0. Table of content
-------------------
This document is organized as follows:
1. Running the compiler
1.1 Compiling ieee.std_logic_1164 and ieee.numeric_std
1.2 Compiler options
2. Supported VHDL subset
3. Supported simulation commands
3.1 Controlling simulation from the command line
4. Bug reports
1. Running the compiler
-----------------------
Change to subdirectory "v2cc". Here you will find a simple perl script
"gvhdl" which performs all necessary steps in order to create a
simulation binary from a VHDL source file. The command
%./gvhdl y.vhdl
compiles "y.vhdl" into a executable "y". Type
%./y
to start the simulator. For more info on how to control the simulator
see section 3.
Note that all VHDL source files must end with ".vhdl".
If you would like to build a simulator for a model consisting of
several modules (entity + architecture or package + package body) you
may put all the modules into a single file and compile it as
described above. The top level module should be placed at the end of
the file.
Another option is to create a separate file for each module. The files
should be named after the entity/package it stores. Then, each module
must be compiled separately:
%./gvhdl -c <module_1>.vhdl
%./gvhdl -c <module_2>.vhdl
...
%./gvhdl -c <module_1>.vhdl
Finally, the top level module is compiled and linked via:
%./gvhdl <top_module>.vhdl <module_1>.o ... <module_n>.o
1.1 Compiling ieee.std_logic_1164 and ieee.numeric_std
------------------------------------------------------
If package ieee.std_logic_1164 or ieee.numeric_std are used within a
design then the corresponding object files must be added when
compiling the top level design. I.e., when compiling the top level
module of your design add "../ieee/numeric_std.o
../ieee/std_logic_1164.o" (order is important!) to the list of modules
to link (or just "../ieee/std_logic_1164.o" if you do not use
numeric_std):
%./gvhdl <top_module>.vhdl <module_1>.o ... <module_n>.o \
../ieee/numeric_std.o ../ieee/std_logic_1164.o
Make sure to list numeric_std.o before std_logic_1164.o. Otherwise,
the link stage may fail!
As an alternative method you may use the "--libieee" option to add
all ieee libraries (that currently come with the compiler).
Directory "v2cc" contains two example models "top.vhdl" and
"model4.vhdl" which make use of std_logic_1164 and numeric_std. To
compile "top.vhdl" execute:
%./gvhdl -c adder.vhdl
%./gvhdl top.vhdl adder.o ../ieee/std_logic_1164.o
or
%./gvhdl -c adder.vhdl
%./gvhdl top.vhdl adder.o --libieee
To compile "model4.vhdl" run
%./gvhdl model4.vhdl ../ieee/std_logic_1164.o ../ieee/numeric_std.o
or simply
%./gvhdl model4.vhdl --libieee
1.2 Compiler options
--------------------
gvhdl now accepts the following options:
-g : adds debugging info (i.e., the simulator can be debugged
using VHDL source file line numbers). This also enables
outputting some stack trace info in case of an runtime error.
-G : same as -g but no VHDL source file and line number info
is added to the executable (this is to support debugging
code generated by the compiler).
-c : compile only, do not link
-l <lib_name> : compile design into library <lib_name>.
-L <vhdl_lib> : path to VHDL library root directory. Within this
directory the compiler search for a file named v2cc.libs.
v2cc.libs translates library unit names to directories.
Note that more than one vhdl_lib may be provided
(see also section "VHDL library mapping").
--libieee : add ieee libraries (std:logic_1164, numeric_std, ...)
to executable.
All other options not directly recognized by gvhdl are forwarded to
g++. Hence, in order to optimize the generated code for speed add
"-O3" to the list of gvhdl options! E.g.,
%../v2cc/gvhdl -O3 -c -l ieee std_logic_1164.vhdl
%../v2cc/gvhdl -O3 -c -l ieee numeric_std.vhdl
executed within subdir "ieee" will create speed optimized versions of
std_logic_1164 and numeric_std. However, note that the code of these
packages is generated form the the ORIGINAL ieee VHDL source. Currently,
there are no special hand optimized versions of it (this is one of the
tasks to be done in the future).
1.3 VHDL library mapping
--------------------------------
In order to support mapping from VHDL unit names to directiores, a set
of v2cc.libs files may be used. The directory where a v2cc.libs file
is stored is passed over to the compiler using the "-L <vhdl_lib>"
compiler switch. Note that several vhdl_lib directores may be
specified.
The content of a v2cc.libs file looks like
v2cc_mapfile 0
work : vhdl
dummy : /home/edwin/work/test/dummy
The first line ist just used to check for a vaild vhdl mapping
file. The next two lines associate
- VHDL library "work" with subdirectory "vhdl" and
- VHDL library "dummy" with subdirectory /home/edwin/work/test/dummy.
If the subdir path does not start with "/" then it is relative to the
directory the corresponding v2cc.libs resides in. Here, VHDL library
"work" is mapped to "<vhdl_lib>/vhdl". If a model or package named
"comp" is referenced then the compiler will look into the directores
of all VHDL libraries that are currently visible and searches for a
file named "comp.vhdl".
For more details about the v2cc.libs format please read with
README.libraries.
1.3.1 Example VHDL library setup
--------------------------------
As an 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
2. Supported VHDL subset
------------------------
Currently, FreeHDL does not support the entire VHDL'93 standard. The
following incomplete list gives an overview on what is currently (not)
supported (note that the compiler is not tested very intensively;
hence, expect to hit a lot of bugs in the compiler and simulator
system):
- Individual association of formals of composite type are currently
not supported.
- VHDL'93 as well as VHDL'87 file support has been added.
- Shared variables are currently not supported.
- Attributes transaction, quiet, stable and delayed are
currently not supported.
- User defined attributes are currently not supported.
- Groups are currently not supported.
- Guarded signal assignments are currently not supported.
- Currently drivers cannot be switched off.
3. Supported simulation commands
--------------------------------
After the simulator has been started a short summary of the available
commands are printed to the screen:
c <number> : execute cycles = execute <number> simulation cycles
n : next = execute next simulation cycle
q : quit = quit simulation
r <time> : run = execute simulation for <time>
d : dump = dump signals
doff : dump off = stop dumping signals
don : dump on = continue dumping signals
s : show = show signal values
dv : dump var = dump a signal from the signal lists
ds : dump show = shows the list of dumped signals
nds : number show = shows the number of dumped signals
dc [-f <filename>] [-t <timescale> <time unit>] [-cfg <translation file>] [-q]
: configures dump process
Note that signals are dumped into a file (default file name is
"wave.dmp") in VCD format. This file format should be accepted by each
VCD waveform viewer. The file name is set to "wave.dmp" but may be
changed using "dc -f <new_file_name>". However, make sure to execute
"dc -f ..." before executing "d".
Here is a small protocol of a simulation run (user input is marked
with "<--"):
%./y
Available commands:
c <number> : execute cycles = execute <number> simulation cycles
n : next = execute next simulation cycle
q : quit = quit simulation
r <time> : run = execute simulation for <time>
d : dump = dump signals
doff : dump off = stop dumping signals
don : dump on = continue dumping signals
s : show = show signal values
dv : dump var = dump a signal from the signal lists
ds : dump show = shows the list of dumped signals
nds : number show = shows the number of dumped signals
dc [-f <filename>] [-t <timescale> <time unit>] [-cfg <translation file>] [-q]
: configures dump process
Simulation time = 0 fs + 0d
> dc -q <-- suppress warnings/verbose messages
> d <-- dump all signals into wave.dmp
> run 100 ns <-- run for 100 ns
Run simulation for which time span?
Simulating model to time 100 ns
Simulation time = 100 ns + 0d
106 processes were executed.
138 transaction were created.
> quit <-- quit simulation
3.1 Controlling simulation from the command line
------------------------------------------------
Simulation can be controlled via the command line parameter '-cmd
"cmd1; cmd2; ..."' where 'cmd1', 'cmd2', ... are simulation commands
as described in the previous section. Note that each command must be
separated by ';'. E.g., executing
%./y -cmd "d;run 1000 ns;q;"
will start simulation program 'y', dump all signals and run simulation
for 1000 ns. Finally, simulation is terminated. Actually, the last
command 'q;' is optional as the simulator automatically terminates as
soon as the last command has been executed.
4. Bug reports
--------------
Please send simulator or code generator related bug reports or
comments to Edwin Naroska <edwin@ds.e-technik.uni-dortmund.de>. If you
are not sure to what your problem is related to send your email to
Edwin as well. He will take care of forwarding your report or comment
to the appropriate recipient.
