Verilog-XL System Tasks and Functions

Verilog-XL System Tasks and Functions

You can access information on the following Verilog-XL Version 2.7 features: Back to the Quick Reference main page

Conventions for System Tasks and Function Syntax

Symbols Description
bold or italic Bold or italic text indicates a system task or function keyword. Online HTML 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(...);

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

$async$or$array(...);
$async$or$plane(...);
 Lets you define programmable logic array (PLA) tasks in Verilog HDL.
$bitstoreal(<variable>); Converts a variable from a bit pattern to a real number.
$cleartrace; Disables the tracing of simulation activity started by the $settrace system task.
$compare(<enable>,<expected_value>,
<simulated_value>
<,<expected_value>,<simulated_value>>*); 		Issues a discrepancy message if an expected value and a simulated value differ during the time window in which the task runs.
$countdrivers(<net>, <net_is_forced>,
<number_of_01x_drivers>, <number_of_0_drivers>,
<number_of_1_drivers>, <number_of_x_drivers>); 		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 a bit-select of an expanded vector net. The number of parameters to 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.
$db_breakaftertime(<time>); Sets a breakpoint at the end of a time unit that you specify.
$db_breakatline(<line_no>
<,<scope> <,<filename>>? >? ); 		Sets a breakpoint at the line that you specify; Verilog-XL stops executing each time that it encounters the specified line.
$db_breakbeforetime(<time>); Sets a breakpoint at the beginning of a time unit that you specify.
$db_breakonceatline(<line_no>
<,<scope> <,<filename>>? >? ); 		Sets a breakpoint at the line that you specify; Verilog-XL stops executing the first time it encounters the specified line.
$db_breakonceonnegedge(<object>); Sets a transition-based breakpoint; Verilog-XL breaks the first time a negative-edge transition occurs on the specified object.
$db_breakonceonposedge(<object>); Sets a transition-based breakpoint; Verilog-XL breaks the first time a positive-edge transition occurs on the specified object.
$db_breakoncewhen(<object> <,<value>>? ); Sets a breakpoint dependent on the value of a given object; Verilog-XL breaks the first time the object has the specified value.
$db_breakonnegedge(<object>); Sets a transition-based breakpoint; Verilog-XL breaks each time a negative-edge transition occurs on the specified object.
$db_breakonposedge(<object>); Sets a transition-based breakpoint; Verilog-XL breaks each time a postive-edge transition occurs on the specified object.
$db_breakwhen(<object> <,<value>>? ); Sets a breakpoint dependent on the value of a given object; Verilog-XL breaks each time the object has the specified value.
$db_cleartrace; Turns off trace-stepping mode.
$db_deletebreak;
$db_deletebreak(<break_id> <,<break_id>>*); 		Deletes a given set of breakpoints from the breakpoint list.
$db_deletefocus;
$db_deletefocus(<focus_id_or_scope>
<,<focus_id_or_scope>>*); 		Removes the foci that you specify from the focus list.
$db_disablebreak;
$db_disablebreak(<break_id> <,<break_id>>*); 		Disables a given set of breakpoints in the breakpoint list.
$db_disablefocus;
$db_disablefocus(<focus_id_or_scope>
<,<focus_id_or_scope>>*); 		Disables the foci that you specify; the foci remain in the focus list.
$db_enablebreak;
$db_enablebreak(<break_id> <,<break_id>>*); 		Enables a given set of breakpoints in the breakpoint list.
$db_enablefocus;
$db_enablefocus(<focus_id_or_scope>
<,<focus_id_or_scope>>*); 		Enables the foci that you specify.
$db_help; Displays a list of the interactive debugging commands.
$db_setfocus(<scope> <,<scope>>*); Lets you set the scope for debugging operations by adding one or more scopes to the focus list.
$db_settrace; Turns on trace-stepping mode; decompilation and results display at each step of simulation.
$db_showbreak; Displays the breakpoint list.
$db_showfocus; Displays the focus list with each entry containing the focus ID number, the hierarchical scope name, and whether the focus is enabled or disabled.
$db_step;
$db_step(<step_count>); 		Steps through the source file one or more steps, depending on the number of steps that you specify.
$db_steptime(<time_units>); Steps through the simulation by the number of time units that you specify.
$deposit(<variable>, <value>); Sets a net to a particular value and then simulates with the net set to that new value. The value change is propagated throughout the nets and registers being driven by the variable that has been set.
$disable_warnings("<keyword>"?
<,<module_instance>?>*); 		Stops displaying all warnings about timing check violations, and triregs that acquire a value of X due to charge decay. You can optionally disable specific warnings by keyword, by module instance, or by both.
$display(P1, P2, ..., Pn);
$displayb(P1, P2, ..., Pn);
$displayh(P1, P2, ..., Pn);
$displayo(P1, P2, ..., Pn); 		Displays parameters P1 through Pn, adding a new line to the end of the output. Use $display for literal format, $displayb for binary format, $displayh for hexadecimal format, and $displayo for octal format.
$dist_chi_square(<seed>,<degree_of_freedom>)
$dist_erlang(<seed>,<k_stage>,<mean>)
$dist_exponential(<seed>,<mean>)
$dist_normal(<seed>,<mean>, <standard_deviation>)
$dist_poisson(<seed>,<mean>)
$dist_t(<seed>,<degree_of_freedom>)
$dist_uniform(<seed>, <start>, <end>) 		These are random number generators that return integer values distributed according to standard probabillistic functions.
$dumpall; Creates a checkpoint in the value change dump file that shows the current values of its variables.
$dumpfile(<filename>); Specifies the name of the value change dump file. If you do not specify a dump filename, the default name is verilog.dump.
$dumpflush; Empties the dump file buffer and ensures that all the data in that buffer is stored in the value change dump file.
$dumplimit(<file_size>); Sets the size of the value change dump file.
$dumpoff; Stops Verilog-XL from recording value changes in the value change dump file.
$dumpon; Resumes recording value changes in the value change dump file.
$dumpvars(<levels> <,<module_or_variable>>* ); Specifies the variables whose changing values are recorded in the value change dump file.
$enable_warnings("<keyword>"?
<,<module_instance>>*?); 		Displays all warning messages about timing check violations, and about triregs that acquire a value of X due to charge decay. You can optionally enable specific warnings by keyword, by module instance, or by both.
$fdisplay(<multichannel_descriptor>, P1, P2, ... , Pn);
$fdisplayb(<multichannel_descriptor>, P1, P2, ... , Pn);
$fdisplayh(<multichannel_descriptor>, P1, P2, ... , Pn);
$fdisplayo(<multichannel_descriptor>, P1, P2, ... , Pn);
 Prints parameters P1 through Pn to the multichannel descriptor adding a new line to the end of the output.

Use $fdisplay for literal format, $fdisplayb for binary format, $fdisplayh for hexadecimal format, and $fdisplayo for octal format.

$finish;
$finish(n); 		Halts the simulator, passing control to the operating system. The optional parameter can be 0 (print nothing), 1 (print simulation time and location), or 2 (print simulation time, location, and statistics about memory and CPU time).
$fmonitor(<multichannel_descriptor>, P1, P2, ..., Pn);
$fmonitorb(<multichannel_descriptor>, P1, P2, ..., Pn);
$fmonitorh(<multichannel_descriptor>, P1, P2, ..., Pn);
$fmonitoro(<multichannel_descriptor>, P1, P2, ..., Pn);
 Monitors and displays, in literal format, the values of any variables or expressions specified as parameters to the multichannel descriptor. Use $fmonitor for literal format, $fmonitorb for binary format, $fmonitorh for hexadecimal format, and $fmonitoro for octal format.
$fopen("<filename>") Opens the specified file and returns a 32-bit unsigned multichannel descriptor that is uniquely associated with the file. The function returns 0 if the specified file cannot be opened for writing. The $fopen function reuses channels that have been closed.
$fclose(<multichannel_descriptor>); Closes the channels specified in the multichannel descriptor, and does not allow any further output to the closed channels.
$fstrobe(<multichannel_descriptor>, P1, P2, ..., Pn);
$fstrobeb(<multichannel_descriptor>, P1, P2, ..., Pn);
$fstrobeh(<multichannel_descriptor>, P1, P2, ..., Pn);
$fstrobeo(<multichannel_descriptor>, P1, P2, ..., Pn); 		Displays the specified information at the end of the time unit in the multichannel descriptor. Use $fstrobe for literal format, $fstrobeb for binary format, $fstrobeh for hexadecimal format, and $fstrobeo for octal format.
$fwrite(<multichannel_descriptor>, P1, P2, ... , Pn);
$fwriteb(<multichannel_descriptor>, P1, P2, ... , Pn);
$fwriteh(<multichannel_descriptor>, P1, P2, ... , Pn);
$fwriteo(<multichannel_descriptor>, P1, P2, ... , Pn); 		Prints parameters P1 through Pn in literal format to the multichannel descriptor. Use $fwrite for literal format, $fwriteb for binary format, $fwriteh for hexadecimal format, and $fwriteo for octal format.
$get_pattern(<mem_element>); Reads the stimulus patterns that have been loaded into a memory using the $readmemb or $readmemh system tasks.
$history; Displays out a numbered list of all the interactive commands that have been entered. Active commands are indicated by an asterisk (*) next to the command number.
$hold(<clk_event>,<data_event>,
<hold_limit>,<notifier>); 		Determines whether a data signal remains stable for a period of time after a transition in an enabling signal, such as a clock signal that latches data in a memory. (See the SDF Annotator Guide.)
$incpattern_read(<filename>,
<end_of_file>,<variable_list>); 		Reads an incremental pattern file and places the values in that file on expanded or accelerated nets.
$incpattern_write(<filename>,<variable_list>); Writes an incremental pattern file that stores only the changes in the values of nets or register arguments that occur at the end of each time unit. The system task ignores all redundant information.
$incsave("<incremental_filename>"); Saves only what has changed since the last invocation of $save. You 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.
$itor(<variable>); Converts integers to real values (for example, 123 becomes 123.0).
$keepcommands; Adds all subsequent interactive commands to the history stack. (This is the default behavior. See also $nokeepcommands.)
$key;
$key("<filename>"); 		Creates a file that contains all successful interactive commands. Interactive input that results in a syntax error is not included in this file. If you do not specify a filename, verilog.key is created.
$list;
$list(<name>); 		Lists the module, task, function, or named block of the current scope. The <name> parameter must refer to a specific module, task, function or named block, in which case the specified object is listed.
$list_forces;
$list_forces("<filename>"); 		Lists the currently active force statements with the full hierarchical names of the nets and registers subject to those force statements. The optional filename specifies a file to which Verilog-XL writes the list.
$listcounts;
$listcounts(<name>); 		An expanded version of the $list system task that produces a line-numbered source listing that includes a statement execution count. This system task must be used in conjunction with the +listcounts option on the command line to enable the task.
$log;
$log("<filename>"); 		Creates a file containing the output 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.
$monitor(P1,P2,...,Pn);
$monitorb(P1, P2, ..., Pn);
$monitorh(P1, P2, ..., Pn);
$monitoro(P1, P2, ..., Pn); 		Monitors and displays the values of any variables or expressions specified as parameters to the task.

Use $monitor for literal format, $monitorb for binary format, $monitorh for hexadecimal format, and $monitoro for octal format.

$monitoroff; Disables monitoring with $monitor.
$monitoron; Enables monitoring with $monitor.
$nokeepcommands; Disables the saving of interactive 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;
$no_show_cancelled_e(<path_output>+); 		Disables the display of cancelled schedules.
$period(<clk_event>,
<period_limit>,<notifier>); 		Issues a violation when a clock event of the same edge occurs within the specified time. (See the SDF Annotator Guide.)
$printtimescale(<hierarchical_path_name>?); Displays the time unit and precision of a particular module.
$pulsestyle_ondetect; Enables the on-detect method for resolving cancelled schedule dilemmas on transport path delays.
$pulsestyle_onevent; Enables the on-event method for resolving cancelled schedule dilemmas on transport path delays.
$q_add(<q_id>,<job_id>,
<inform_id>,<status>) 		Places a job on the specified queue.
$q_exam(<q_id>,<q_stat_code>,
<q_stat_value>,<status>) 		Provides information about the 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>,
<max_length>,<status>) 		Creates a new queue.
$q_remove(<q_id>,<job_id>,
<inform_id>,<status>) 		Removes a job from the specified queue.
$random;
$random(<seed>); 		Returns a new 32-bit random signed integer. The <seed> parameter controls the numbers that $random returns and must be either a register, integer, or time variable. The <seed> parameter must be assigned its variable prior to calling $random.
$readmemb("<filename>", <memname>
<<, <start_addr>><, <finish_addr>>?>?);

$readmemh("<filename>", <memname>
<<, <start_addr>><, <finish_addr>>?>?);
 Reads and loads data from the specified text file (white space, comments, and numbers only) into the specified memory. Use $readmemb for binary format, and use $readmemh for hexadecimal format.
$realtime; Returns a real number, scaled to the time unit of the module that invoked it.
$realtobits(<variable>); Passes bit patterns across module ports; converts the specified variable from a real number to the 64-bit representation (vector) of that real number.
$recovery(<control_event>,<clk_event>,
<recovery_limit>, <notifier>?);		 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 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.)
$recrem(<control_event>,<clk_event>,
<recovery_limit>,<removal_limit>,
<notifier>?,<tstamp_cond>?,<tcheck_cond>?,
<delayed_clk>?,<delayed_data>?;); 		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 flip-flop). A violation occurs when the value of the asynchronous signal changes within the specified 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.)
$removal(<control_event>,<clk_event>,
<recovery_limit>, <notifier>?);		 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 flip-flop). A violation occurs when 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.)
$reportprofile(<max_lines>?); Produces the following reports before the end of simulation:
  • Profile ranking by statement
  • Profile ranking by module instance
  • Profile ranking by statement class
  • Profile ranking by statement type
$reset<(<stop_value>,
<<reset_value><,<diagnostics_value>>>)>; 		Resets the simulation time to 0. If 0 or no argument is given, $reset enters interactive mode; other values cause Verilog-XL to continue simulating from time 0.
$reset_count; Returns an integer that represents the number of times you called the $reset system task since you invoked Verilog-XL. The initial value of this integer is 0.
$reset_value; 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 the $reset function call. You can use this system function to communicate information from one reset run to the next.
$restart("<filename>"); Restores a previously-saved data structure from the specified file.
$rtoi(<variable>); Converts real values to integers by truncating the real values (for example, 123.45 becomes 123).
$save("<filename>"); Saves the entire data structure into the specified file.
$scale; Scales the time unit from one module so that it can be used with the time unit of another module.
$scope(<name>); Assigns a particular level of hierarchy as the interactive scope for identifying objects. The <name> parameter must be the complete hierarchical name of a 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">, <module_instance>?,
<"config_file">?, <"log_file">?, <"mtm_spec">?,
<"scale_factors">?, <"scale_type">? ); 		Invokes the SDF annotator. If you want to use SDF annotation at times other than time 0, use the +annotate_any_time plus option on the command line. (See the SDF Annotator Guide.)
$settrace; Enables thetracing of all simulation activity, including the current simulation time, the location in the source file description of the active statement, a full decompilation of the active statement, and the results of the execution of the active statement.
$setup(<data_event>,<clk_event>,
<setup_limit>,<notifier>); 		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 latches data in memory. A violation occurs when a change to the signal occurs within the specified time limit before the clock event. (See the SDF Annotator Guide.)
$setuphold(<clk_event>,<data_event>,
<setup_limit>,<hold_limit>,<notifier>,
<tstamp_cond>,<tcheck_cond>,
<delayed_clk>,<delayed_data>); 		Combines the functionality of $setup and $hold into one system task. It also offers additional functionality in the form of negative time specifications. A violation occurs when a change to the signal occurs within the specified time limits. (See the SDF Annotator Guide.)
$shm_close; Closes the open waveform database.
$shm_open(<database_name>); Opens a specified waveform database.
$shm_probe(<signal>); Specifies a list of signals whose value changes enter the open database.
$shm_save; Saves the open waveform database.
$show_cancelled_e;
$show_cancelled_e(<path_output>+); 		Displays cancelled schedules in specify blocks.
$showallinstances; Displays the number of instances of each module, gate, and primitive in the entire design hierarchy. Also, for modules and UDPs, this task identifies the name of the file that contains their definitions.
$showexpandednets; Lists all of the vector nets that have been expanded during compilation.
$showmodes;
$showmodes(<constant>); 		Displays the delay modes of the current scope and its subscopes in effect for particular modules during simulation. If you specify no argument or 0, displays only the delay mode of the current scope.
$shownonxl; Shows all non-accelerated structures.
$showportsnotcollapsed; Lists all module ports that have not been collapsed during compilation.
$showscopes;
$showscopes(n); 		Lists modules, tasks, functions, and named blocks defined at the current scope level. When n is not zero, all of the modules, tasks, functions, 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.
$showvars;
$showvars(<variable_list>); 		Produces status information for register and net variables, both scalar and vector. Without parameters, shows the status information for the current scope. With a list of variables, shows the status information only for the specified variables.
$showvariables(n);
$showvariables(n,<variable_list>); 		Same as $showvars except that n is a number from 0-7 that specifies one of 8 ways to display the output.
$skew(<clk_1>,<clk_2>,
<skew_limit>,<notifier>); 		Specifies the maximum delay 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>,
<string1>,<string2>,,,);

$sreadmemh(<mem_name>,
<start_addr>,<finish_addr>,
<string1>,<string2>,,,); 		Loads data into memory from a source character string. Use $sreadmemb for binary format and $sreadmemh for hexadecimal format.
$stime; Returns the current simulation time as a 32-bit integer.
$startprofile;
$startprofile(<sampling_factor>); 		Invokes the behavior profiler, taking samples of the simulation.
$stop;
$stop(n); 		Halts the simulator, issues an interactive command prompt, and passes control to the user. The optional parameter can be 0 (print nothing), 1 (print simulation time and location), or 2 (print simulation time, location, and statistics about memory and CPU time).
$stopprofile; Stops the behavior profiler from taking samples.
$strobe(P1, P2, ..., Pn);
$strobeb(P1, P2, ..., Pn);
$strobeh(P1, P2, ..., Pn);
$strobeo(P1, P2, ..., Pn); 		Displays the specified information at the end of the time unit. Use $strobe for literal format, $strobeb for binary format, $strobeh for hexadecimal format, and $strobeo for octal format.
$strobe_compare(<expected_value>,
<simulated_value><,<expected_value>,
<simulated_value>>*); 		Issues a discrepancy message if a value produced by a simulation and the corresponding expected value differ at the end of the single time unit in which the task runs.
$sync$and$array(...);
$sync$and$plane(...);

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

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

$sync$or$array(...);
$sync$or$plane(...);
 Lets you define programmable logic array (PLA) tasks in Verilog HDL.
$time; Returns a 64-bit integer, scaled to the time unit of the module that invoked it.
$timeformat(<units_number>,<precision_number>,
<suffix_string>,<minimum_field_width>); 		Specifies a uniform time unit, time precision, and format for reporting timing information from various modules that use different time units and precisions.
$width(<edge_clk>,
<min_limit>,<threshold>,<notifier>); 		Specifies the duration of signal levels from one clock edge to the opposite clock edge. A violation occurs when signals are too close together. If you use edge specifiers, all edges must be of the same direction. (See the SDF Annotator Guide.)
$write(p1, p2, ..., pn);
$writeb(p1, p2, ..., pn);
$writeh(p1, p2, ..., pn);
$writeo(p1, p2, ..., pn);
 Displays parameters p1 through pn. Use $write for literal format, $writeb for binary format, $writeh for hexadecimal format, and $writeo for octal format.

Copyright © 1990-98 Cadence Design Systems, Inc. All rights reserved. Printed in the United States of America. Cadence Design Systems, Inc., 555 River Oaks Parkway, San Jose, CA 95134, USA

Confidentiality Notice No part of this publication may be reproduced in whole or in part by any means (including photocopying or storage in an information storage/retrieval system) or transmitted in any form or by any means without prior written permission from Cadence Design Systems, Inc. (Cadence). Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence. The information contained herein is the proprietary and confidential information of Cadence or its licensors, and is supplied subject to, and may be used only by Cadence's customer in accordance with, a written agreement between Cadence and its customer. Except as may be explicitly set forth in such agreement, Cadence does not make, and expressly disclaims, any representations or warranties as to the completeness, accuracy or usefulness of the information contained in this document. Cadence does not warrant that use of such information will not infringe any third party rights, nor does Cadence assume any liability for damages or costs of any kind that may result from use of such information.

RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.