Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

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

DESCRIPTION
       FreeHDL is a compiler/simulator suite for the hardware description lan-
       guage 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	 simu-
       lation  program.	 Starting  the	generated executable will simulate the
       corresponding VHDL model. The actual build process to generate the sim-
       ulator  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  get-
       ting 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 transform-
       ing 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 charac-
       ters 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 re-
       placement,  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 charac-
       ters 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  fi-
       nal 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	refer-
       enced from another design unit, no code will be generated for the pack-
       age 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 be-
       cause all design	units are retained in core.

EXAMPLES
       The simplest situation is when you have no mapping files	at all.	 A de-
       sign  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  di-
       rectory	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 sub-
       dirs 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  li-
       brary  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  exe-
       cutable 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  ad-
       dresses	a  parser  related  topic then contact Marius Vollmer <mvo@za-
       gadka.ping.de>.	If it is related to the	 code  generator  or  compiler
       then  send  an  email  to  Edwin	 Naroska <edwin@ds.e-technik.uni-dort-
       mund.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)

NAME | DESCRIPTION | EXAMPLES | SEE ALSO | AVAILABILITY | REPORTING BUGS | COPYRIGHT | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=v2cc.libs&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help