1V2CC.LIBS(5) File Formats V2CC.LIBS(5)
2
6 v2cc.libs - VHDL library mapping file for the FreeHDL compiler/simula‐
7 tor.
8
10 FreeHDL is a compiler/simulator suite for the hardware description lan‐
11 guage VHDL. VHDL'93 as well as VHDL'87 standards are supported.
12 FreeHDL translates the original VHDL source FILEs into C++. Then, the
14 C++ source can be compiled and linked to the kernel to build the simu‐
15 lation program. Starting the generated executable will simulate the
16 corresponding VHDL model. The actual build process to generate the sim‐
17 ulator from the VHDL source is a complex process which is handled by
18 the gvhdl script.
19 FreeHDL does not have a opaque notion of design libraries. VHDL files
21 are not pre-analyzed and checked into some library data base as in
22 other VHDL compiler/simulator systems. Instead, whenever a reference
23 to a design unit needs to be made, FreeHDL parses the VHDL code of that
24 design unit from fresh. Therefore, it needs to be able to find the
25 source file of a design unit given the VHDL name of that unit.
26 Thus, as far as FreeHDL is concerned, a design library is a mapping
28 from VHDL identifiers to file names. There is also a mapping for get‐
29 ting library names from mapping files.
30 Such a mapping is specified via a "mapping file". It contains a list
32 of pattern rules that each transform a certain class of identifiers
33 into file names.
34 The syntax of a mapping file is:
36 Lexical:
38 litchar: 'a'..'z' | 'A'..'Z' | '0'..'9' | '_' | '/' | '-' | '.'
40 escchar
41 escchar: '\' char
43 whitespace: ' ' | '\n' | '\v' | '\t' | comment
45 comment: '#' any_character* '\n'
47 opchar: ':' | ',' | '(' | ')'
49 specchar: every printable char except litchar, whitespace and
51 opchar
52 symchar: litchar | specchar
54 symbol: symchar+
56 Grammar:
58 mapping: version patternrule*
60 version: "v2cc_mapfile" "0"
62 patternrule: symbol [ ':' symbol ]
64 Comments are ignored.
66 A mapping files specifies a sequence of pattern rules. When transform‐
68 ing an identifier, each rule is tried in turn and the first one that
69 matches is chosen.
70 A rule looks like
72 pattern: filename
74 When the ": filename" part is omitted, it defaults to "patternEXT"
76 where "EXT" is determined by the user of the mapping file.
77 The "pattern" can contain the special character "<" which introduces a
79 `wildcard'. The "<" must be followed by a ">", with arbitrary charac‐
80 ters inbetween. These characters form the name of the wildcard. A
81 wildcard matches any sequence of characters. There can be any number
82 of wildcards in the pattern, but each must have a unique name.
83 The "filename" can also contain the character "<", followed by a name,
85 followed by ">". There, it introduces a `wildcard substitution'. It
86 will be replaced with the characters that matched the wildcard with the
87 same name in "pattern". When there is no wildcard in "pattern" with
88 the right name, it will be replaced with nothing. While doing this
89 replacement, the characters "#" and "/" are replaced as "##", and "#-"
90 respectively. No other character translations are done, so if you have
91 funny characters in your VHDL identifiers, you will have funny charac‐
92 ters in your filenames.
93 Before doing the comparison with the patterns, the VHDL identifier is
95 brought into a canonical form: when it is not an abstract identifier,
96 all its characters are down-cased.
97 When the resulting filename is relative (does not begin with "/"), it
99 is prefixed with the directory of the mapping file.
100 A non-existent mapping file is equivalent to the single rule
102 <>
104 An empty mapping file is just that: an empty mapping.
106 The mapping does not need to be reversible. It is OK when multiple
108 identifiers map to a single filename.
109 No special character besides "<" and ">" is valid in "pattern" or
111 "filename". They are reserved for future extensions.
112 The mapping files for going from design unit names to filenames are
115 found by looking into directories specified by the `v2cc library path'.
116 You can use the environment variable V2CC_LIBRARY_PATH and command line
117 options to define the path. When the environment variable is not set,
118 it defaults to a value that makes the standard libraries available that
119 are distributed and installed with v2cc itself. When it is set, it
120 completely overwrites this default value.
121 The variable V2CC_LIBRARY_PATH consists of ":" separated filenames.
123 The filename "*" is replaced with the default value mentioned above.
124 In addition to the environment variable, you can use the "-L libdir"
126 command line option with v2cc. The directories specified with "-L" are
127 added in front of the ones specified by V2CC_LIBRARY_PATH. In the
128 final library path, they appear in the same order as on the command
129 line.
130 Looking for a design unit named UNIT in a library named LIB is done
132 like this:
133 for each component of the library path, L
135 if L is a regular file
136 set LMAP to L
137 else if L is a directory
138 set LMAP to L/v2cc.libs
139 else
140 continue with next component
141 translate LIB into FLIB using LMAP with EXT=""
142 if FLIB.vhdl exists
143 terminate with FLIB.vhdl as the result
144 if FLIB.v2cc exists
145 set UMAP to FLIB.v2cc
146 else if FLIB is a directory
147 set UMAP to FLIB/v2cc.units
148 else
149 continue with next component
150 translate UNIT into FUNIT using UMAP with EXT=".vhdl"
151 terminate with FUNIT as the result
152 terminate unsuccessfully
153 This mechanism is used for all design units that are referenced from
156 within VHDL code (or via other means). There is a complication with
157 architectures and package bodies, though, because they are not uniquely
158 identified by a single identifier. For them, a artificial identifier
159 is constructed. Architectures get names of the form
160 <entity>(<architecture>)
162 while package bodies become
164 <package>(body)
166 For example, "architecture struct of model" is turned into
168 "model(struct)" and "package body misc" is turned into "misc(body)".
169 When a design file contains multiple design units, they are all parsed,
171 checked for correctness and remembered, but only the needed unit will
172 be used for code generation. That is, when a design file contains both
173 a package header and a package body and the package header is refer‐
174 enced from another design unit, no code will be generated for the pack‐
175 age body. When one of the ignored units will be referenced later in
176 the same invocation of v2cc, the design file will not be read again
177 because all design units are retained in core.
178
180 The simplest situation is when you have no mapping files at all. A
181 design library is then a directory on your library path. The name of
182 that directory is that of the library in VHDL. Each file in that
183 directory with a ".vhdl" extension is used for a design unit with the
184 same name as the file without the extension.
185 Say you have this directory structure
187 somedir/
189 std/
190 standard.vhdl
191 textio.vhdl
192 ieee/
193 numeric_bit.vhdl
194 std_logic_1164.vhdl
195 When you put "somedir" into your library path, you have access to the
197 design units
198 STD.STANDARD
200 STD.TEXTIO
201 IEEE.NUMERIC_BIT
202 IEEE.STD_LOGIC_1164
203 In this situation, you have one file per design unit. When you have
205 one file per design library, it would look like this
206 somedir/
208 fmf.vhdl
209 All references to design units in the FMF design library would be
211 routed to "fmf.vhdl".
212 As another example assume that all VHDL libraries are mapped into sub‐
214 dirs starting from root directory "/foo". Further, assume that there
215 are VHDL libraries named "lib1" and "lib2". They shall be mapped to
216 subdir "/foo/lib1_dir" and "/foo/lib2_dir". Hence, the file/directory
217 structure is as follows:
218 /foo <- library root directory /foo/v2cc.libs <-
220 mapping control file /foo/lib1_dir <- library dir for VHDL
221 library lib1 /foo/lib1_dir/comp1.vhdl <- file that contains VHDL model
222 comp1 /foo/lib2_dir <- library dir for VHDL library lib2
223 /foo/lib2_dir/comp2.vhdl <- file that contains VHDL model comp2
224 Then, file "/foo/v2cc.libs" should contain:
226 v2cc_mapfile 0 lib1 : lib1_dir lib2 : lib2_dir
228 In order to compile a design named comp1 (stored in file comp1.vhdl)
230 into VHDL library lib1 goto subdir "/foo/lib1_dir" and execute:
231 gvhdl -c -L .. -l lib1 comp1.vhdl
233 Note that option "-l lib1" forces the compiler to associate the model
235 stored in "comp1.vhdl" with VHDL library lib1. Note further, that the
236 compiler switch "-L .." specifies the path to the directory where
237 "v2cc.libs" is stored. You may also specify an absolute path:
238 gvhdl -c -L /foo -l lib1 comp1.vhdl
240 Note that comp1 should reside in a file named "comp1.vhdl".
242 If lib2 contains a design comp2 that makes use of comp1 from lib1 then
244 goto "/foo/lib2_dir" and run the following command to create an exe‐
245 cutable for model comp2:
246 gvhdl -L .. -l lib2 comp2.vhdl ../lib1_dir/comp1.o
248
250 gvhdl(1), freehdl-v2cc(1), freehdl-config(1)
251
253 The latest version of FreeHDL can always be obtained from www.free‐
254 hdl.seul.org
255
257 Known bugs are documented within the BUGS file. If your report
258 addresses a parser related topic then contact Marius Vollmer
259 <mvo@zagadka.ping.de>. If it is related to the code generator or com‐
260 piler then send an email to Edwin Naroska <edwin@ds.e-technik.uni-dort‐
261 mund.de>. If your are not sure send it to Edwin. He will take care of
262 forwarding your report to the appropriate recipient.
263
265 Edwin Naroska © 1999, 2000, 2001, 2002, 2003, 2004, 2005 <edwin@ds.e-
266 technik.uni-dortmund.de>
267 This is free software; see the source for copying conditions. There is
269 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
270 PURPOSE.
271
273 Written by Marius Vollmer <mvo@zagadka.ping.de> and Edwin Naroska
274 <edwin@ds.e-technik.uni-dortmund.de>.
275Debian/GNU Linux December 2005 V2CC.LIBS(5)