Simulation (runtime)

Simulation options

In most system environments, it is possible to pass CLI options while invoking a program. Contrary to most programming languages, there is no standard method in VHDL to obtain the arguments or to set the exit status. However, the GHDL runtime behaviour can be modified with some options:

  • It is possible to pass parameters to your design through the generic interfaces of the top entity.

  • It is also possible to stop simulation after a certain time. The exit status of the simulation is EXIT_SUCCESS (0) if the simulation completes, or EXIT_FAILURE (1) in case of error (assertion failure, overflow or any constraint error).

Here is the list of the most useful options. For further info, see Debugging.

Hint

Note that these arguments are represented as simulation_options... in this documentation. For analysis/elaboration options, see Invoking GHDL.

-gGENERIC=VALUE

Set value VALUE to generic with name GENERIC.

Example:

$ ghdl -r --std=08 my_unit -gDEPTH=12

Note

This is currently a run option; but in the (not near) future it might be deprecated to become an elaboration option only. As a result, now you can generate a single binary and execute it multiple times with different arguments. That might not be possible in the future.

As explained in -e, performing a complete elaboration in terms of the LRM requires to get rid of the compile and link model. This is mostly because delaying certain elaboration steps to the runtime prevents elaboration-time optimisions.

Hint

Currently, GHDL has limited support for generic types in the CLI. It is suggested to use strings or integers. Nonetheless, project JSON-for-VHDL allows to encode a set of parameters as stringified JSON, and it provides VHDL functions to read specific values from it. It is valid for synthesis.

--assert-level=<LEVEL>

Select the assertion level at which an assertion violation stops the simulation. LEVEL is the name from the severity_level enumerated type defined in the standard package or the none name.

By default, only assertion violation of severity level failure stops the simulation.

For example, if LEVEL was warning, any assertion violation with severity level warning, error or failure would stop simulation, but the assertion violation at the note severity level would only display a message.

Option --assert-level=none prevents any assertion violation from stopping simulation.

--backtrace-severity=<LEVEL>

Select the assertion level at which an assertion violation display a backtrace (if available).

This is useful when the assertion is generated by a function (like assertions in ieee.numeric_std) whose location is not very useful.

--ieee-asserts=<POLICY>
--asserts=<POLICY>

Select how assertions are handled. POLICY can be enable (the default), disable which disables all assertions and disable-at-0 which disables only at the start of simulation.

The --ieee-asserts applies only to assertions from ieee package. This option can be useful to avoid assertion messages from ieee.numeric_std (and other ieee packages).

The --asserts option applies to all assertions, including those from the ieee units. The behaviour of the latter can be overridden by using the --ieee-asserts option after the --asserts option.

--stop-time=<TIME>

Stop the simulation after TIME. TIME is expressed as a time value, without any space. The time is the simulation time, not the real clock time.

For example:

$ ./my_design --stop-time=10ns
$ ./my_design --stop-time=ps
--stop-delta=<N>

Stop the simulation after N delta cycles in the same current time. The default is 5000.

--disp-time

Display the time and delta cycle number as simulation advances.

--unbuffered

Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO).

--max-stack-alloc=<N>

Emit an error message in case of allocation on the stack of an object larger than N KB. Use 0 to disable these checks.

--sdf=<PATH=FILENAME>

Do VITAL annotation on PATH with SDF file FILENAME.

PATH is a path of instances, separated with . or /. Any separator can be used. Instances are component instantiation labels, generate labels or block labels. Currently, you cannot use an indexed name.

Specifying a delay:

--sdf=min=PATH=FILENAME
--sdf=typ=PATH=FILENAME
--sdf=max=PATH=FILENAME

If the option contains a type of delay, that is min=, typ= or max=, the annotator use respectively minimum, typical or maximum values. If the option does not contain a type of delay, the annotator uses the typical delay.

See section Backannotation, for more details.

--vpi=<FILENAME>

Load VPI library. This option can be used multiple times to load different libraries.

Any registration functions in the vlog_startup_routines array in the library will be called:

void (*vlog_startup_routines[]) () = {
  my_handle_register,
  0
};
--vpi-trace[=<FILENAME>]

Trace vpi calls. Trace is printed to FILENAME if provided, otherwise to stdout.

--vhpi=<FILENAME>[:<ENTRYPOINT>]

Load VHPI library. This option can be used multiple times to load different libraries.

If an ENTRYPOINT registration function is provided, it will be called. Otherwise, any registration functions in the vhpi_startup_routines array in the library will be called:

void (*vhpi_startup_routines[])() = {
  register_foreign_app,
  register_foreign_func,
  0
};
--vhpi-trace[=<FILENAME>]

Trace vhpi calls. Trace is printed to FILENAME if provided, otherwise to stdout.

--coverage

Generate coverage information about the simulation. A JSON file (whose name is :file:’coverage-DATETIME.json’) is generated at the end of the simulation. You can use the coverage command to merge results and generate reports.

--help

Display a short description of the options accepted by the runtime library.

--no-run

Stop the simulation before the first cycle. This option actually elaborates the design, so it will catch any bound error in port maps. See also -e.

This may be used with --disp-tree to display the tree without simulating the whole design.

Export waveforms

Note

All the waveform formats supported by GHDL are also supported by GTKWave.

--read-wave-opt=<FILENAME>

Filter signals to be dumped to the wave file according to the wave option file provided.

Here is a description of the wave option file format currently supported

$ version = 1.1  # Optional

# Path format for signals in packages :
my_pkg.global_signal_a

# Path format for signals in entities :
/top/sub/clk

# Dump every signal named reset in first level sub entities of top
/top/*/reset

# Dump every signal named reset in recursive sub entities of top
/top/**/reset

# Dump every signal of sub2 which could be anywhere in the design except
# on the top level
/**/sub2/*

# Dump every signal of sub3 which must be a first level sub entity of the
# top level
/*/sub3/*

# Dump every signal of the first level sub entities of sub3 (but not
# those of sub3)
/**/sub3/*/*
--write-wave-opt=<FILENAME>

If the wave option file doesn’t exist, creates it with all the signals of the design. Otherwise throws an error, because it won’t erase an existing file.

--vcd=<FILENAME>
--vcdgz=<FILENAME>

Option --vcd dumps into the VCD file FILENAME the signal values before each non-delta cycle. If FILENAME is -, then the standard output is used, otherwise a file is created or overwritten.

The --vcdgz option is the same as the --vcd option, but the output is compressed using the zlib (gzip compression). However, you can’t use the - filename. Furthermore, only one VCD file can be written.

VCD (value change dump) is a file format defined by the verilog standard and used by virtually any wave viewer. Since it comes from verilog, only a few VHDL types can be dumped. GHDL dumps only signals whose base type is of the following:

  • types defined in the std.standard package:

    • bit

    • bit_vector

  • types defined in the ieee.std_logic_1164 package:

    • std_ulogic

    • std_logic (because it is a subtype of std_ulogic)

    • std_ulogic_vector

    • std_logic_vector

  • any integer type

Note

It is very unfortunate there is no standard or well-known wave file format supporting VHDL types. If you are aware of such a free format, please let us know!

--vcd-nodate

Do not write date in the VCD file.

--vcd-4states

Only use the verilog states 0/1/x/z to represent std_ulogic values. The VCD file produced should be fully compatible with any VCD reader. The default is to write std_ulogic as they are (so keeping states U/W/L/H/-), which is supported by several VCD readers.

--fst=<FILENAME>

Write the waveforms into an fst file. The fst files are much smaller than VCD or GHW files, but it handles only the same signals as the VCD format.

--wave=<FILENAME>

Write the waveforms into a GHDL Waveform (GHW) file. Contrary to VCD files, any VHDL type can be dumped into a GHW file.

Export hierarchy and references

--disp-tree=<KIND>

Display the design hierarchy as a tree of instantiated design entities. This may be useful to understand the structure of a complex design. KIND is optional, but if set must be one of:

  • none Do not display hierarchy. Same as if the option was not present.

  • inst Display entities, architectures, instances, blocks and generates statements.

  • proc Like inst but also display processes.

  • port Like proc but display ports and signals too. If KIND is not specified, the hierarchy is displayed with the port mode.

--xref-html [options] files...

To easily navigate through your sources, you may generate cross-references. This command generates an html file for each file given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. An index of the files is created too.

The set of files are analyzed, and then, if the analysis is successful, html files are generated in the directory specified by the -o <DIR> option, or html/ directory by default. The style of the html file can be modified with the --format option.

--psl-report=<FILENAME>

Write a report for PSL at the end of simulation. For each PSL cover and assert statements, the name, source location and whether it passed or failed is reported. The file is written using the JSON format, but is still human readable.

--psl-report-uncovered

Reports warning for each uncovered PSL cover point when simulation ends.