home | help 
V2CC.LIBS(5)			  File Formats			    V2CC.LIBS(5)

NAME
     v2cc.libs - VHDL library mapping file for the FreeHDL compiler/simulator.

DESCRIPTION
     FreeHDL is a compiler/simulator suite for the hardware description language
     VHDL.  VHDL'93 as well as VHDL'87 standards are supported.

     FreeHDL  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 script.

     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  li-
     brary 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' | '_' | '/' | '-' | '.' esc-
     char

	  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 identifier, each rule is tried in turn and the first one that matches is
     chosen.

     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, fol-
     lowed 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 char-
     acters "#" 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 identi-
     fiers map to a single filename.

     No  special  character  besides "<" and ">" is valid in "pattern" or "file-
     name".  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" com-
     mand 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 artificial identifier is constructed.   Ar-
     chitectures 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  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.

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  direc-
     tory  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 de-
     sign 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".

     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	<-  map-
     ping 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 com-
     piler 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

SEE ALSO
     gvhdl(1), freehdl-v2cc(1), freehdl-config(1)

AVAILABILITY
     The latest version  of  FreeHDL  can  always  be  obtained  from  www.free-
     hdl.seul.org

REPORTING BUGS
     Known bugs are documented within the BUGS file.  If your report addresses a
     parser related topic 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.

COPYRIGHT
     Edwin Naroska (C) 1999, 2000, 2001, 2002,	2003,  2004,  2005  <edwin@ds.e-
     technik.uni-dortmund.de>

     This  is free software; see the source for copying conditions.  There is NO
     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

AUTHORS
     Written by Marius Vollmer	<mvo@zagadka.ping.de>  and  Edwin  Naroska  <ed-
     win@ds.e-technik.uni-dortmund.de>.

Debian/GNU Linux		  December 2005 		    V2CC.LIBS(5)
home | help