Running existing scripts

Last updated:

Many teams have scripts, makefiles and regression flows that call simulation commands by name: vcom and vsim, xvhdl and xelab, ghdl or nvc. JanusHDL comes with small front ends that answer to those command names, so that such scripts run on JanusHDL as they are. This chapter explains how to use them, what each accepts, and how to run VUnit.

For new work, jhdl itself and project files are simpler (Running simulations from the command line, Projects). The front ends are for keeping what you have.

How the front ends work

The compat folder of the download has one folder per family of commands. Each holds a small program for each command name of the family, and a jhdl as well:

Each program passes its command line to JanusHDL, which translates it into its own options and runs it. To use a family, put its folder first on your PATH, before anything else that provides those commands. Put only one family's folder on the PATH, so that each command name means one thing:

export PATH=/opt/janushdl/compat/vsim:$PATH        # Linux

$env:Path = "C:\Tools\janushdl\compat\vsim;" + $env:Path   # Windows, this session

Since each folder has its own jhdl, that one folder on the PATH is enough to use jhdl too.

Commands that JanusHDL does not handle yet (the Verilog commands, and the families marked "not yet") answer with an error that says so, with exit code 2, rather than doing something else.

What they have in common

• Libraries on disk. As the original commands do, the front ends keep libraries between commands: each library has a record of the source files analyzed into it, in order, with each file's VHDL version, and an analysis cache beside it. Each analysis, elaboration or run step analyzes the recorded files of every library it can see (the cache makes that quick) and goes on from there. Each file is analyzed as the VHDL version its own command gave, so libraries analyzed as different versions work together; the standard packages are those of the newest version among the files. The source files must stay where they were when they were analyzed; a file that is gone is left out, with a note.
• Compatibility mode. The front ends always run in compatibility mode, so code that existing scripts were used to getting through, such as UVVM's unprotected shared variables, is accepted with a warning instead of the error jhdl gives without --compat (Compatibility mode). Options such as -frelaxed, --relaxed, -relax or -permissive also turn into warnings the errors JanusHDL can lower.
• Output. Messages are JanusHDL's own, in its format, with files named by their path relative to the current folder, as the script gave them; the summary line jhdl prints at the end is left out. The exit codes follow jhdl's (Exit codes).
• Options without a counterpart. Options that tune optimization, coverage, message display, timing checks and the like are accepted and have no effect. An option that cannot be honored and would change the result is refused with an error that names it. Some accepted options print a note about what they do here.
• Waveforms. Requests to record waveforms record into JanusHDL's waveform database, or into a VCD file where a VCD file is asked for; a note says which file. Open them with jhdlw.
• Versions. Asked for its version, a front end prints the version number of the command language it accepts, followed by JanusHDL's version, so that tools that check the version keep working.

vcom, vsim and the rest

Library mapping. Library names map to folders through the [Library] section of a mapping file: the first .ini file in the current folder that has one. vmap writes there, and makes jhdl-libraries.ini if there is none. Without a mapping, library NAME is the folder NAME.

vcom options. -87 and -93 (VHDL-1993), -2002 (the default), -2008, -2019; -work LIB; -f FILE reads more arguments from a file; -psl reads PSL in comments; -permissive and -relax relax the rules that can be relaxed. Options about checks, optimization, coverage, messages and logs are accepted without effect. -pslfile is not supported yet.

vsim options. The design unit (LIB.TOP, a configuration, or a vopt name); -c, -batch or -console to run without the window; -do "COMMANDS" or -do FILE (several allowed); -lib LIB or -work LIB; -L LIB to make more libraries visible; -gNAME=VALUE and -GNAME=VALUE for generics. vsim -c -do script.do without a design runs a script that loads the design itself; vsim -c without -do reads the commands from the standard input.

Without -c, vsim opens the design in the JanusHDL window and runs it there; the -do scripts are not run in the window yet (a note says so).

Script commands. A -do script, or a file run with do, can use:

Scripts are a small part of Tcl: commands separated by new lines and ;, words grouped with {...} and "...", # comments, \ at the end of a line, set NAME VALUE and $NAME, ${NAME}, $env(NAME). Command substitution ([...]) and control commands (if, foreach, proc, ...) are not supported yet: the script stops with an error that names them. A command that is not supported stops the script the same way.

An example, in a folder with vlib's libraries:

vlib work
vcom -2008 src/fifo.vhd tb/fifo_tb.vhd
vsim -c work.fifo_tb -do "run -all; quit -code 0"

xvhdl, xelab and xsim

Libraries are folders under xsim.dir/.

xvhdl options. --2008 (or -2008, --vhdl2008), --2019, --93_mode; the default is VHDL-1993. -work NAME or -work NAME=DIR; -L NAME[=DIR]; -d NAME=VALUE defines a conditional analysis identifier; --relax; -prj FILE reads a project file of lines vhdl LIB FILE..., vhdl2008 LIB FILE... or vhdl2019 LIB FILE.... -f argument files are not supported yet.

xelab options. The top level; -s NAME names the snapshot (default: the top's name); -R runs after elaborating; -generic_top NAME=VALUE; -prj FILE; and xvhdl's version and library options. Options about debug, timing, SDF and optimization are accepted without effect; -sdfmax, -sdfmin, -sdfroot, -sv_lib, -sv_root and -dll are refused.

xsim options. -R; -tclbatch FILE (several allowed); -wdb FILE records into JanusHDL's waveform database in FILE; -gui runs in batch, and a note says to open the waveform with jhdlw.

Script commands. run TIME, run N UNIT, run all (run alone runs 1000 ns); restart; quit or exit (-code N); puts; log_wave, add_wave, add_wave_divider, add_wave_group record every signal into xsim.jhw; open_vcd [FILE] and log_vcd record a VCD file; close_vcd, current_scope, set_property and similar commands are accepted without effect. The same part of Tcl as above.

xvhdl --2008 src/fifo.vhd tb/fifo_tb.vhd
xelab work.fifo_tb -s fifo
xsim fifo -R

ghdl

ghdl COMMAND [options] ...

Options before the unit. --std=87|93|93c|00|02|08|19 (default 93; VHDL-87 is analyzed as VHDL-93), --work=NAME, --workdir=DIR (where the library records are; default the current folder), -PDIR (more folders with libraries), -frelaxed (or -frelaxed-rules, --relaxed), -fpsl (PSL in comments). Options such as --ieee=..., -fexplicit, -W... and -O... are accepted without effect (the legacy packages they would select are built in).

Run options, after the unit. --stop-time=TIME, --vcd=FILE, --wave=FILE (written in JanusHDL's waveform format), --fst=FILE and --vcdgz=FILE (written as a VCD file, FILE.vcd), -gNAME=VALUE, --assert-level=note|warning|error|failure|none (the severity that stops the run), --ieee-asserts=enable|disable, --no-run. An architecture name after the unit is noted; the architecture analyzed last is used.

ghdl -a --std=08 src/fifo.vhd tb/fifo_tb.vhd
ghdl --elab-run --std=08 fifo_tb --stop-time=10us --wave=fifo.jhw

nvc

nvc [global options] -a FILE... -e [options] UNIT -r [options]

-a, -e and -r can come in one command line, in that order.

• Global options. --std=1993|2000|2002|2008|2019 (or the two-digit forms; default 2008), --work=NAME or --work=NAME:DIR (default: folder ./NAME), -L DIR (more folders with libraries), --map=NAME:DIR, --ieee-warnings=on|off, --init (make the work library).
• After -a. Files; --relaxed; --psl; -DNAME=VALUE.
• After -e. The unit (ENTITY or ENTITY-ARCH, the architecture being noted and the last analyzed one used); -gNAME=VALUE (or -g NAME=VALUE). -e without -r only checks the elaboration.
• After -r. --stop-time=TIME; --wave[=FILE] (JanusHDL's waveform format; default wave.jhw); --format=vcd (a VCD file instead); --exit-severity=LEVEL (the severity that stops the run).

VHPI plug-ins (--load, --vhpi...) and the commands -i, --do, -c, --make, --syntax and others are not supported yet, and say so.

nvc --std=2008 -a src/fifo.vhd tb/fifo_tb.vhd -e fifo_tb -r --stop-time=10us

Limits of the front ends

• Only the Tcl described above is understood in scripts.
• Verilog, and the families marked "not yet", are not supported.

VUnit

VUnit runs on JanusHDL through the ghdl or nvc front end, with your run.py unchanged. VUnit itself is a Python package that you install:

pip install vunit_hdl

Then put one of the two front ends first on your PATH, and tell VUnit to use that command family with VUNIT_SIMULATOR:

export PATH=/opt/janushdl/compat/ghdl:$PATH
export VUNIT_SIMULATOR=ghdl
python run.py

$env:Path = "C:\Tools\janushdl\compat\ghdl;" + $env:Path
$env:VUNIT_SIMULATOR = "ghdl"
python run.py

With the nvc front end, use compat/nvc and VUNIT_SIMULATOR=nvc. VUnit analyzes its own libraries and your sources, then runs each test case in a simulation of its own, in parallel with -p N as usual. Like every front end, these run in compatibility mode, so sources that need it (unprotected shared variables, for instance) analyze with warnings and need nothing in run.py. VUnit's examples (uart, check, logging, array, composite_generics, generate_tests and run) pass this way through either front end; in the run example, the tests written to fail, fail.

• Each simulation stops with an error if it uses more than 4 GiB of memory (Memory limit).
• VUnit's --gui option is not supported. To look at a test's waveforms, run its testbench with jhdl --wave and open the recording in jhdlw.