Verilog-XL System Tasks and Functions

Conventions for System Tasks and Function Syntax

Symbols Description

bold or Bold or italic text indicates a system task or function keyword. Online HTML
italic versions also distinguish these with color.

Angle brackets around each argument are added for clarity and are not literal
<>
symbols-that is, they do not appear in the actual code.

The question mark indicates that the argument is optional in the system task or
?
function.

* The asterisk indicates that you can specify zero or more of these arguments.

+ The plus sign indicates that you can specify one or more of these arguments.

... The ellipsis indicates omitted information.

System Tasks and Function Syntax

Task or Function Syntax Description

$async$and$array(...);
$async$and$plane(...);

$async$nand$array(...);
$async$nand$plane(...); Lets you define programmable
logic array (PLA) tasks in Verilog
$async$nor$array(...); HDL.
$async$nor$plane(...);

$async$or$array(...);
$async$or$plane(...);

Converts a variable from a bit

$bitstoreal(<variable>);
pattern to a real number.

Disables the tracing of simulation

$cleartrace; activity started by the $settrace
system task.
 Issues a discrepancy message if an
$compare(<enable>,<expected_value>,
expected value and a simulated
<simulated_value>
value differ during the time
<,<expected_value>,<simulated_value>>*);
window in which the task runs.

Counts the number of drivers on a

specified net so that bus contention
can be identified. Returns a 0 if
there is no more than one driver on
the net, and returns a 1 otherwise
(indicating contention). The
specified net must be a scalar net or
$countdrivers(<net>, <net_is_forced>,
a bit-select of an expanded vector
<number_of_01x_drivers>, <number_of_0_drivers>,
net. The number of parameters to
<number_of_1_drivers>, <number_of_x_drivers>);
the system function may vary
according to how much information
is desired. The net parameter is
required; the rest are optional.
Include commas to hold the places
of parameters that you are not
using.

Sets a breakpoint at the end of a

$db_breakaftertime(<time>);
time unit that you specify.

Sets a breakpoint at the line that

$db_breakatline(<line_no> you specify; Verilog-XL stops
<,<scope> <,<filename>>? >? ); executing each time that it
encounters the specified line.

Sets a breakpoint at the beginning

$db_breakbeforetime(<time>);
of a time unit that you specify.

Sets a breakpoint at the line that

$db_breakonceatline(<line_no> you specify; Verilog-XL stops
<,<scope> <,<filename>>? >? ); executing the first time it
encounters the specified line.

Sets a transition-based breakpoint;

Verilog-XL breaks the first time a
$db_breakonceonnegedge(<object>);
negative-edge transition occurs on
the specified object.

Sets a transition-based breakpoint;

Verilog-XL breaks the first time a
$db_breakonceonposedge(<object>);
positive-edge transition occurs on
the specified object.
 Sets a breakpoint dependent on the
value of a given object; Verilog-XL
$db_breakoncewhen(<object> <,<value>>? );
breaks the first time the object has
the specified value.

Sets a transition-based breakpoint;

Verilog-XL breaks each time a
$db_breakonnegedge(<object>);
negative-edge transition occurs on
the specified object.

Sets a transition-based breakpoint;

Verilog-XL breaks each time a
$db_breakonposedge(<object>);
postive-edge transition occurs on
the specified object.

Sets a breakpoint dependent on the

value of a given object; Verilog-XL
$db_breakwhen(<object> <,<value>>? );
breaks each time the object has the
specified value.

$db_cleartrace; Turns off trace-stepping mode.

$db_deletebreak; Deletes a given set of breakpoints

$db_deletebreak(<break_id> <,<break_id>>*); from the breakpoint list.

$db_deletefocus;
Removes the foci that you specify
$db_deletefocus(<focus_id_or_scope>
from the focus list.
<,<focus_id_or_scope>>*);

$db_disablebreak; Disables a given set of breakpoints

$db_disablebreak(<break_id> <,<break_id>>*); in the breakpoint list.

$db_disablefocus;
Disables the foci that you specify;
$db_disablefocus(<focus_id_or_scope>
the foci remain in the focus list.
<,<focus_id_or_scope>>*);

$db_enablebreak; Enables a given set of breakpoints

$db_enablebreak(<break_id> <,<break_id>>*); in the breakpoint list.

$db_enablefocus;
$db_enablefocus(<focus_id_or_scope> Enables the foci that you specify.
<,<focus_id_or_scope>>*);

Displays a list of the interactive

$db_help;
debugging commands.

$db_setfocus(<scope> <,<scope>>*); Lets you set the scope for

 debugging operations by adding
one or more scopes to the focus list.

Turns on trace-stepping mode;

$db_settrace; decompilation and results display at
each step of simulation.

$db_showbreak; Displays the breakpoint list.

Displays the focus list with each

entry containing the focus ID
$db_showfocus; number, the hierarchical scope
name, and whether the focus is
enabled or disabled.

Steps through the source file one or

$db_step;
more steps, depending on the
$db_step(<step_count>);
number of steps that you specify.

Steps through the simulation by the

$db_steptime(<time_units>); number of time units that you
specify.

Sets a net to a particular value and

then simulates with the net set to
that new value. The value change is
$deposit(<variable>, <value>);
propagated throughout the nets and
registers being driven by the
variable that has been set.

Stops displaying all warnings about

timing check violations, and triregs
that acquire a value of X due to
$disable_warnings("<keyword>"?
charge decay. You can optionally
<,<module_instance>?>*);
disable specific warnings by
keyword, by module instance, or by
both.

Displays parameters P1 through

Pn, adding a new line to the end of
$display(P1, P2, ..., Pn);
the output. Use $display for literal
$displayb(P1, P2, ..., Pn);
format, $displayb for binary
$displayh(P1, P2, ..., Pn);
format, $displayh for hexadecimal
$displayo(P1, P2, ..., Pn);
format, and $displayo for octal
format.

$dist_chi_square(<seed>,<degree_of_freedom>) These are random number

$dist_erlang(<seed>,<k_stage>,<mean>)
$dist_exponential(<seed>,<mean>)
$dist_normal(<seed>,<mean>, generators that return integer values
<standard_deviation>) distributed according to standard
$dist_poisson(<seed>,<mean>) probabillistic functions.
$dist_t(<seed>,<degree_of_freedom>)
$dist_uniform(<seed>, <start>, <end>)

Creates a checkpoint in the value

$dumpall; change dump file that shows the
current values of its variables.

Specifies the name of the value

change dump file. If you do not
$dumpfile(<filename>);
specify a dump filename, the
default name is verilog.dump.

Empties the dump file buffer and

ensures that all the data in that
$dumpflush;
buffer is stored in the value change
dump file.

Sets the size of the value change

$dumplimit(<file_size>);
dump file.

Stops Verilog-XL from recording

$dumpoff; value changes in the value change
dump file.

Resumes recording value changes

$dumpon;
in the value change dump file.

Specifies the variables whose

$dumpvars(<levels> <,<module_or_variable>>* ); changing values are recorded in the
value change dump file.

Displays all warning messages

about timing check violations, and
about triregs that acquire a value of
$enable_warnings("<keyword>"?
X due to charge decay. You can
<,<module_instance>>*?);
optionally enable specific warnings
by keyword, by module instance, or
by both.

$fdisplay(<multichannel_descriptor>, P1, P2, ... , Prints parameters P1 through Pn to

Pn); the multichannel descriptor adding
$fdisplayb(<multichannel_descriptor>, P1, P2, ... , a new line to the end of the output.
Pn);
$fdisplayh(<multichannel_descriptor>, P1, P2, ... , Use $fdisplay for literal format,
Pn); $fdisplayb for binary format,
$fdisplayo(<multichannel_descriptor>, P1, P2, ... , $fdisplayh for hexadecimal format,
Pn); and $fdisplayo for octal format.

Halts the simulator, passing control

to the operating system. The
optional parameter can be 0 (print
$finish;
nothing), 1 (print simulation time
$finish(n);
and location), or 2 (print simulation
time, location, and statistics about
memory and CPU time).

Monitors and displays, in literal

$fmonitor(<multichannel_descriptor>, P1, P2, ...,
format, the values of any variables
Pn);
or expressions specified as
$fmonitorb(<multichannel_descriptor>, P1, P2, ...,
parameters to the multichannel
Pn);
descriptor. Use $fmonitor for literal
$fmonitorh(<multichannel_descriptor>, P1, P2, ...,
format, $fmonitorb for binary
Pn);
format, $fmonitorh for hexadecimal
$fmonitoro(<multichannel_descriptor>, P1, P2, ...,
format, and $fmonitoro for octal
Pn);
format.

Opens the specified file and returns

a 32-bit unsigned multichannel
descriptor that is uniquely
associated with the file. The
$fopen("<filename>")
function returns 0 if the specified
file cannot be opened for writing.
The $fopen function reuses
channels that have been closed.

Closes the channels specified in the

multichannel descriptor, and does
$fclose(<multichannel_descriptor>);
not allow any further output to the
closed channels.

$fstrobe(<multichannel_descriptor>, P1, P2, ..., Pn); Displays the specified information

$fstrobeb(<multichannel_descriptor>, P1, P2, ..., at the end of the time unit in the
Pn); multichannel descriptor. Use
$fstrobeh(<multichannel_descriptor>, P1, P2, ..., $fstrobe for literal format,
Pn); $fstrobeb for binary format,
$fstrobeo(<multichannel_descriptor>, P1, P2, ..., $fstrobeh for hexadecimal format,
Pn); and $fstrobeo for octal format.
$fwrite(<multichannel_descriptor>, P1, P2, ... , Pn);
Prints parameters P1 through Pn in
$fwriteb(<multichannel_descriptor>, P1, P2, ... ,
literal format to the multichannel
Pn);
descriptor. Use $fwrite for literal
$fwriteh(<multichannel_descriptor>, P1, P2, ... ,
format, $fwriteb for binary format,
Pn);
$fwriteh for hexadecimal format,
$fwriteo(<multichannel_descriptor>, P1, P2, ... ,
and $fwriteo for octal format.
Pn);

Reads the stimulus patterns that

have been loaded into a memory
$get_pattern(<mem_element>);
using the $readmemb or
$readmemh system tasks.

Displays out a numbered list of all

the interactive commands that have
$history; been entered. Active commands are
indicated by an asterisk (*) next to
the command number.

Determines whether a data signal

remains stable for a period of time
$hold(<clk_event>,<data_event>, after a transition in an enabling
<hold_limit>,<notifier>); signal, such as a clock signal that
latches data in a memory. (See the
SDF Annotator Guide.)

Reads an incremental pattern file

$incpattern_read(<filename>,
and places the values in that file on
<end_of_file>,<variable_list>);
expanded or accelerated nets.

Writes an incremental pattern file

that stores only the changes in the
values of nets or register arguments
$incpattern_write(<filename>,<variable_list>);
that occur at the end of each time
unit. The system task ignores all
redundant information.

Saves only what has changed since

the last invocation of $save. You
$incsave("<incremental_filename>"); cannot perform an incremental save
on any file other than the one
produced by the last $save.

$input("<filename>"); Enters commands from a file

instead of from the terminal. At the
end of the command file, or when
an asynchronous interrupt is issued
 from the terminal, the input is
automatically switched back to the
terminal.

Converts integers to real values (for

$itor(<variable>);
example, 123 becomes 123.0).

Adds all subsequent interactive

commands to the history stack.
$keepcommands;
(This is the default behavior. See
also $nokeepcommands.)

Creates a file that contains all

successful interactive commands.
$key; Interactive input that results in a
$key("<filename>"); syntax error is not included in this
file. If you do not specify a
filename, verilog.key is created.

Lists the module, task, function, or

named block of the current scope.
$list; The <name> parameter must refer
$list(<name>); to a specific module, task, function
or named block, in which case the
specified object is listed.

Lists the currently active force

statements with the full hierarchical
names of the nets and registers
$list_forces;
subject to those force statements.
$list_forces("<filename>");
The optional filename specifies a
file to which Verilog-XL writes the
list.

An expanded version of the $list

system task that produces a line-
numbered source listing that
$listcounts; includes a statement execution
$listcounts(<name>); count. This system task must be
used in conjunction with the
+listcounts option on the command
line to enable the task.

$log; Creates a file containing the output

$log("<filename>"); that is printed to the standard
output, including the host command
used to run Verilog-XL. If no file is
 specified, verilog.log is created.

Monitors and displays the values of

any variables or expressions
$monitor(P1,P2,...,Pn); specified as parameters to the task.
$monitorb(P1, P2, ..., Pn);
$monitorh(P1, P2, ..., Pn); Use $monitor for literal format,
$monitoro(P1, P2, ..., Pn); $monitorb for binary format,
$monitorh for hexadecimal format,
and $monitoro for octal format.

$monitoroff; Disables monitoring with $monitor.

$monitoron; Enables monitoring with $monitor.

Disables the saving of interactive

$nokeepcommands;
commands to the history stack.

$nokey; Disables the output to the key file.

$nolog; Disables the output to the log file.

$no_show_cancelled_e; Disables the display of cancelled

$no_show_cancelled_e(<path_output>+); schedules.

Issues a violation when a clock

$period(<clk_event>, event of the same edge occurs
<period_limit>,<notifier>); within the specified time. (See the
SDF Annotator Guide.)

Displays the time unit and precision

$printtimescale(<hierarchical_path_name>?);
of a particular module.

Enables the on-detect method for

$pulsestyle_ondetect; resolving cancelled schedule
dilemmas on transport path delays.

Enables the on-event method for

$pulsestyle_onevent; resolving cancelled schedule
dilemmas on transport path delays.

$q_add(<q_id>,<job_id>,
Places a job on the specified queue.
<inform_id>,<status>)

$q_exam(<q_id>,<q_stat_code>, Provides information about the

<q_stat_value>,<status>) activity of the specified queue.

$q_full(<q_id>,<status>) Checks for room for another job on

 the specified queue; returns 0 if the
queue is not full; returns 1 if the
queue is full.

$q_initialize(<q_id>,<q_type>,
Creates a new queue.
<max_length>,<status>)

$q_remove(<q_id>,<job_id>, Removes a job from the specified

<inform_id>,<status>) queue.

Returns a new 32-bit random

signed integer. The <seed>
parameter controls the numbers that
$random; $random returns and must be either
$random(<seed>); a register, integer, or time variable.
The <seed> parameter must be
assigned its variable prior to calling
$random.

Reads and loads data from the

$readmemb("<filename>", <memname> specified text file (white space,
<<, <start_addr>><, <finish_addr>>?>?); comments, and numbers only) into
the specified memory. Use
$readmemh("<filename>", <memname> $readmemb for binary format, and
<<, <start_addr>><, <finish_addr>>?>?); use $readmemh for hexadecimal
format.

Returns a real number, scaled to the

$realtime; time unit of the module that
invoked it.

Passes bit patterns across module

ports; converts the specified
$realtobits(<variable>); variable from a real number to the
64-bit representation (vector) of
that real number.

$recovery(<control_event>,<clk_event>, Specifies a minimum time limit

<recovery_limit>, <notifier>?); between an asynchronous control
signal and the next clock pulse (for
example, between the clearbar
signal and the clock signal for a
flip-flop). A violation occurs when
the value of the asynchronous
signal changes within specified
time limit. If the clock signal
violates the constraint, the output
 value is unknown. (See the SDF
Annotator Guide.)

Specifies a minimum time limit

between an asynchronous control
signal and the next clock pulse (for
example, between the clearbar
signal and the clock signal for a
$recrem(<control_event>,<clk_event>,
flip-flop). A violation occurs when
<recovery_limit>,<removal_limit>,
the value of the asynchronous
<notifier>?,<tstamp_cond>?,<tcheck_cond>?,
signal changes within the specified
<delayed_clk>?,<delayed_data>?;);
time limits. If the clock signal
violates the constraint, the output
value is unknown. You can specify
a negative time limits. (See the
SDF Annotator Guide.)

Specifies a minimum time limit

between an asynchronous control
signal and the previous clock pulse
(for example, between the clearbar
signal and the clock signal for a
$removal(<control_event>,<clk_event>, flip-flop). A violation occurs when
<recovery_limit>, <notifier>?); the value of a the asynchronous
signal occurs within specified the
time limit. If the clock signal
violates the constraint, the output
value is unknown. (See the SDF
Annotator Guide.)

Produces the following reports

before the end of simulation:

• Profile ranking by statement

• Profile ranking by module
$reportprofile(<max_lines>?); instance
• Profile ranking by statement
class

• Profile ranking by statement

type

$reset<(<stop_value>, Resets the simulation time to 0. If 0

<<reset_value><,<diagnostics_value>>>)>; or no argument is given, $reset
enters interactive mode; other
values cause Verilog-XL to
 continue simulating from time 0.

Returns an integer that represents

the number of times you called the
$reset_count; $reset system task since you
invoked Verilog-XL. The initial
value of this integer is 0.

Returns a zero if there has not yet

been a call to $reset; otherwise,
$reset value extracts the value of
the <reset_value> argument from
$reset_value;
the $reset function call. You can
use this system function to
communicate information from one
reset run to the next.

Restores a previously-saved data

$restart("<filename>");
structure from the specified file.

Converts real values to integers by

$rtoi(<variable>); truncating the real values (for
example, 123.45 becomes 123).

Saves the entire data structure into

$save("<filename>");
the specified file.

Scales the time unit from one

$scale; module so that it can be used with
the time unit of another module.

Assigns a particular level of

hierarchy as the interactive scope
for identifying objects. The
<name> parameter must be the
complete hierarchical name of a
$scope(<name>); module, task, function, or named
block. Once the $scope task is
executed, objects may be
referenced in relation to the
interactive scope established by
$scope.

$sdf_annotate( <"sdf_filename">, Invokes the SDF annotator. If you

<module_instance>?, want to use SDF annotation at
<"config_file">?, <"log_file">?, <"mtm_spec">?, times other than time 0, use the
<"scale_factors">?, <"scale_type">? ); +annotate_any_time plus option on
 the command line. (See the SDF
Annotator Guide.)

Enables thetracing of all simulation

activity, including the current
simulation time, the location in the
source file description of the active
$settrace;
statement, a full decompilation of
the active statement, and the results
of the execution of the active
statement.

Determines whether a data signal

remains stable for a period of time
before a transition in an enabling
signal, such as a clock signal that
$setup(<data_event>,<clk_event>,
latches data in memory. A violation
<setup_limit>,<notifier>);
occurs when a change to the signal
occurs within the specified time
limit before the clock event. (See
the SDF Annotator Guide.)

Combines the functionality of

$setup and $hold into one system
task. It also offers additional
$setuphold(<clk_event>,<data_event>,
functionality in the form of
<setup_limit>,<hold_limit>,<notifier>,
negative time specifications. A
<tstamp_cond>,<tcheck_cond>,
violation occurs when a change to
<delayed_clk>,<delayed_data>);
the signal occurs within the
specified time limits. (See the SDF
Annotator Guide.)

Closes the open waveform

$shm_close;
database.

Opens a specified waveform

$shm_open(<database_name>);
database.

Specifies a list of signals whose

$shm_probe(<signal>); value changes enter the open
database.

$shm_save; Saves the open waveform database.

$show_cancelled_e; Displays cancelled schedules in

$show_cancelled_e(<path_output>+); specify blocks.
 Displays the number of instances of
each module, gate, and primitive in
the entire design hierarchy. Also,
$showallinstances;
for modules and UDPs, this task
identifies the name of the file that
contains their definitions.

Lists all of the vector nets that have

$showexpandednets;
been expanded during compilation.

Displays the delay modes of the

current scope and its subscopes in
$showmodes; effect for particular modules during
$showmodes(<constant>); simulation. If you specify no
argument or 0, displays only the
delay mode of the current scope.

Shows all non-accelerated

$shownonxl;
structures.

Lists all module ports that have not

$showportsnotcollapsed;
been collapsed during compilation.

Lists modules, tasks, functions, and

named blocks defined at the current
scope level. When n is not zero, all
$showscopes; of the modules, tasks, functions,
$showscopes(n); and named blocks in or below the
current hierarchical scope are
listed. When n is zero, only objects
at the current scope level are listed.

Produces status information for

register and net variables, both
scalar and vector. Without
$showvars; parameters, shows the status
$showvars(<variable_list>); information for the current scope.
With a list of variables, shows the
status information only for the
specified variables.

Same as $showvars except that n is

$showvariables(n);
a number from 0-7 that specifies
$showvariables(n,<variable_list>);
one of 8 ways to display the output.

$skew(<clk_1>,<clk_2>, Specifies the maximum delay

<skew_limit>,<notifier>); allowable between two signals. A
 violation occurs when the signals
are too far apart. (See the SDF
Annotator Guide.)

$sreadmemb(<mem_name>,
<start_addr>,<finish_addr>, Loads data into memory from a
<string1>,<string2>,,,); source character string. Use
$sreadmemb for binary format and
$sreadmemh(<mem_name>, $sreadmemh for hexadecimal
<start_addr>,<finish_addr>, format.
<string1>,<string2>,,,);

Returns the current simulation time

$stime;
as a 32-bit integer.

$startprofile; Invokes the behavior profiler,

$startprofile(<sampling_factor>); taking samples of the simulation.

Halts the simulator, issues an

interactive command prompt, and
passes control to the user. The
$stop; optional parameter can be 0 (print
$stop(n); nothing), 1 (print simulation time
and location), or 2 (print simulation
time, location, and statistics about
memory and CPU time).

Stops the behavior profiler from

$stopprofile;
taking samples.

Displays the specified information

$strobe(P1, P2, ..., Pn); at the end of the time unit. Use
$strobeb(P1, P2, ..., Pn); $strobe for literal format, $strobeb
$strobeh(P1, P2, ..., Pn); for binary format, $strobeh for
$strobeo(P1, P2, ..., Pn); hexadecimal format, and $strobeo
for octal format.

Issues a discrepancy message if a

$strobe_compare(<expected_value>, value produced by a simulation and
<simulated_value><,<expected_value>, the corresponding expected value
<simulated_value>>*); differ at the end of the single time
unit in which the task runs.

$sync$and$array(...); Lets you define programmable

$sync$and$plane(...); logic array (PLA) tasks in Verilog
HDL.
$sync$nand$array(...);
$sync$nand$plane(...);

$sync$nor$array(...);
$sync$nor$plane(...);

$sync$or$array(...);
$sync$or$plane(...);

Returns a 64-bit integer, scaled to

$time; the time unit of the module that
invoked it.

Specifies a uniform time unit, time

precision, and format for reporting
$timeformat(<units_number>,<precision_number>,
timing information from various
<suffix_string>,<minimum_field_width>);
modules that use different time
units and precisions.

Specifies the duration of signal

levels from one clock edge to the
opposite clock edge. A violation
$width(<edge_clk>, occurs when signals are too close
<min_limit>,<threshold>,<notifier>); together. If you use edge specifiers,
all edges must be of the same
direction. (See the SDF Annotator
Guide.)

Displays parameters p1 through pn.

$write(p1, p2, ..., pn);
Use $write for literal format,
$writeb(p1, p2, ..., pn);
$writeb for binary format, $writeh
$writeh(p1, p2, ..., pn);
for hexadecimal format, and
$writeo(p1, p2, ..., pn);
$writeo for octal format.