v2cc.libs - VHDL library mapping file for the FreeHDL compiler/simulator.
is a compiler/simulator suite for the hardware description
language VHDL. VHDL'93 as well as VHDL'87 standards are supported.
translates the original VHDL source FILEs into C++. Then, the C++
source can be compiled and linked to the kernel to build the simulation
program. Starting the generated executable will simulate the corresponding
VHDL model. The actual build process to generate the simulator from the VHDL
source is a complex process which is handled by the gvhdl
FreeHDL does not have a opaque notion of design libraries. VHDL files are not
pre-analyzed and checked into some library data base as in other VHDL
compiler/simulator systems. Instead, whenever a reference to a design unit
needs to be made, FreeHDL 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 FreeHDL 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
The syntax of a mapping file is:
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
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
identifier, each rule is tried in turn and the first one that matches is
A rule looks like
When the ": filename" part is omitted, it defaults to
"patternEXT" where "EXT" is determined by the user of the
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
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 canonical 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
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
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
continue with next component
translate UNIT into FUNIT using UMAP with EXT=".vhdl"
terminate with FUNIT as the result
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 artificial identifier is constructed. Architectures
get names of the form
while package bodies become
For example, "architecture struct of model" is turned into
"model(struct)" and "package body misc" is turned into
When a design file contains multiple design units, they are all parsed, checked
for correctness 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.
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
When you put "somedir" into your library path, you have access to the
In this situation, you have one file per design unit. When you have one file per
design library, it would look like this
All references to design units in the FMF design library would be routed to
As another 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 library 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
gvhdl(1), freehdl-v2cc(1), freehdl-config(1)
The latest version of FreeHDL can always be obtained from
Known bugs are documented within the BUGS file. If your report addresses a
parser related topic then contact Marius Vollmer <firstname.lastname@example.org>.
If it is related to the code generator or compiler then send an email to Edwin
Naroska <email@example.com>. If your are not sure send
it to Edwin. He will take care of forwarding your report to the appropriate
Edwin Naroska © 1999, 2000, 2001, 2002, 2003, 2004, 2005
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Written by Marius Vollmer <firstname.lastname@example.org> and Edwin Naroska