Home Documentation: Introduction Python Perl PCI_Model Demo Future Other: Download Contact_Info

Perl Language Reference
Manual

All features of the python version are also available with the perl version, but at this time (Dec 18, 2002), the perl documentation and demos are out of date. Most users are using python. Contact the developer for updated perl documentation.

Introductory Notes

The perl implementation internally uses objects, but you only need basic perl programming skills to utilize ScriptSim.

To provide a shorthand for frequently accessed functions, 'magic' variables are used which, when read or written, internally result in a function call. For example, after defining:

tie $time, ScriptSim::Time, $sim;

$time is a magic variable. Reading $time invokes a ScriptSim function which returns the current simulation time. Magic variables are used frequently, but always remember that they are really function calls and often don't return the last value written to them.

Accessing the verilog signals (nets or registers) is also generally performed with 'tied' magic variables. Setting this variable sets the verilog net or register. Reading the variable returns the current net value. Generally it is useful to read the net value formatted in various ways. The 'tie' command can provide an optional format string. For example:

tie $data, ScriptSim::Arg, $sim, 3;
tie $data_x, ScriptSim::Arg, $sim, 3, "x"; # return 1 if unknown ('x' or 'z'bits are present)
tie $data_h0, ScriptSim::Arg, $sim, 3, "h0"; # format like "%0x".

Here the 3 magic variables, $data, $data_x, and $data_h0 all refer to the same verilog net. Setting the verilog net by assigning to the variable works exactly the same for all 3 variables. However, when reading the net, $data will return a numeric value, $data_x will return either '0' or '1', and $data_h0 will return a hexadecimal string with leading zeros.

In the following sections, methods which are usually accessed as tied variables are marked with '**'.

Numeric Precision and Conversion

ScriptSim supports unlimited length vectors, but perl generally uses floating point for math operations, which has a limited precision so care must be taken when operating on verilog vectors exceeding 48 bits. When setting a verilog long vector, provide a string format such as '0xffff...', or '0b101010...'. When accessing a verilog long vector, by default ScriptSim returns a string of binary digits (i.e. 0, 1, x, and z) whose length matches the vector length. For shorter vectors, ScriptSim by default returns a floating point number (with no fractional part).

In keeping with the 'spirit' of perl, unknown bits 'x' or 'z' are interpreted as 0 bits. However, the 'x' format allows you to easily check for 'x' or 'z' bits.

Python has some advantages here because it has built-in support for unlimited size numbers.

The Simulator Object

The simulator object is the basic object for all interaction with the simulation. It is returned by the following command.

$sim = new ScriptSim::Sim;

Simulator Object Methods

Simulator methods are used as in the following examples:

$parms = $sim->argc();
$module_name = $sim->module();
$path_name = $sim->path();
$product_name = $sim->product();
$current_time = $sim->time();
$time_precision = $sim->time_precision();
$time_unit = $sim->time_unit();
$sim->time_unit(-9); # sets to nanosecond resolution
$sim->time_unit("us'); # sets to microsecond resolution
$time_suffix = $sim->u();
$event_number = $sim->wait("100ns");
$sim->close();

In the following table, methods which are usually accessed as tied variables are marked with '**'.

Method Arguments Returns Description

argc None Numeric Return the number of arguments in the verilog $scriptsim() function call. Note that python uses the terminology 'function arguments', while the verilog standard calls them 'function parameters'.

event argument object, plus an optional string. 1 Configure an event on this argument to terminate an event. The optional string can be 'change', 'rising', 'falling', or 'cancel'. 'change' is the default and terminates the wait when this verilog object changes. 'rising' and 'falling' refer to transitions to 1 or 0 for single bit nets only. 'cancel' cancels any previous event configuration for this argument.

module None String Return the module name where the $scriptsim() verilog command was invoked. This is equivalent to the PLI function tf_mipname(). A typical module string would be 'Demo'.

path None String Return the module name plus blockname, i.e. the full pathname of where the $scriptsim() verilog command was invoked. This is equivalent to the PLI function tf_sname(). A typical path string would be 'Demo.main_block'.

product None String Return the product name of the verilog simulator. For PLI, this is the value returned by the PLI acc_product_version() function. If the product information is unavailable, the string '<unknown>' is returned. A typical product() string would be 'ModelSim Version 5.4d'.

time ** None Numeric Return the current simulation time. The units is determined by the time_unit method, and defaults to nanoseconds.

time_precision None Numeric Returns the simulator time precision. For example, if the simulator time precision is 1 nanosecond, this method returns the integer -9. This is the value returned from the PLI function call tf_gettimeprecision(). The time_precision can only be changed by modifying and recompiling the verilog source.

time_unit Numeric Numeric Specify the units for integer, long, or float time values. By default, values are interpreted as nanoseconds, i.e. with time_unit(-9). The only allowed values are 0, -3, -6, -9, -12, and -15. Rather than setting from an integer, you can set it from one of the following strings: 's', 'ms', 'us', 'ns', 'ps', and 'fs'. The time_unit setting is independent of the verilog time_unit as configured with the verilog timescale command. If no argument is present, the time_unit setting is unchanged. Returns the current time_unit as an integer. See the u attribute to get the value as a string.

u ** None String Return the current time_unit as one of the following strings: 's', 'ms', 'us', 'ns', 'ps', or 'fs'. This is convenient for printing time values with the units.

version None String Return the version of the simulator. For PLI, this is the value returned by the PLI acc_version() function. If the version information is unavailable, the string '<unknown>' is returned. A typical version() string would be 'Access routines Version IEEE 1364 PLI'.

wait Optional string or numeric timeout Numeric Suspend the scriptsim process until an event occurs. Events are defined using the event method. The optional timeout is a numeric, optionally with time units such as 'ns'. Some examples of valid arguments are: '25ns', 25, 25.5. The time is interpreted as a relative time, so '25ns' will pause the simulation in 25ns. The wait method returns an integer value which indicates what caused the wait to terminate. A wait value of 0 indicates a timeout. Otherwise, the integer gives the simulator argument index whose event terminated the wait.

close None None Terminate the program's connection to the simulator without error. This function is rarely needed since a ScriptSim program generally executes until the simulation ends. If you don't call this function before exiting the program, the simulation will report an error. After invoking this method, do not attempt to use the simulator object.

Simulator Argument Object

The Simulator Argument (Arg) object refers to an argument of the verilog $scriptsim() function call. There are a wide variety of Arg objects because of the wide variety of verilog argument types. Only the methods applicable to that type of argument are allowed.

Notes regarding verilog types: Verilog integers in verilog are simply vectors, and the same operations and assignments can occur as with vectors. They can contain 'x' or 'z' bits. The only difference between a verilog vector and a verilog integer is that a vector is unsigned, and an integer has a sign. A verilog integer is always at least 32 bits. Verilog time is an unsigned vector with at least 64 bits. Events always have value 0. The only meaningful operation for a verilog event is to use the event method to terminate a wait when the verilog event occurs.

Simulator Argument Methods

In the following table, methods which are usually accessed as tied variables are marked with '**'.

Name	Argument	Returns	Description
bits	None	Numeric	Returns the number of bits if the type is 'vector'. If not a 'vector', returns 0.
delay	Numeric or List	List	Set the delay for this argument. The first element should be a numeric delay. The second element is optional and can be one of the following strings specifying the delay type: 'Inertial', 'Transport', or 'PureTransport'. The default is 'Inertial'. You may abbreviate these strings and use lower case. See your verilog documentation to understand inertial, transport, and pure transport delays.
fmt **	String	String	Formats a vector argument value in a way similar to the standard printf % operator except it handles unknown bits. Supports 'b' binary and 'h' hex formats, with optional leading zeros. Supported format examples are "%h", "%0h", "%b", "%0b". If all bits are 'z' or 'x', a single 'z' or 'x' digit is returned unless a leading 0 specification is present. When formatting hex, a 'z' digit is displayed if all bits are 'z'. Otherwise an 'x' digit is displayed if any bits are 'x' or 'z'. Any characters preceding or following the format are copied to the result string, so a format such as "0x%hL" is allowed and could generate, for example, "0x23L".
fullname	None	String	Returns a string giving the name of the argument. For example, 'Demo.clk' or 'Demo.main_block.<Constant>'. This string comes from the PLI function acc_fetch_fullname().
index	None	Integer	Returns the index number of this argument. If the argument came from the verilog $scriptsim() call, it is the index number of the argument starting with 0. Otherwise it is a unique number. If an event on this argument terminates a wait, the wait command returns this index.
signed	None	Numeric	Returns 1 if the argument is a vector with a sign bit. Otherwise return 0. Only verilog integers have a sign bit.
type	None	String	Returns one of the following strings: 'string', 'float', 'vector', or 'event'. A string refers to a verilog function parameter enclosed with "". A float is a verilog real or time_time function parameter. A vector is a verilog scalar, vector, integer, or time type. An event is a verilog event.
val **	Numeric or String	Numeric or String	Set the function argument value. If the type is 'string', a string is required. (Setting strings is not yet implemented.) If the argument is type 'float', a float is required. If the argument is a vector, an integer, long, or string is accepted. A vector string must either begin with '0b' or '0x' and can contain 'x' and 'z' digits, or it can be the single character '0', '1', 'x', or 'z'. If set to a single character, all bits in the vector are set to that character. If the argument is type 'event', only an integer with value 1 is accepted (setting events not yet implemented). Setting val causes an argument value to change after a simulator wait.
writeable	None	Numeric	Returns 1 if the argument can be written. Otherwise returns 0.
x **	None	Numeric	Returns 1 if the argument is type 'vector' and contains unknown bits. Otherwise returns 0.

The following methods are of interest to PLI gurus:

Name Argument Returns Description

acc_type None String Returns any one of many acc type strings, such as: 'accConstant' 'accNet' 'accIntegerVar' 'accRealVar' 'accParameter' 'accRegister' 'accNamedEvent' but always returns 'accConstant' if the tf_type() was 'tf_nullparm' or 'tf_string'. The string is based upon the defines in acc_user.h as returned by the PLI routine acc_fetch_type(). If multiple defines have the same value (such as accReg and accRegister), the longer name is returned.

acc_fulltype None String Very similar to acc_type but uses the PLI function call 'acc_fetch_fulltype'.

tf_type None String Returns one of the following strings: 'tf_nullparam' 'tf_string' 'tf_readonly' 'tf_readwrite' 'tf_rwbitselect' 'tf_rwpartselect' 'tf_rwmemselect' 'tf_readonlyreal' 'tf_readwritereal'

Tied Variables - Revisited

The methods above marked with ** are generally used as tied variables. To access a verilog argument value, use the following:

tie $variable_name, ScriptSim::Arg, <simulator_object>, <argument_number>, <optional_format>;

Where <argument_number> is the argument number of the $scriptsim() verilog command, counting from zero. The optional format can be one of the following:

%b binary using the digits [01xz]

%0b like %b but with leading zeros

0b%b like %b but with '0b' prefix

%x hex using the digits [0-9a-fzx]

%0x like %x except with leading zeros

0x%x like %x but with '0x' prefix

x 1 if contains any 'x' or 'z' bits, otherwise 0.

To access time, use the command:

tie $time, ScriptSim::Time, $sim;

To get the time units ('ns', etc), use the command:

tie $units, ScriptSim::U, $sim;

So you can use, for example, the command:

print "The current time is $time $units\n";

which might generate something like: "The current time is 125 ns".

The Console Display

The console is used to display normal status or error messages. All print statements and any writes to stdout or stderr appear automatically in the console window. All messages in the console window are preceded by a 1 or 2 digit number which indicates which python agent generated the message. The console menu shows the association between the number and the program.

Method	Arguments	Returns	Description
argc	None	Numeric	Return the number of arguments in the verilog $scriptsim() function call. Note that python uses the terminology 'function arguments', while the verilog standard calls them 'function parameters'.
event	argument object, plus an optional string.	1	Configure an event on this argument to terminate an event. The optional string can be 'change', 'rising', 'falling', or 'cancel'. 'change' is the default and terminates the wait when this verilog object changes. 'rising' and 'falling' refer to transitions to 1 or 0 for single bit nets only. 'cancel' cancels any previous event configuration for this argument.
module	None	String	Return the module name where the $scriptsim() verilog command was invoked. This is equivalent to the PLI function tf_mipname(). A typical module string would be 'Demo'.
path	None	String	Return the module name plus blockname, i.e. the full pathname of where the $scriptsim() verilog command was invoked. This is equivalent to the PLI function tf_sname(). A typical path string would be 'Demo.main_block'.
product	None	String	Return the product name of the verilog simulator. For PLI, this is the value returned by the PLI acc_product_version() function. If the product information is unavailable, the string '<unknown>' is returned. A typical product() string would be 'ModelSim Version 5.4d'.
time **	None	Numeric	Return the current simulation time. The units is determined by the time_unit method, and defaults to nanoseconds.
time_precision	None	Numeric	Returns the simulator time precision. For example, if the simulator time precision is 1 nanosecond, this method returns the integer -9. This is the value returned from the PLI function call tf_gettimeprecision(). The time_precision can only be changed by modifying and recompiling the verilog source.
time_unit	Numeric	Numeric	Specify the units for integer, long, or float time values. By default, values are interpreted as nanoseconds, i.e. with time_unit(-9). The only allowed values are 0, -3, -6, -9, -12, and -15. Rather than setting from an integer, you can set it from one of the following strings: 's', 'ms', 'us', 'ns', 'ps', and 'fs'. The time_unit setting is independent of the verilog time_unit as configured with the verilog timescale command. If no argument is present, the time_unit setting is unchanged. Returns the current time_unit as an integer. See the u attribute to get the value as a string.
u **	None	String	Return the current time_unit as one of the following strings: 's', 'ms', 'us', 'ns', 'ps', or 'fs'. This is convenient for printing time values with the units.
version	None	String	Return the version of the simulator. For PLI, this is the value returned by the PLI acc_version() function. If the version information is unavailable, the string '<unknown>' is returned. A typical version() string would be 'Access routines Version IEEE 1364 PLI'.
wait	Optional string or numeric timeout	Numeric	Suspend the scriptsim process until an event occurs. Events are defined using the event method. The optional timeout is a numeric, optionally with time units such as 'ns'. Some examples of valid arguments are: '25ns', 25, 25.5. The time is interpreted as a relative time, so '25ns' will pause the simulation in 25ns. The wait method returns an integer value which indicates what caused the wait to terminate. A wait value of 0 indicates a timeout. Otherwise, the integer gives the simulator argument index whose event terminated the wait.
close	None	None	Terminate the program's connection to the simulator without error. This function is rarely needed since a ScriptSim program generally executes until the simulation ends. If you don't call this function before exiting the program, the simulation will report an error. After invoking this method, do not attempt to use the simulator object.

%b	binary using the digits [01xz]
%0b	like %b but with leading zeros
0b%b	like %b but with '0b' prefix
%x	hex using the digits [0-9a-fzx]
%0x	like %x except with leading zeros
0x%x	like %x but with '0x' prefix
x	1 if contains any 'x' or 'z' bits, otherwise 0.

Perl Language Reference Manual