Provided by: freehdl_0.0.8-2.2ubuntu2_amd64 bug

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>.