VHDL Simili Documentation:

Command file reference: 

This chapter documents the various commands that can be used in a command file supplied to vhdle (the simulator). This command file is used in conjunction with the the -do/-list options of the simulator. The command line language documented below is for backward compatibility purposes for the command line version only. Most of this functionality will be moved to Sonata so that it can be accessed using the TCL language. However, we do intend to keep the following interface alive for as long as possible.

Before we delve into the various commands we should understand the basic syntax of the command file.

Syntax rules

• Blank lines are ignored
• Any line beginning with the '#' character is also ignored
• The first word of each line is the command.
• Commands are case sensitive. Unlike VHDL, the commands in this file are case sensitive. We have deliberately made this choice so we can avoid confusion later and stay forward compatible with other languages (Verilog, Tcl, Perl, etc).
• Each command is followed by zero or more command arguments.
• Each command will decide how it wishes to interpret it's arguments. Unless specified otherwise, the arguments are also interpreted in a case sensitive manner.

The following documentation conventions have been used in this chapter

• Optional arguments are surrounded by square brackets '[' ']'
• Choices are separated by '|' -- a | b implies a or b but not both a or b
• Braces '{' '}' enclose an item that can be repeated. { a | b } implies that a | b can be repeated zero or more times.

Command summary

add list { signal-name }

This command adds the specified signal-name(s) to the list of signals being monitored. You can use multiple such commands (or specify multiple signal-names in one command) to monitor signals. Please refer to the signal-name syntax below. The following are examples of adding various signals to the list of signals being monitored.

add list sig1 sig2(3) /u1/state1 :u1:state2 /u2/*
add list *

When absolute path names are specified (path name begins with a '/' or a ':') we first attempt to search for the signal with its full path name, failing which we attempt to search it as if it is a relative path name (by removing the leading '/' or ':'). Signal values are printed without quotes (single or double) to save space and complex data structures such as records, multi-dimensional arrays are printed as if they were aggregates (using nested parentheses and commas). Real numbers are printed with a maximum precision of 6 digits.

Note that you can monitor the same signal (or a portion thereof) multiple times. This can be helpful for example if you would like to repeat your clock (or some other control signal) every so often. We put a lot of effort into making sure that we use as less horizontal space as possible (while still being readable) and at the same time, make the list file look as tabular as we can. But sometimes, this is not possible when you have records or arrays containing numbers (integers, reals, etc.). In such cases, we are forced to estimate (rather than calculate) a reasonable column width. Note that all data columns are right justified to their estimated column width and each column is separated by a single space character.

You cannot monitor aliases or variables. Most aliases actually get optimized out by the compiler and variables cannot be monitored at this time because they do not trigger events.

SetListHeaderStyle style

This command specifies how the header of the list file should be printed. 'style' can be one of three different styles currently supported. You can experiment with the style that suites you (or your current design). The following styles are supported.

• horizontal -- This is the default style. This style uses the least number of lines. Each name is right aligned with its own data column.
• vertical -- This style also right aligns the name with its data column but prints the entire name in a columnar format (one character per line). A series of dots (.) are printed to fill the gap between the name and its data column. The number of lines consumed by this style is determined by the largest name being displayed.
• wrapped -- This style is a compromise of the above two styles. It left and bottom aligns the name to the data column and essentially uses the full width of the data column to print the name. If the name is longer than its data width, it simply wraps around.

The following is an example of that selects the vertical style.

SetListHeaderStyle vertical

If multiple SetListHeaderStyle commands are specified, the last one overrides the previous one.

Hint: We recommend using a text editor that supports splitter panes (same file in multiple sub-windows) so that you can see the header in one window and the list output in the window below. Editors such as Microsoft Word, emacs, vim, etc. are capable of doing this.

SetListStyle { delta | nodelta | collpase | nocollapse }

This command affects the contents of the body of the list file. You can specify one or more of the keywords specified above. The following is the default specification (if none is specified).

SetListStyle delta nocollapse

The following is the meaning of each of the keywords

nocollapse -- When zero delay assignments are used in a design, this has the potential of creating an additional simulation cycle without actually advancing time. Such a cycle is called a "delta cycle". During these delta cycles signal values can change. With this option, all such intermediate values are written.

collapase -- Sometimes, we might not be interested in the delta cycle information and instead, we are interested in the final value(s) assumed by all the signals being monitored at any given time. It essentially collapses the delta cycle information and only displays the "settled" or "final" values of the signals being monitored. This has a tendency of clarifying the output somewhat but has the danger of hiding glitches or other important information with regards to the order in which signals are changing.

delta -- This option create a column that prints the delta cycle number in each row of the output

nodelta -- This option suppresses the column that prints the delta cycle number.

SetListInterval start-time [ end-time ]

Sometimes, it may be useful to monitor signals only during a period of time that is of interest. On large simulations that can reduce the amount of time spent writing the list file and also reduces the size of the list file. The start-time specifies when the monitoring should begin. If no end-time is specified, it is assumed to be the end of simulation. The following is the default specification

SetListInterval 0ns

The time specification is similar to the specification of time in command line arguments for the simulator (no spaces between the number and the units). Note that if you specify a start time that is greater than the maximum simulation time, the list file may never even be written. The end-time must be greater than or equal to the start-time (or else it is silently ignored). The following example sets the time interval to be between 1us and 2.1us

SetListInterval 1us 2.1us

Signal-name(s)

The syntax used to specify signal names allows you specify full or partial signal names, all signals in a given region of your design, a specific signal from a specific region, etc. Region names are derived from the label associated with that region except for the top level region name. The top level region name is always either the name of the top-level-entity or a package-name. Sub-region names are typically labels like block label, generate label, component instantiation label, etc. A signal can be one of the following types

• A full signal name (scalar or array or record)
• A partial signal name such as an single item of an array or a record field. Examples of such signal names are x(1), ary(2,3), rec.fld, rec.fld(3), etc. Indices MUST be integers (no spaces). Indices and record fields MUST be valid for the given signal prefix. A slice is NOT allowed as a valid partial signal name.

The following syntax can be used to select a signal

signal-name	::=	[ region ] item
item	::=	* | name
name	::=	prefix [ suffix ]
suffix	::=	indices | record-field
indices	::=	'(' INTEGER {, INTEGER } ')'
record-field	::=	'.' IDENTIFIER
prefix	::=	IDENTIFIER | name
region	::=	[ absolute-path-prefix ] label { hsep label } hsep
absolute-path-prefix	::=	hsep design-unit-name hsep
design-unit-name	::=	entity-name | package-name
hsep	::=	':' | '/'
label	::=	IDENTIFIER [ '(' generate-index ')' ]
generate-index	::=	INTEGER | ENUM_LITERAL
entity-name	::=	IDENTIFIER -- must be top level entity name
package-name	::=	IDENTIFIER -- can be any package name

As noted above, you use either a ':' or a '/' as a hierarchy/region separator. A "label" can be a block or component or generate label. Note that if you have a FOR generate label, it has to be suffixed by the exact generate index you are interested in. If a region does not begin with an "hsep", it implies that the rest of the signal-name is relative to the top level of your design. If it does begin with an "hsep", then the path is an absolute name and this can be used to select signals from a package or from the top level entity name. The following are some examples of signal names (assume that the top level entity name is TOP and the design also uses a package called MYPKG

u1/sig1          -- Selects signal 'sig1' in region /top/u1
/top/u1/sig      -- Same as above
/TOP/U1/SIG      -- Same as above (case does not matter)
:top:u1:sig      -- Same as above (using ':' as a separator)
/mypkg/mysig     -- Selects mysig defined in PACKAGE MYPKG
/top/u1/*        -- All signals in region /tmp/u1
/top/u1/si*      -- Invalid
mysig            -- Selects signal 'mysig' in /TOP
*                -- Selects all signals in /TOP
ginger(1)        -- Selects index 1 of one-dim signal ginger
fred.fld         -- Selects record field 'fld' or fred
fred.fld(1)      -- Selects index 1 of fred.fld

Note that a signal name is NOT case sensitive except for portions of the name which contains VHDL extended identifiers.

Example command file and sample output:

Here is a sample command file for a vital design that models an 8-input and function. We have listed the signals at the top level of the test bench (x_and8_tb) and also signals from one level down in the hierarchy where the actual implementation lies.

# Following are relative path names
add list i7 i6 i5 i4 i3 i2 i1 i0 o 

# Following is a full path name
# It is also an example of a vectored signal
add list /x_and8_tb/vec_stim

# Following is a wild card example. Notice that it
# is using a relative path name and will cause
# the simulator to monitor all signals in the block
# labeled uut
add list uut/*

Click here to see the sample output from such a simulation using the command listed above.