GVHDL(1)

📦 version 0.0.8, in arch rolling

💅 GVHDL(1) — the gvhdl page, but make it make sense 🎀

okay so the manual name is literally GVHDL(1) and it lives in the User Commands section, bestie. That's the whole header, we're done with it, moving on ✨

🌸 NAME 🌸

gvhdl — it's the frontend to the VHDL compiler/simulator FreeHDL. That's it, that's the vibe check 👑

🦋 SYNOPSIS 🦋

gvhdl [OPTION] ... [VHDL_FILES] ... [OBJECT_FILES] ...

no cap, that's the whole thing. options, then your VHDL files, then your object files. easy 🫶

💖 DESCRIPTION 💖

so FreeHDL is a whole compiler/simulator suite for the hardware description language VHDL, and it supports both the VHDL'93 and the VHDL'87 standards. iconic, honestly.

here's the pipeline, bestie, pay attention: FreeHDL translates your original VHDL source FILEs into C++. then that C++ source gets compiled and linked against the kernel to build the actual simulation program. and when you start the generated executable, boom — it simulates the corresponding VHDL model. but the actual build process to get from VHDL source to a working simulator is genuinely a complex multi-step situation, and the gvhdl script is the one that handles it all for you ✨

VHDL_FILES is your list of VHDL source file names, and they must end with .vhdl or .vhd — no exceptions, the extension is not optional. and here's the cute part: the first VHDL file name also decides what your simulator executable is called. like, the final executable gets named after that first VHDL file, just with the .vhdl or .vhd chopped off. also note that both the object files and the simulator get created in the current directory, so keep that in mind 💅

OBJECT_FILES is the list of object files that get linked into the simulator executable. gvhdl treats literally everything ending in .o as an object file. typically you generated those earlier (with the -c option) from VHDL source code during a separate compilation step. it's giving "prep work pays off" 🌈

✨ OPTIONS ✨

  • -L VHDLLIB — path to the VHDL library root directory. inside this directory, the compiler looks for a file named v2cc.libs. that mapping file is what translates library unit names into directories. and ngl, you can pass more than one VHDLLIB — stack 'em 🧚
  • -g — adds debug information to the executable. specifically, this option associates the generated machine code with the corresponding lines in your VHDL source files. so when debugging hits, you know exactly which line did it 💀
  • -G — also adds debug information to the executable, but does not associate machine code with VHDL source lines. this one is actually for debugging the generated C++ code, not your VHDL. different girl, different job 🎀
  • -c — do not generate the simulator executable. with this, the compiler translates VHDL source into executables and compiles them into object code, but stops there and doesn't produce a final simulator executable. this is especially useful for compiling VHDL packages. lowkey my fave for incremental work 🍓
  • -l LIBNAME — associate the VHDL source code with the VHDL library LIBNAME. the default library name is WORK. this one matters big time if you want VHDL components from several different VHDL libraries built into the simulator. and listen — to successfully use a VHDL component from a library other than the current working library, the corresponding VHDL files have to be found by the compiler using the mechanisms described in v2cc.libs. further, those components must be compiled with the appropriate -l LIBNAME option. both things. not one. both 🙈
  • --relaxed-component-visibility — allows invisible default bindings from WORK.
  • --libieee — adds the IEEE standard library files to the simulation executable. slay 👑

🌈 ENVIRONMENT VARIABLES 🌈

💜 V2CC_LIBRARY_PATH

V2CC_LIBRARY_PATH consists of ":"-separated filenames. and in addition to the environment variable, you can also use the "-L libdir" command line option with v2cc. here's the ordering tea tho: the directories specified with "-L" get 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. so command line first, env var after, and everybody keeps their original order 🫶

🌸 SUPPORTED VHDL SUBSET 🌸

okay bestie, moment of honesty: currently, FreeHDL does not support the entire VHDL'93 standard. here's an incomplete list giving you an overview of what's currently not supported — read it before you get attached to a feature 😭

  • 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 — it's flexible like that 💅

gvhdl adder.vhdl

will generate a simulator for the last VHDL model found in adder.vhdl. but heads up: in this case, all VHDL components that are required to build the simulator must be included in the VHDL source file. no sneaky external deps 🔥

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. that's the full combo meal 🍓

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. and note that option -l only affects the generated C++ source code — it does not alter the place where the object files or executables are stored. so don't come for me when the files are still right there in your current directory 🙈

⭐ 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 every VCD waveform viewer, so you're covered 🌈 the file name is set to "wave.dmp" but may be changed using "dc -f <new_file_name>". however — and I mean this lovingly — make sure to execute "dc -f ..." before executing "d". order matters, bestie 💀

🦋 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. and actually — the last command 'q;' is optional, because the simulator automatically terminates as soon as the last command has been executed. so you can just let it go out on its own terms 👑

💫 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 — go get her 🫶

💀 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's related to the code generator or compiler, then send an email to Edwin Naroska <edwin@ds.e-technik.uni-dortmund.de>. and if you're not sure? send it to Edwin. he will take care of forwarding your report to the appropriate recipient. king behavior, honestly 👑

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. like, none. zero. don't @ me 😭

🧚 AUTHORS 🧚

written by Marius Vollmer <mvo@zagadka.ping.de> and Edwin Naroska <edwin@ds.e-technik.uni-dortmund.de>.

💖 that's the whole page, bestie! this one shipped with the Debian/GNU Linux distribution, dated December 2005, and it's filed under GVHDL(1). now go compile something iconic ✨🎀💅
📦 where this page comes from