NAME
gvhdl - Frontend to the VHDL compiler/simulator FreeHDL.
SYNOPSIS
gvhdl [OPTION] ... [VHDL_FILES] ... [OBJECT_FILES] ...
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.
VHDL_FILES is a list of VHDL source file names that must end with .vhdl
or .vhd. The first VHDL file name also determines the name of the
simulator executable. This is, the final executable will be named after
the first VHDL file without the .vhdl or .vhd extension. Note that the
object files as well as the simulator will be created in the current
directory.
OBJECT_FILES specifies a list of object files that are linked to the
simulator executable. gvhdl considers all files that end with .o to be
object files. Typically, these object files are generated previously
(using option -c) from VHDL source code during a separate compilation
step.
OPTIONS
-L VHDLLIB
Path to VHDL library root directory. Within this directory the
compiler search for a file named v2cc.libs. The mapping file
v2cc.libs translates library unit names to directories. Note
that more than one VHDLLIB may be provided.
-g Adds debug information to the executable. In detail, this
options associates the generated machine code to the
corresponding lines in the VHDL source files.
-G Adds debug information to the executable but does not associate
machine code to VHDL source lines. This option is actually used
to debug the generated C++ code.
-c Do not generate simulator executable. Using this option, the
compiler translated VHDL source into executables and compiles
them into object code but does not generate a final simulator
executable. This option is especially useful to compile VHDL
packages.
-l LIBNAME
Associate the VHDL source code to VHDL library LIBNAME. As
default the library name WORK is used. This option is especially
important if VHDL components from several VHDL libraries shall
be build into the simulator. Note that in order to successfully
use a VHDL component from another than the current working
library, the corresponding VHDL files must be found by the
compiler using the mechanisms described in v2cc.libs. Further,
components must be compiled with the appropriate -l LIBNAME
option.
--relaxed-component-visibility
Allows invisible default bindings from WORK.
--libieee
Add the IEEE standard library files to the simulation
executable.
ENVIRONMENT VARIABLES
V2CC_LIBRARY_PATH
The variable V2CC_LIBRARY_PATH consists of ":" separated
filenames. 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.
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:
- Individual association of formals of composite type are not
supported.
- Shared variables are not supported.
- Attributes transaction, quiet, stable and delayed are not supported.
- User defined attributes are not supported.
- Groups are not supported.
- Guarded signal assignments are not supported.
- Configurations are not supported.
- Currently, drivers cannot be switched off.
EXAMPLES
Use
gvhdl -c adder.vhdl
to build an object file for adder.vhdl. Note that adder.vhdl may
contain several VHDL models.
gvhdl adder.vhdl
will generate a simulator for the last VHDL model found in adder.vhdl.
However, in this case, all VHDL components that area required to build
the simulator must be included in the VHDL source file.
gvhdl top.vhdl adder.o --libieee
generates a simulator for the last VHDL model found in top.vhdl by
compiling all models in top.vhdl and linking (the previously generated)
adder.o object file and the IEEE standard libraries to the executable.
gvhdl -c -l mylib adder.vhdl
will build an object file including all components provided in
adder.vhdl. However, in this case the components will be associated
with library mylib instead of the default library name work. Note that
option -l does only effect the generated C++ source code but does not
alter the place where the object files or executables are stored.
SIMULATION COMMANDS
After the simulator has been started a short summary of the available
commands is 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".
SIMULATOR COMMAND LINE OPTIONS
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
./top -cmd "d;run 1000 ns;q;"
will start simulation program ’top’, 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.
SEE ALSO
freehdl-v2cc(1), freehdl-config(1), v2cc.libs(5)
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.
COPYRIGHT
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>.