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 libraray 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 libraray "work" with subdirectory "vhdl" and - VHDL libraray "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 libraray 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.