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!

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

To compile "model4.vhdl" run

    %./gvhdl model4.vhdl ../ieee/std_logic_1164.o ../ieee/numeric_std.o


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

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


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.