This is a early test release of the FreeHDL package.  As such, nothing
is final yet and everything is bound to be changed.  Please tell us
everything that you don't like about this package so that we can
improve it.  You are also allowed to tell us about the things that you
do like, of course, so that we don't make them worse.

Installation
------------

This package should behave like a regular GNUish package.  Generic
installation instructions for such a package can be found in the file
INSTALL.

Right now, there is only enough documentation to get you to run the
included example. Further, some additional info about the
compiler/simulator (e.g. a list of supported VHDL constructs) can be
found in README.v2cc.

Pick a suitable place to install this package in.  The default is
/usr/local.  Then run

    % ./configure --prefix <install-prefix>
    % make
    % make install

The last step will create some directories below <install-prefix> and
will put the created programs and some data files there. However, if
you prefer *not* to install the package (currently the simulator is
very limited, hence you will not be able to use it for "real" work!)
check out README.v2cc for some additional info on how to execute the
compiler/simulator. Further, if your computer should run out of memory
during compilation run "make CXXFLAGS=-g" instead of just "make".

You must make sure that the installed files can be found by your
system (otherwise you will only be able to compile an execute models
copied to the v2cc subdirectory).  That is, the directory
<install-prefix>/bin should be on your path and your linker should be
able to find libraries in <install-prefix>/lib.  We are not yet ready
to isolate you from these technicalities.

Running the example
-------------------

See file "README.v2cc" for some information on how to compile/run
the example vhdl models.


Where to send bug reports / suggestions / comments
--------------------------------------------------

If your report addresses a parser related topics then contact Marius
Vollmer <mvo@zagadka.ping.de>. If it is related to the code generator
or compiler then send an email to Edwin Naroska
<edwin@ds.e-technik.uni-dortmund.de>. If your are not sure send it to
Edwin. He will take care of forwarding your report to the appropriate
recipient.

[ If you are working on FIRE, please update this document accordingly.
  The `I' in the text is mvo@zagadka.ping.de (Marius Vollmer). ]


Differences between FIRE and AIRE
*********************************

The node type definition in fire-chunk.t are an attempt to get as
close to AIRE as reasonable, but there are both large and small
differences that are mostly motivated by my laziness.  But many are
also due to my unhappines with certain AIRE features.

Being fully AIRE compliant is a worthy goal.  But right now, I think
it does not pay off to put much energy into this as there are more
useful goals.

Below is a (incomplete) account of the differences between FIRE and
AIRE, with biased comments.


Framework
---------

With the term `framework', I'm referring to the general constructs
with which FIRE and AIRE try to support their general goals.  This
includes things like the operations that are supported for every node
type, memory management, the precise way how new types are defined,
extensibility, modularity and more.

The framework of FIRE is more advanced than the one of AIRE and I see
no point in going with AIRE in this regard.  There has been much
discussion about this topic on the FreeHDL list, and improvements for
the framework were the original motivation to start with FIRE.  The
advantages of FIRE include:

  - Painless high level definitions
  - Definitions are trivially and confidently machine-readable
  - Run-time type information via the "is-a" predicate.
  - Flexible run-time extensibility
  - Extensibility includes new node types, new visitor functions and
    new node attributes without recompiling.
  - Semi-automatic memory management with a simple garbage collector
  - Inspection facilities that can be used to implement persistence

Please see the libfire sources for ultimate technical details.


General Node Stuff
------------------

The nodes of a abstract syntax `tree' form a graph.  It is useful to
find a definition what a node can be.  It pays to find a simple but
general definition because it makes graph algorithms easier to specify
and implement.  For example, memory management and persitent stores
are much easier to implement when the nodes have been kept
conceptually simple.

FIRE views the syntax graph as a passive, mostly un-mutable data
structure.  It consists of nodes that contain typed pointers to other
nodes, and additional payload.  This simplistic definition is mapped
to a similarily simplistic C++ implementation.  Each node type is
mapped to a C++ struct with the pointers and the payload implemented
as public data members.

In addition to the type id, there is also a predicate that can test
whether a given node is derived from a given type.

AIRE uses C++ syntax to describe the node type definitions.  It does
not seem to have restrictions on what features of C++ one might use in
such a node type definition.  The AIRE spec randomly uses both public
data members and accessor functions.

It is possible to add the accessor functions to FIRE to achieve AIRE
source compatability.  But the underlying simple view of a node as a
passive data structure should remain.  In fact, using *only* accessor
functions would be an improvement for FIRE, but they should not
destroy the fundamental `passiveness' of the graphs, and there should
not be a random mixture between data members and accessor functions.

AIRE often uses the effectively untyped IIR node type.  This makes the
specification less precise and less transparent.  FIRE tries to avoid
the use of IIR and prefers more specialized types instead.  For
example, a IIR_SignalAssignmentStatement in AIRE denotes the target by
an IIR, while FIRE uses IIR_Expression.

FIRE generally tries to put the burden on the frontend.  It chooses a
representation that is convenient for the clients of the frontend.
For example, it requires that all names have been resolved.


Basic Data Types
----------------

FIRE mostly uses the types defined in AIRE.

IR_Kind: this is not an enumeration member, but a pointer to an opaque
information structure.  This should be of no consequence, but IR_Kind
is no longer an integral type that can be used to index arrays, say.

IR_Direction: new type to denote the direction of ranges.

IR_String: new type to hold a constant string and do memory management
for it.


IIR Base Class
--------------

The get_kind and get_kind_text functions of AIRE are named kind and
kind_name in FIRE, for no good reasons.

No source location methods are implemented.  Instead, a IIR node
points to a IIR_PosInfo node.  Predefined IIR_PosInfo types include
IIR_PosInfo_TextFile and IIR_PosInfo_Sheet.  It is possible to
trivially implement new kinds of position information.

IIR_Statement is not implemented.


IIR_DesignFile & IIR_Comment Derived Classes
--------------------------------------------

Unimplemented.  Comments are ignored completely and DesignFiles are
not mapped into the graph.  The largest unit for a graph is a design
unit.  Design files are handled by the frontend.


IIR_Literal Derived Classes
---------------------------

IIR_TextLiteral has an IR_String attribute called `text' that holds
the characters of the literal.  IIR_Identifier, IIR_CharacterLiteral,
and IIR_StringLiteral are derived from TextLiteral without adding any
new features.  There is no `get' method.

There is no IIR_BitStringLiteral because the lexer converts bit string
literals immediately into IIR_StringLiterals.  It would be better to
retain bit string literals unchanged to produce better error messages.

IIR_IntegerLiteral just uses a IR_String for the value, without any
support routines.  When we want to have arbitrary integers, we should
be using a bignum package (like GNU mp) and remove
IIR_IntegerLiteral32, IIR_IntegerLiteral64 completely.  The same
applies to IIR_FloatingPointLiteral and derived types.

There are additional types IIR_AbstractLiteral,
IIR_AbstractIntegerLiteral, and IIR_AbstractFloatingPointLiteral to
further structure the hierachy.


IIR_Tuple Derived Classes
-------------------------

IIR_AssociationElement: Moved actual from AEByExpression to here.
Added formal_conversion and actual_conversion.  When actual is
IIR_OpenExpression, then it's an AEOpen, else it's an AEByExpression.
The types AEByExpression and AEOpen are there and correctly used, too.

IIR_BreakElement: unused/unimplemented.

IIR_CaseStatementAlternative: Moved ChoiceList from CSAByChoices to
base class.  CSAByExpression, CSAByChoices, CSAByOthers are not used.
It's all in the ChoiceList.  This could be done AIRE style.

IIR_Choice: added CByExpression, CByRange, CByOthers.  Choice is an
abstract class.  This could be done AIRE style.

IIR_ConditionalWaveform: unused/unimplemented.  A conditional signal
assignemnt is expanded into its equivalent process.

IIR_ConfigurationItem: derived from IIR_DeclarativeRegion for historic
reasons.  Needs to be cleaned up.

IIR_ComponentConfiguration: has no `name' element.

IIR_Designator*: unused/unimplemented.

IIR_Elsif: unused/unimplemented.

IIR_SelectedWaveform: unused/unimplemented.  A selected signal
assignemnt is expanded into its equivalent process.

IIR_Simultanous*: unused/unimplemented.

IIR_ElementAssociation, IIR_IndexedAssociation: new, used for
aggregates.

IIR_AttributeValue: new, used for user defined attributes.


Lists
-----

Lists are currently a cheap cop out.  They don't implement any of the
baroque ADT stuff from AIRE, but are simply singly linked lists with a
first and rest pointer.  I think the AIRE interface could be provided
but is not very useful.

Not all lists have been implemented, only those that are actually
used.  Some new lists are also there.

IIR_GenericList, IIR_PortList: not used because they are not derived
from IIR_InterfaceList and I want to have `generic' functions that can
work both on a GenericList and a PortList.  This is no big loss.


IIR_TypeDefinition and IIR_NatureDefinition Derived Classes
-----------------------------------------------------------

Here are many significant deviations from AIRE.  I had especially
little respect when I did this part of FIRE and it shows.

All IIR_TypeDefinitions have lost their "Definition" suffix.  Thus,
IIR_TypeDefinition is now IIR_Type.  This is easy to revert of course.

Types have a pointer to their declaration.

Scalar types have no range (it is contained in their primary
subtype(?)).

Subtypes are arranged differently.  Subtypes form their own hierachy:

 IIR_Type:                Type base
   IIR_Subtype:           Type immediate_base, FunctionDeclaration res_func
      IIR_ScalarSubtype:  Range range
      IIR_ArraySubtype:   TypeList constraint

This avoids gratitous duplication of code for the original multitude
of similar Subtypes that weren't related hierachically.

The range of a ScalarSubtype is denoted by the IIR_Range hierachy.
This allows not only for explicit ranges but also for ranges denoted
by attributes.

There is no IIR_RangeTypeDefinition.

Record and Array types are derived from the new IIR_CompositeType.

ArrayTypes are not restricted to one dimension.  This is important.
We can either support it directly in the spec or everybody is forced
to non-portably kluge around it.  See SAVANT.

IIR_Signature: unused/unimplemented.

IIR_NatureDefinition: unused/unimplemented.


IIR_Declaration Derived Classes
-------------------------------

In addition to the declarations, we also maintain the nested
declarative regions in the graph, so that backends can walk them in a
generic way.

IIR_Declaration: moved attributes to here and use AttributeValue
instead of AttributeSpecification.  Has pointer to containing
IIR_DeclarativeRegion.

IIR_DeclarativeRegion: new.  Chains declarative regions of one scope
together with a `continued' pointer.  Has list of contained
IIR_Declarations.  This means that declarations that have their own
IIR_DeclarationList in AIRE are now derived from IIR_DeclarativeRegion
and inherit the list.  Makes much more sense.

IIR_LoopDeclarativeRegion: new.

IIR_FunctionDeclaration: pure is just a boolean.

IIR_EnumerationLiteral: has no position info.

IIR_NatureElementDeclaration: unused/unimplemented.

IIR_SubtypeDeclaration: derived from TypeDeclaration.

IIR_NatureDeclaration: unused/unimplemented.

IIR_SubnatureDeclaration: unused/unimplemented.

IIR_ObjectDeclaration: added initial_value.

IIR_ConstantDeclaration, IIR_VariableDeclaration,
IIR_SharedVariableDeclaration, IIR_SignalDeclaration: no value, use
initial_value of ObjectDelcaration.  The graph is not intented to be
used at simulation-time.

IIR_TerminalDeclaration, IIR_QuantityDeclaration: unused/unimplemented.

IIR_InterfaceDeclaration: derived from IIR_ObjectDeclaration.  Added
`boolean buffer'.  No value, see IIR_ConstantDeclaration, et al.

IIR_TerminalInterfaceDeclaration, IIR_QuantityInterfaceDeclaration:
unused/unimplemented.

IIR_AliasDeclaration: derived from IIR_ObjectDeclaration.  No name,
initial_value refers to aliased object (via ObjectReference,
presumably).

IIR_ComponentDeclaration: derived from IIR_DeclarativeRegion.  This
probably can be fixed but it doesn't hurt either.

IIR_Group*: unused/unimplemented.  Needs fixing.

IIR_LibraryUnit: added library_name to help identify units.

IIR_EntityDeclaration: has no `architectures' pointer.  The full list
of architectures can not be determined when parsing the entity
declaration and the graph should not be mutated later.  Finding all
architectures of an entity is a useful thing but I do not consider it
to be the job of the frontend. More often than not, the architectures
aren't needed anyway.

IIR_PackageDeclaration: like architectures of entities, I consider it
to be out of the scope of the frontend to find the package body for a
package.

IIR_PackageBodyDeclaration: rather, a package body points back to its
package declaration.

IIR_PhysicalUnit: added pointer to defining PhysicalType.

IIR_AttributeSpecification: unused/unimplemented.  Use AttributeValue
instead, much simpler.

IIR_ConfigurationSpecification: has no component_name, entity_aspect,
and instantiation_list but simply a `LibraryUnit unit'.

IIR_DisconnectSpecification: used for only one signal, which is
denoted by `IIR_Expression guarded_signal'.

IIR_LibraryClause: has no logical_name.

IIR_UseClause: has no selected_name, but a direct pointer to the used
unit.


IIR_Name derived Classes
------------------------

No Name class is used/implemented.  All references are resolved.
Attributes are implemented as Expressions.


IIR_Expression Derived Classes
------------------------------

No MonadicOperator or DyadicOperator is implemented.  They are
expressed by function calls that point to the declaration of the
operator.

We need a number of new node types to refer to objects and literals.
AIRE seems to allow literals and objects directly in expressions, but
FIRE doesn't.  This and most of the other changes are done to make the
life of the backend easier.  By using these additional `indirect'
classes, we can be more precise and explicit.

IIR_AbstractLiteralExpression: new, used to refer to IIR_AbstractLiterals.

IIR_PhysicalLiteral: derived from AbstractLiteralExpression.

IIR_ArrayLiteralExpression: new, used to refer to IIR_StringLiterals.

IIR_EnumLiteralReference: new, used to refer to
IIR_EnumerationLiterals.

IIR_NullExpression, IIR_OpenExpression: new, useful.

IIR_Aggregate: split into RecordAggregate and ArrayAggregate with
their own specialized Element/IndexedAssociations.

IIR_OthersInitialization: unused/unimplemented.

IIR_FunctionCall: `implementation' is called `function', for no good
reason.

IIR_ObjectReference: new, used to refer to objects.  The hierarchy is

    ObjectReference
      SimpleReference:        ObjectDeclaration object
      AccessReference:        Expression access
      RecordReference:        Expression record, ElementDeclaration element
      GenericArrayReference:  Expression array
        ArrayReference:       ExpressionList indices
        SliceReference:       Range range

Builtin attributes are also derived from Expression.  They are mostly
copied verbatim from the old VAUL definitions.  There is no similarity
to the unimplemented AIRE Attribute classes.  The similarity could be
achieved, but they should remain Expressions.


IIR_SequentialStatement Derived Classes
---------------------------------------

IIR_SequentialStatement: moved label from unimplemented IIR_Statement
to here.

IIR_ProcedureCallStatement: has no procedure_name, points directly to
ProcedureDeclaration.

IIR_IfStatement: does not use ElsIf.  Instead, if/elsif chains are
rewritten into equivalent nested ifs.

IIR_LoopStatement: new, used as common base of ForLoopStatement and
WhileLoopStatement.  Does not have declaration list, but points to
LoopDeclarativeRegion.

IIR_LoopControlStatement: new, used as common base of NextStatement,
ExitStatement.


IIR_ConcurrentStatement Derived Classes
---------------------------------------

IIR_ConcurrentStatement: derived from DeclarativeRegion, for
historical reasons.  Needs to be fixed, maybe.

IIR_ProcessStatement: added `boolean guarded'.

IIR_ConcurrentProcedureCallStatement, ConcurrentAssertionStatement,
ConcurrentConditionalSignalAssignment,
ConcurrentSelectedSignalAssignment: unused/unimplemented.  They are
rewritten into their equivalent ProcessStatement.

IIR_ComponentInstantiationStatement: added pointer to
ConfigurationSpecification that configures this thing.

IIR_ConcurrentGenerateStatement: new, used as common base class of
ConcurrentGenerateForStatement and ConcurrentGenerateIfStatement.


IIR_SimultanousStatement Derived Classes
----------------------------------------

unused/unimplemented.

[This is the README from an early prototype of the gen-nodes tool.  It
 is quite out of date with regard to the details, but the general
 ideas still apply.]

This is a demonstration of my ideas about an extensible framework for
representing an abstract syntax tree (actually a graph).

The goal is to be able to specify a hierachy of node types and define
`generic' functions on them.  A generic function can have different
implementations for different types.  These implementations are called
the methods of a generic function.  The decision which method to
invoke when a generic functions is called is made at run-time.

We want to be able to define new generic functions without changing
the definition of the types that they work on.  Therefore, we can not
use the virtual functions of C++.  A virtual function is part of the
type it works on and it is therefore necessary to change the type
itself when adding new virtual functions.  This means frequent and
inconvenient recompilation.

Furthermore, such changes to the type definitions have to be carefully
coordinated when more than one party wants to make some.


My proposed solution to this dilemma is to design a new, minimal OOP
model and implement it in C++.  To make it useable, we need a tool
that generates most of the boilerplate code for us.

The demonstration uses Scheme (a Lisp dialect) for implementing the
boilerplate generating tool and Scheme syntax for specifying the input
to it.  I know that this is not the most popular thing to do, but it
was easiest for me.  Therefore...

*   You need to have Guile installed to play with the tool.  Version  *
*   1.2 should work fine.  You can find it on your local GNU mirror.  *


- How it works

The node features are defined in `chunks'.  Each chunk can contain new
node type definitions and generic functions with their methods.  You
can also extend node types with new attributes.

The chunks are independent from one-another.  That is, you can mix and
match chunks at link time without having to recompile them.

The cornerstone of the system is `gen-nodes'.  This is the tool that
reads the description of a number of chunks and outputs C++ code for
their implementation.

- The chunk descriptions.

The files that gen-nodes reads contain the description of the chunks
in Scheme syntax.

A chunk is started with this statement:

    (chunk NAME OPTS..)

it ends at the end of input or when the next chunk begins.  NAME
should be a valid C++ identifier and unique among all chunks.

You can define new node types:

    (defnode NAME (BASE)
       SLOTS...
       OPTS...)

The NAME is the name of the node type and should be a valid and unique
C++ identifier.  BASE is the name of a previously defined node type
that will be used as the base for the new type.  You can omit BASE
(but not the parentheses around it).

LINKS-AND-ATTRS can specify links to other nodes

    (link NODE LINK-NAME)

where NODE is the type of the node that is pointed to by the link
named LINK-NAME.  The generated C++ struct will have a member that is
a pointer to a struct generated for NODE.

You can also specify attributes

    (attr TYPE ATTR-NAME)

where TYPE is string enclosed in double quotes that is a valid C++
type, such as "char*" or "int".  The generated C++ struct will have a
member with name ATTR-NAME and type TYPE.


Generic functions are specified with

    (defgeneric RET-TYPE GENERIC-NAME EXTRA-ARGS)

This will generate a C++ function named GENERIC-NAME with return type
RET-TYPE (which should be a string just like a attribute type).  The
first argument of this function is a pointer to a node struct.  The
run-time type of this node is used to dispatch to one of the methods
of this generic function, see below.  The rest of the arguments of the
function are specified by EXTRA-ARGS.  This should be a list like

    ((TYPE ARG-NAME) (TYPE ARG-NAME) ...)

When the generic function should not be global but be contained in a
class, you specify the qualified name of it (i.e. including the class
name) as a list of symbols.  The qualified name
"outer_class::inner_class::func" would be written as

    (outer_class inner_class func)

Methods are defined with

    (defmethods GENERIC-NAME NODES...)

For each of the node types listed in NODES, an individual method is
defined.  Methods are translated into ordinary C++ functions whose
name is formed by concatenating the string "m_" and the GENERIC-NAME.
Their first parameter is a pointer to the node type they belong to and
the rest is specified by the EXTRA-ARGS of the generic declaration.

When a generic function is invoked on a node type that has no method
defined for it, the method for the nearest base type that has a method
is invoked.  When no such base type exists, the program is aborted.


You can extend existing nodes with

    (extnode NODE
       ATTRS...)

NODE is the name of the node that you want to extend and ATTRS is a
list of attribute definitions, just like for defnode.  For every
specified attribute a function will be generated according to this
template:

    TYPE& NAME (NODE*);

TYPE is the type of the attribute, NAME is the name of the attribute
and NODE is the struct generated for the extended node.  The function
will return a reference to the storage reserved for the attribute.


You can add arbitary lines to the generated output with

    (header-add LINES...)

and

    (impl-add LINES)

You can split the chunk definitions into several files and use

    (include FILE)

to include them.


- Invoking gen-nodes

    gen-nodes CMD CHUNK IN-FILE OUT-FILE

Gen-nodes reads the IN-FILE (which should contain the descriptions in
the format explained above) and generates output for CHUNK in
OUT-FILE, according to CMD.

When CMD is `header', gen-nodes writes a header file to OUT-FILE that
should be included by the users of the CHUNK.  When it is `impl', it
writes the implementation of CHUNK.

Design libraries and v2cc
-------------------------

v2cc does not have a opaque notion of design libraries.  VHDL files
are not pre-analyzed and checked into some library data base.
Instead, whenever a reference to a design unit needs to be made, v2cc
parses the VHDL code of that design unit from fresh.  Therefore, it
needs to be able to find the source file of a design unit given the
VHDL name of that unit.

Thus, as far as v2cc is concerned, a design library is a mapping from
VHDL identifiers to file names.  There is also a mapping for getting
library names from mapping files.

Such a mapping is specified via a "mapping file".  It contains a list
of pattern rules that each transform a certain class of identifiers
into file names.

The syntax of a mapping file is:

  Lexical:

     litchar: 'a'..'z' | 'A'..'Z' | '0'..'9' | '_' | '/' | '-' | '.' escchar

     escchar: '\' char

     whitespace: ' ' | '\n' | '\v' | '\t' | comment

     comment: '#' any_character* '\n'

     opchar: ':' | ',' | '(' | ')'

     specchar: every printable char except litchar, whitespace and opchar

     symchar: litchar | specchar

     symbol: symchar+

  Grammar:

     mapping: version patternrule*

     version: "v2cc_mapfile" "0"

     patternrule: symbol [ ':' symbol ]

Comments are ignored.

A mapping files specifies a sequence of pattern rules.  When
transforming an indentifier, each rule is tried in turn and the first
one that matches is choosen.

A rule looks like

  pattern: filename

When the ": filename" part is omitted, it defaults to "patternEXT"
where "EXT" is determined by the user of the mapping file.

The "pattern" can contain the special character "<" which introduces a
`wildcard'.  The "<" must be followed by a ">", with arbitrary
characters inbetween.  These characters form the name of the wildcard.
A wildcard matches any sequence of characters.  There can be any
number of wildcards in the pattern, but each must have a unique name.

The "filename" can also contain the character "<", followed by a name,
followed by ">".  There, it introduces a `wildcard substitution'.  It
will be replaced with the characters that matched the wildcard with
the same name in "pattern".  When there is no wildcard in "pattern"
with the right name, it will be replaced with nothing.  While doing
this replacement, the characters "#" and "/" are replaced as "##", and
"#-" respectively.  No other character translations are done, so if
you have funny characters in your VHDL identifiers, you will have
funny characters in your filenames.

Before doing the comparison with the patterns, the VHDL identifier is
brought into a canononical form: when it is not an abstract
identifier, all its characters are down-cased.

When the resulting filename is relative (does not begin with "/"), it
is prefixed with the directory of the mapping file.

A non-existent mapping file is equivalent to the single rule

  <>

An empty mapping file is just that: an empty mapping.

The mapping does not need to be reversible.  It is OK when multiple
identifiers map to a single filename.

No special character besides "<" and ">" is valid in "pattern" or
"filename".  They are reserved for future extensions.


The mapping files for going from design unit names to filenames are
found by looking into directories specified by the `v2cc library
path'.  You can use the environment variable V2CC_LIBRARY_PATH and
command line options to define the path.  When the environment
variable is not set, it defaults to a value that makes the standard
libraries available that are distributed and installed with v2cc
itself.  When it is set, it completely overwrites this default value.

The variable V2CC_LIBRARY_PATH consists of ":" separated filenames.
The filename "*" is replaced with the default value mentioned above.

In addition to the environment variable, you can use the "-L libdir"
command line option with v2cc.  The directories specified with "-L"
are added in front of the ones specified by V2CC_LIBRARY_PATH.  In the
final library path, they appear in the same order as on the command
line.

Looking for a design unit named UNIT in a library named LIB is done
like this:

     for each component of the library path, L
       if L is a regular file
         set LMAP to L
       else if L is a directory
         set LMAP to L/v2cc.libs
       else
         continue with next component
       translate LIB into FLIB using LMAP with EXT=""
       if FLIB.vhdl exists
         terminate with FLIB.vhdl as the result
       if FLIB.v2cc exists
         set UMAP to FLIB.v2cc
       else if FLIB is a directory
         set UMAP to FLIB/v2cc.units
       else
         continue with next component
       translate UNIT into FUNIT using UMAP with EXT=".vhdl"
       terminate with FUNIT as the result
     terminate unsuccessfully


This mechanism is used for all design units that are referenced from
within VHDL code (or via other means).  There is a complication with
architectures and package bodies, though, because they are not
uniquely identified by a single identifier.  For them, a artifical
identifier is constructed.  Architectures get names of the form

    <entity>(<architecture>)

while package bodies become

    <package>(body)

For example, "architecture struct of model" is turned into
"model(struct)" and "package body misc" is turned into "misc(body)".

When a design file contains multiple design units, they are all
parsed, checked for correctnes and remembered, but only the needed
unit will be used for code generation.  That is, when a design file
contains both a package header and a package body and the package
header is referenced from another design unit, no code will be
generated for the package body.  When one of the ignored units will be
referenced later in the same invocation of v2cc, the design file will
not be read again because all design units are retained in core.


Examples
--------

The simplest situation is when you have no mapping files at all.  A
design library is then a directory on your library path.  The name of
that directory is that of the library in VHDL.  Each file in that
directory with a ".vhdl" extension is used for a design unit with the
same name as the file without the extension.

Say you have this directory structure

    somedir/
      std/
        standard.vhdl
        textio.vhdl
      ieee/
        numeric_bit.vhdl
        std_logic_1164.vhdl

When you put "somedir" into your library path, you have access to the
design units

       STD.STANDARD
       STD.TEXTIO
       IEEE.NUMERIC_BIT
       IEEE.STD_LOGIC_1164

In this situation, you have one file per design unit.  When you have
one file per design library, it would look like this

    somedir/
      fmf.vhdl

All references to design units in the FMF design library would be
routed to "fmf.vhdl".




Considerations
--------------

- Simplicity

  The mapping is intended to be simple.  If you find yourself doing
  complicated things or wanting complicated extensions, we should
  probably rethink the mapping file completely.  Maybe it is better to
  be able to specify an external program that gets called to do the
  mapping.

- Extensibility

  Simple things within the pattern rules can be done by defining a
  meaning for other special characters.

  Broader changes to the grammar of the file should be marked with a
  different version number, or maybe even a different format name.

- Efficiency

  It might be that the repeated parsing of VHDL source code will be an
  unduly overhead.  This might not really be the case (Edwin says the
  C++ compiler takes much longer anyway), but if it turns out to be a
  problem, the solution would be to cache the results of previous
  parsing runs on disk.  This should be done transparent to the user
  (although the user should of course be able to detect and correct
  problems with the caching like full disks or denied write permission
  to the caching directoy).

- Automatic generation

  Mapping files are meant to be written by hand.  If you are thinking
  about some automatic mechanism by which to generate them, it is
  probably better to extend the capabilities of the mapping files so
  that your new mechanism can be selected.

0. Table of content
-------------------

This document is organized as follows:

	1. Running the compiler
	1.1 Compiling ieee.std_logic_1164 and ieee.numeric_std
	1.2 Compiler options
	2. Supported VHDL subset
	3. Supported simulation commands
	3.1 Controlling simulation from the command line
	4. Bug reports


1. Running the compiler
-----------------------

Change to subdirectory "v2cc". Here you will find a simple perl script
"gvhdl" which performs all necessary steps in order to create a
simulation binary from a VHDL source file. The command

    %./gvhdl y.vhdl

compiles "y.vhdl" into a executable "y". Type

    %./y

to start the simulator. For more info on how to control the simulator
see section 3.

Note that all VHDL source files must end with ".vhdl".

If you would like to build a simulator for a model consisting of
several modules (entity + architecture or package + package body) you
may put all the modules into a single file and compile it as
described above. The top level module should be placed at the end of
the file.

Another option is to create a separate file for each module. The files
should be named after the entity/package it stores. Then, each module
must be compiled separately:

    %./gvhdl -c <module_1>.vhdl
    %./gvhdl -c <module_2>.vhdl
    ...
    %./gvhdl -c <module_1>.vhdl

Finally, the top level module is compiled and linked via:

    %./gvhdl <top_module>.vhdl <module_1>.o ... <module_n>.o


1.1 Compiling ieee.std_logic_1164 and ieee.numeric_std
------------------------------------------------------

If package ieee.std_logic_1164 or ieee.numeric_std are used within a
design then the corresponding object files must be added when
compiling the top level design. I.e., when compiling the top level
module of your design add "../ieee/numeric_std.o
../ieee/std_logic_1164.o" (order is important!) to the list of modules
to link (or just "../ieee/std_logic_1164.o" if you do not use
numeric_std):

    %./gvhdl <top_module>.vhdl <module_1>.o ... <module_n>.o \
	../ieee/numeric_std.o ../ieee/std_logic_1164.o

Make sure to list numeric_std.o before std_logic_1164.o. Otherwise,
the link stage may fail!

As an alternative method you may use the "--libieee" option to add
all ieee libraries (that currently come with the compiler).

Directory "v2cc" contains two example models "top.vhdl" and
"model4.vhdl" which make use of std_logic_1164 and numeric_std. To
compile "top.vhdl" execute:

    %./gvhdl -c adder.vhdl
    %./gvhdl top.vhdl adder.o ../ieee/std_logic_1164.o

or

    %./gvhdl -c adder.vhdl
    %./gvhdl top.vhdl adder.o --libieee


To compile "model4.vhdl" run

    %./gvhdl model4.vhdl ../ieee/std_logic_1164.o ../ieee/numeric_std.o

or simply

    %./gvhdl model4.vhdl --libieee


1.2 Compiler options
--------------------

gvhdl now accepts the following options:

    -g : adds debugging info (i.e., the simulator can be debugged
        using VHDL source file line numbers). This also enables
        outputting some stack trace info in case of an runtime error.
    -G : same as -g but no VHDL source file and line number info
        is added to the executable (this is to support debugging
	code generated by the compiler).
    -c : compile only, do not link
    -l <lib_name> : compile design into library <lib_name>.
    -L <vhdl_lib> : path to VHDL library root directory. Within this
	directory the compiler search for a file named v2cc.libs.
	v2cc.libs translates library unit names to directories.
	Note that more than one vhdl_lib may be provided
	(see also section "VHDL libraray mapping").
    --libieee : add ieee libraries (std:logic_1164, numeric_std, ...)
	to executable.

All other options not directly recognized by gvhdl are forwarded to
g++.  Hence, in order to optimize the generated code for speed add
"-O3" to the list of gvhdl options! E.g.,

    %../v2cc/gvhdl -O3 -c -l ieee std_logic_1164.vhdl
    %../v2cc/gvhdl -O3 -c -l ieee numeric_std.vhdl

executed within subdir "ieee" will create speed optimized versions of
std_logic_1164 and numeric_std. However, note that the code of these
packages is generated form the the ORIGINAL ieee VHDL source. Currently,
there are no special hand optimized versions of it (this is one of the
tasks to be done in the future).


1.3 VHDL library mapping
--------------------------------

In order to support mapping from VHDL unit names to directiores, a set
of v2cc.libs files may be used. The directory where a v2cc.libs file
is stored is passed over to the compiler using the "-L <vhdl_lib>"
compiler switch. Note that several vhdl_lib directores may be
specified.

The content of a v2cc.libs file looks like

v2cc_mapfile 0
work : vhdl
dummy : /home/edwin/work/test/dummy

The first line ist just used to check for a vaild vhdl mapping
file. The next two lines associate

- VHDL libraray "work" with subdirectory "vhdl" and
- VHDL libraray "dummy" with subdirectory /home/edwin/work/test/dummy.

If the subdir path does not start with "/" then it is relative to the
directory the corresponding v2cc.libs resides in. Here, VHDL library
"work" is mapped to "<vhdl_lib>/vhdl". If a model or package named
"comp" is referenced then the compiler will look into the directores
of all VHDL libraries that are currently visible and searches for a
file named "comp.vhdl".

For more details about the v2cc.libs format please read with
README.libraries.


1.3.1 Example VHDL library setup
--------------------------------

As an example assume that all VHDL libraries are mapped into subdirs
starting from root directory "/foo". Further, assume that there are
VHDL libraries named "lib1" and "lib2". They shall be mapped to subdir
"/foo/lib1_dir" and "/foo/lib2_dir". Hence, the file/directory
structure is as follows:

/foo  			<-  library root directory
/foo/v2cc.libs  	<-  mapping control file
/foo/lib1_dir		<-  library dir for VHDL library lib1
/foo/lib1_dir/comp1.vhdl <- file that contains VHDL model comp1
/foo/lib2_dir		<-  library dir for VHDL library lib2
/foo/lib2_dir/comp2.vhdl <- file that contains VHDL model comp2

Then, file "/foo/v2cc.libs" should contain:

v2cc_mapfile 0
lib1 : lib1_dir
lib2 : lib2_dir

In order to compile a design named comp1 (stored in file comp1.vhdl)
into VHDL library lib1 goto subdir "/foo/lib1_dir" and execute:

    %gvhdl -c -L .. -l lib1 comp1.vhdl

Note that option "-l lib1" forces the compiler to associate the model
stored in "comp1.vhdl" with VHDL libraray lib1.  Note further, that
the compiler switch "-L .." specifies the path to the directory where
"v2cc.libs" is stored. You may also specify an absolute path:

    %gvhdl -c -L /foo -l lib1 comp1.vhdl

Note that comp1 should reside in a file named "comp1.vhdl".

If lib2 contains a design comp2 that makes use of comp1 from lib1 then
goto "/foo/lib2_dir" and run the following command to create an
executable for model comp2:

    %gvhdl -L .. -l lib2 comp2.vhdl ../lib1_dir/comp1.o


2. Supported VHDL subset
------------------------

Currently, FreeHDL does not support the entire VHDL'93 standard. The
following incomplete list gives an overview on what is currently (not)
supported (note that the compiler is not tested very intensively;
hence, expect to hit a lot of bugs in the compiler and simulator
system):

- Individual association of formals of composite type are currently
not supported.

- VHDL'93 as well as VHDL'87 file support has been added.

- Shared variables are currently not supported.

- Attributes transaction, quiet, stable and delayed are
currently not supported.

- User defined attributes are currently not supported.

- Groups are currently not supported.

- Guarded signal assignments are currently not supported.

- Currently drivers cannot be switched off.



3. Supported simulation commands
--------------------------------

After the simulator has been started a short summary of the available
commands are printed to the screen:

  c <number> : execute cycles = execute <number> simulation cycles
  n          : next = execute next simulation cycle
  q          : quit = quit simulation
  r <time>   : run = execute simulation for <time>
  d          : dump = dump signals
  doff       : dump off = stop dumping signals
  don        : dump on = continue dumping signals
  s          : show = show signal values
  dv         : dump var  = dump a signal from the signal lists
  ds         : dump show  = shows the list of dumped signals
  nds        : number  show  = shows the number  of dumped signals
  dc [-f <filename>] [-t <timescale> <time unit>] [-cfg <translation file>] [-q]
                : configures dump process

Note that signals are dumped into a file (default file name is
"wave.dmp") in VCD format. This file format should be accepted by each
VCD waveform viewer. The file name is set to "wave.dmp" but may be
changed using "dc -f <new_file_name>". However, make sure to execute
"dc -f ..." before executing "d".

Here is a small protocol of a simulation run (user input is marked
with "<--"):

   %./y
Available commands:
  c <number> : execute cycles = execute <number> simulation cycles
  n          : next = execute next simulation cycle
  q          : quit = quit simulation
  r <time>   : run = execute simulation for <time>
  d          : dump = dump signals
  doff       : dump off = stop dumping signals
  don        : dump on = continue dumping signals
  s          : show = show signal values
  dv         : dump var  = dump a signal from the signal lists
  ds         : dump show  = shows the list of dumped signals
  nds        : number  show  = shows the number  of dumped signals
  dc [-f <filename>] [-t <timescale> <time unit>] [-cfg <translation file>] [-q]
                : configures dump process
Simulation time = 0 fs + 0d
> dc -q                              <-- suppress warnings/verbose messages
> d                                  <-- dump all signals into wave.dmp
> run 100 ns                         <-- run for 100 ns
Run simulation for which time span?
Simulating model to time 100 ns
Simulation time = 100 ns + 0d

106 processes were executed.
138 transaction were created.
> quit                               <-- quit simulation


3.1 Controlling simulation from the command line
------------------------------------------------

Simulation can be controlled via the command line parameter '-cmd
"cmd1; cmd2; ..."' where 'cmd1', 'cmd2', ... are simulation commands
as described in the previous section. Note that each command must be
separated by ';'. E.g., executing

   %./y -cmd "d;run 1000 ns;q;"

will start simulation program 'y', dump all signals and run simulation
for 1000 ns. Finally, simulation is terminated. Actually, the last
command 'q;' is optional as the simulator automatically terminates as
soon as the last command has been executed.


4. Bug reports
--------------

Please send simulator or code generator related bug reports or
comments to Edwin Naroska <edwin@ds.e-technik.uni-dortmund.de>. If you
are not sure to what your problem is related to send your email to
Edwin as well. He will take care of forwarding your report or comment
to the appropriate recipient.

This is the source for VAUL.

VAUL is cryptic for Vhdl Analyzer and Utility Library.  Devlopment has
been initiated in 1994 by the University of Dortmund, Department for
Electrical Engineering, AG SIV, Heja BVB.  Marius Vollmer
<mvo@zagadka.ping.de> has written most of it, with guidance from
Ludwig Schwoerer <ls@nt.e-technik.uni.dortmund.de>.  Part of this work
is based upon work done by Thomas Dettmer and others.  See the file
AUTHORS for details.  Many thanks to all who have contributed,
especially to Professor Schr�der, who has allowed me to distribute my
work under the terms of the LGPL.

VAUL can be used to parse and analyze arbitrary VHDL code.  The result
is an abstract syntax graph, which is represented as a collection of
C++ objects, tightly connected by pointers. All names used in the VHDL
code have been resolved to their respective declarations (including
overloaded function names) and types have been checked (excluding
subtype constraints).

It is now a serious canditate for the VHDL frontend of the FreeHDL
project, see http://www.linuxeda.com/~freehdl.

* STATUS

Currently, the analyzer understands enough of VHDL to successfully
parse and type-check the IEEE std_logic_1164 packages (including
"arith", "signed", "unsigned", "textio", etc.), the VITAL packages
(timing and primitives), all models of the Free Model Foundation that
I have tested, and probably much more. It generates quite useful error
messages, but could do better, of course.

Many minor semantic checks are not done or the details are probably
incorrect.

The documentation is mostly lacking, unfortunately, but things are
getting better.  Right now, the most useful source of information
about the generated syntax graph is probably "v2c.cc", the source code
of the `VHDL to pseudo-C' translator.

* CONTENTS

libfire/
    Libfire contains the definition of the abstract syntax nodes, plus
    support routines.  "Fire" stands for "Feeble Intermediate
    Representation with Extensibility".  It is of course a pun on
    "AIRE", the "Advanced Intermediate Representation with
    Extensibility".  I hope to make libfire AIRE compliant sometimes
    in the future, but right now, it is only very superficially
    similar to AIRE.

    Libfire has some unique features for extensibility that I think
    are superior to the proposed AIRE mechanisms.  So we wont need the
    extensibility of AIRE for implementing useful applications of the
    syntax nodes, but it would still be nice to be compatible to
    existing and upcoming AIRE compliant software.

    Libfire is [will be] documented in the file `doc/libfire.texi'.

libvaul/
    This is the actual VHDL frontend, packaged as a library.  Included
    is a sample application, the superficial translator from VHDL to
    pseudo C, "v2c". There are also a few VHDL files for testing in
    vlib/.

    PLEASE NOTE: The files in vlib/ are meant for testing ONLY and
    might therefore contain gratuitous errors and lies.  Please get
    them afresh from their original sources if you want to use them
    for real.

    Libvaul uses libfire for its intermediate representation, of
    course.  It adds some extensions of its own.

    Right now, the relationship between libfire and libvaul is
    somewhat perverted.  Libfire does not contain anything really
    useful and the bulk of the syntax nodes is defined as `extensions'
    in libvaul.  This will change over time, of course.

doc/
    Here is some documentation.

* COMPILING

Basically, what you do with GNU packages:

    % ./configure
    % make

More complete (but generic) instructions are in INSTALL.

This version uses automake/libtool as its build environment.  But as
long as you dont want to change the Makefiles, you don't need to have
them installed.

The C++ rendition of the abstract syntax node definitions is generated
by a tool written in Guile Scheme.  The generated files are contained
in the distribution, so you shouldn't need to run the Scheme program
unless you modify the definitions in the *.t files.  Guile version 1.2
from your local GNU mirror should be fine.

You probably need GNU C++ (2.6.3 and up) and maybe some other GNUish
tools. It should compile at least on GNU/Linux, SunOS 4 and 5, maybe
with some tweaking.

* RUNNING

There is no real documentation for the library or the example
programs.  The doc/ directory contains the beginnings of libfire.texi,
the documentatzion for the general syntax graph support and the
particular node types used by VAUL, but it is still very incomplete.
But until then, here are some hints about how to run `v2c' on the
sample VHDL files.

There are some VHDL files in libvaul/vlib/* that can be used to test
`libvaul'. Each VHDL design library is contained in a separate
subdirectory.

    vlib/std/
	The packages std.standard and std.textio.

    vlib/ieee/
	The IEEE std_logic_1164 packages and the VITAL timing and
	primitive packages.

    vlib/fmf/
	Some packages and models from the Free Model Foundation.

Libvaul does not store its intermediate representation of the VHDL
source code on disk.  That means that whenever a design unit is needed
during analysis, the source code for it has to be found and
reanalyzed.  Only two kinds of design units are ever needed during
analysis: packages that are mentioned in USE clauses, and entities
that are mentioned in binding indications. [right?]

Libvaul can not find the needed source code by itself, it needs help
from the application.  v2c has a very simple rule for finding the
source code.  For a package or entity named UNIT, that is contained in
a design library named LIB, it looks for "vlib/LIB/UNIT.vhd" and
"vlib/LIB/UNIT.vhdl".

    % cd .../libvaul

	v2c knows that the libraries are in vlib/

    % ./v2c -lfmf vlib/fmf/nlb6201.vhd

	`-lfmf' means: use the "fmf" library as the working library.