Recording Waveforms in XMODEL

Overview

XMODEL can save the simulated waveforms in two ways: first using the measurement probe primitives and second using the $xmodel_dumpfile() and $xmodel_dumpvars() system calls. The former is more convenient when recording individual signal waveforms while the latter is more convenient when recording multiple signals at once (e.g. all the signals in the current module or in all the hierarchies below).

Supported File Formats

Currently, XMODEL can save the waveforms in two waveform file formats: JEZ and FSDB. The choice is made simply by using the proper extension (.jez or .fsdb, respectively) in the filename.

The JEZ format is the XMODEL’s proprietary format that is most suitable for preserving the highest accuracy and precision of the event-driven signal waveforms in XMODEL (e.g. xbit and xreal-type signals). It also stores the statistical properties of the signals such as noise and jitter. However, currently, it can only be viewed using the dedicated waveform viewer, XWAVE.

On the other hand, the FSDB format is more of a conventional file format that dumps the signal’s value whenever it changes. Its advantage is that it is supported by many third-party waveform viewers today. However, due to the limitation of its file format, the resulting waveforms may lose timing or magnitude accuracy for xbit and xreal-typed signals.

The XMODEL package also includes an offline utility called jez2vcd that can convert a JEZ format file into a VCD (Value Change Dump) format. One disadvantage of the VCD format though is that its file size may become very large after the conversion due to the inefficiency of its file format storing continuous-time real-type signals.

Waveform Recording Using Probe Primitives

The measurement probe primitives are one category of primitives provided by XMODEL. There are two kinds of measurement probe primitives: the signal probes and property probes.

The signal probes record the waveforms of the signals themselves. For instance:

• probe_xbit
• probe_bit
• probe_xreal
• probe_real

can be used to record the waveforms of the signals with the corresponding data types (xbit, bit, xreal, and real, respectively). Their basic usage is:

probe_<data_type>  <instance_name> (<signal_name>);

Users can specify parameters for these probe instances such as:

• filename : the output filename and format (by its extension)
• start : the absolute time to start the waveform recording
• stop : the absolute time to start the waveform recording
• format : the JEZ format string (“jezbinary” or “jezascii“)

For the most up-to-date information, please refer to the online documentation (e.g. by typing xmodel -h probe_xbit for example).

On the other hand, a property probe records a chosen time-varying property of a signal. The examples are:

• probe_freq : records the frequency of a clock signal
• probe_phase : records the phase of a clock signal
• probe_period : records the period of a clock signal
• probe_duty : records the duty-cycle of a clock signal
• probe_delay : records the delay between two signals
• probe_ber : records the error rate between two binary data signals

For the detailed usage of each property primitive, please refer to the online documentation (e.g. by typing xmodel -h probe_freq for example).

Waveform Recording Using XMODEL System Calls

In addition to the measurement probe primitives, XMODEL provides a set of system calls to facilitate waveform dumping. Such XMODEL system calls are listed in the table below:

Table. List of XMODEL system calls for waveform dumping

These system calls are actually analagous to the standard Verilog system calls such as $dumpfile, $dumpvars, $dumpon, and so on, and have similar functionalities with the corresponding calls. However, there are some differences in their detailed usages.

The Simplest Example

The simplest way to use these system calls and record the signals’ waveforms into a file is to insert the following code snippet into your top-level testbench module:

initial begin
     $xmodel_dumpfile();
     $xmodel_dumpvars();
end

It will then dump all the signals in the current module and all the hierarchies below it into a file named "xmodel.jez" in the JEZ format.

Usage of $xmodel_dumpfile

$xmodel_dumpfile system call defines the name and format of the waveform dump file. Its basic usage is:

$xmodel_dumpfile ( [filename], [version] );

or,

$xmodel_dumpfile ( [option spec]* );

where […] denotes optional arguments. The first format takes up to two positional arguments (filename and version) and the second format takes a set of option specifying arguments which may come in an arbitrary order.

The description for each argument is as follows:

• filename: defines the name and format of the waveform dump file. For instance, a file name with a ".jez" extension selects the JEZ format while one with ".fsdb" selects FSDB). The default value is "xmodel.jez".
• version: specifies the version of the file format. Currently this argument is used only for JEZ format files. For instance, "jezbinary" selects JEZ binary format while "jezascii" selects JEZ ascii format. The default value is "jezbinary".
• option spec: Each option spec argument can be either a single string of “arg=value” or a pair of “arg=” and value arguments. The former is good for conciseness and the latter is good for passing parameter values stored in variables. Multiple string-type arguments can be combined into a single string argument using colon separators (e.g. “arg1=value1:arg2=value2“). If no option spec arguments are given, the default values are assumed.

The available ption spec arguments are listed as follows:

• filename=<filename> : the name and format of the waveform dump file. For instance, a file name with a “.jez” extension selects the JEZ format while one with “.fsdb” selects FSDB). The default value is “xmodel.jez“.
• version=<version> : the version of the waveform file format. Currently it is used only for JEZ format files. For instance, “jezbinary” selects JEZ binary format while “jezascii” selects JEZ ascii format. The default value is “jezbinary“.
• scopesep=<scope separator> : the delimiting string separating different levels of the hierarchy scopes. Currently, this option is effective only with FSDB format. The default value is “.“.

Examples

initial begin
      $xmodel_dumpfile();
      $xmodel_dumpvars();
end

: dumps the waveforms of all the signals in the current module and all the hierarchies below it into a file named "xmodel.jez" in JEZ binary format.

$xmodel_dumpfile ("xmodel.jez", "jezascii");

: the same except that the waveform file is in JEZ ascii format (i.e. the content is human readable).

$xmodel_dumpfile ("xmodel.fsdb");

: the same except that the waveforms are recorded into a file named "xmodel.fsdb" in FSDB format.

$xmodel_dumpfile ("filename=", "xmodel.fsdb", "scopesep=", ":");

: dumps the waveform into a file named “xmodel.fsdb” in FSDB format, using “:” as the scope separator instead of the default “.“. For instance, the hierarchy node name TOP.INST1.INST2.n1 will be stored and accessible as TOP:INST1:INST2:n1. This example also demonstrates the use of option specifiers.

$xmodel_dumpfile ("xmodel.fsdb", "scopesep=:");

: the same example demonstrating the mixed usage of a positional argument (filename) and optional specifier (scopesep=).

Usage of $xmodel_dumpvars

$xmodel_dumpvars system call defines the signal variables to be monitored and dumped during the simulation. Its basic usage is:

$xmodel_dumpvars ( [option spec]*, [module or variable name]* );

where […] denotes optional arguments. The asterisk (*) mark indicates that an arbitrary number of arguments can be supplied. However, all the option spec arguments must precede the module or variable name arguments.

The description for each argument is as follows:

• option spec: defines the control parameters. Each option spec argument can be either a single string of “arg=value” or a pair of “arg=” and value arguments. The former is good for conciseness and the latter is good for passing parameter values stored in variables. Multiple string-type arguments can be combined into a single string argument using comma separators (e.g. “arg1=value1:arg2=value2“). If no option spec arguments are given, the default control parameter values are assumed.
• module or variable name: defines a module or variable of which value changes are to be monitored and recorded. If no module or variable name arguments are given, the current module is assumed as a default.

The available control parameters that can be used in the option spec arguments are listed as follows:

• level=<depth> : the level of monitoring depth. For instance, “level=0” means the current level and all lower levels below. “level=1” means the current level only. “level=2” means the current level and one level below.
• type=<vartype1>,<vartype2>,... : a comma-separated list of variable types to be monitored. Possible types are xbit, xreal, reg, wire, bit, int, integer, and real.
• probe=<probespec1>,<probespec2>,... : a comma-separated list of probe specifiers, defining the internal probe options for circuit-level primitives. For instance, one can optionally probe the terminal voltage (“V“), branch current (“I“), or power consumption (“P“) of certain circuit-level primitives including resistor, capacitor, inductor, diode, nmosfet, and pmosfet. Each probe specifier takes a format of “<primitive name>.<variable>“, where <primitive name> can be resistor, capacitor, inductor, diode, nmosfet, or pmosfet, and <variable> can be V, I, or P.
• stat=<statistical mode (1 or 0)> : a flag to enable/disable statistical data recording; it is used only for JEZ format.
• start=<start time> : absolute time (in seconds) to start the waveform dumping.
• stop=<stop time> : absolute time (in seconds) to stop the waveform dumping.

Examples

initial begin
      $xmodel_dumpfile();
      $xmodel_dumpvars();
end

: dumps the waveforms of all the signals in the current module and all the hierarchies below it into a file named "xmodel.jez" in JEZ binary format.

$xmodel_dumpvars ("type=xbit,xreal");

: dumps all the xbit and xreal-typed variables in the current module and below.

$xmodel_dumpvars ("level=1", module1);

: dumps only the variables in module1.

$xmodel_dumpvars ("level=1", "probe=nmosfet.I,pmosfet.I");

: additionally dumps the current (I) information of the nmosfet and pmosfet primitive instances in the current module and below.

$xmodel_dumpvars ("probe=resistor.V,resistor.I,resistor.P", module1);

: additionally dumps the voltage (V), current (I), and power (P) information of the resistor primitive instances in module1.

$xmodel_dumpvars ("start=10e-9:stop=200e-9", var1, var2, var3);

: dumps the value changes of the signal variables var1, var2, var3 from 10ns to 200ns.

$xmodel_dumpvars ("level=0:stat=1");

: dumps all the variables in the current scope and below with the statistical recording option on.

$xmodel_dumpvars ("level=", 0, "stat=", 1);

: demonstrates the usage of name-value pair of option spec arguments. It dumps all the variables in the current scope and below with the statistical recording option on.

Usage of Other System Calls for Waveform Recording

The following four XMODEL system calls are used with no arguments and have the same functionalities with the corresponding Verilog system calls (e.g. $dumpon, $dumpoff, etc.)

• $xmodel_dumpon() : enables waveform recording.
• $xmodel_dumpoff() : disables waveform recording.
• $xmodel_dumpall() : dumps all the variables at the current timestep.
• $xmodel_dumpflush() : flushes the buffer content to the file.

Examples

initial begin
      $xmodel_dumpfile();
      $xmodel_dumpvars();

      #1000; $xmodel_dumpoff();
      #1000; $xmodel_dumpall();
      #1000; $xmodel_dumpon();
end

: This example starts by recording all the variables in the current module and below into a file named "xmodel.jez". However, at 1000 time units, the $xmodel_dumpoff() system call stops the recording. After another 1000 time units (i.e., at 2000 time units), the $xmodel_dumpall() system call dumps the value information of all the variables being monitored. Finally, at 3000 time units, the $xmodel_dumpon() call resumes the waveform recording.