bionic (5) v2cc.libs.5.gz

Provided by: freehdl_0.0.8-2.2ubuntu2_amd64 bug

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 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  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, 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 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  artificial  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  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 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".

       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

SEE ALSO

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

AVAILABILITY

       The latest version of FreeHDL can always be obtained from www.freehdl.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.

       Edwin Naroska © 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 <edwin@ds.e-technik.uni-dortmund.de>.