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


ScriptSim Python Language Core
Reference Manual

The same functionality is available in perl and python, since the ScriptSim core logic is all written in C with a very small shell to provide the perl and python interfaces, but the perl documentation is often out of date because all new functions are first documented and tested with python (my personal preference). But the perl documentation is available here.

Introduction

This document describes the core functionality of the python interface. Objects in python represent the simulation, the display, and objects in the simulation. In addition to these core functions, there is a library available which provides higher level operations. This library is written in python and the source code is available to modify and enhance if desired.

Introduction to object oriented Python

Note to those of you new to object oriented programming. Don't panic. You don't need to write object oriented python. All you have to do is use the objects ScriptSim provides, which, as you can see in the tutorial, is easy to do. Just think of it this way: In C, you might create a structure t_struct defining something too complicated to represent in a simple integer, such as a simulator time value. You instantiate this structure twice, calling it t1 and t2. Then you might write a function which prints its value to stdout and call that function print_t which takes an argument of type t_struct. So in python terminology, t_struct is an object class, t1 and t2 are objects of type t_struct, and print_t is a method for object class t_struct. Members of the structure t_struct are called attributes in python.

With ScriptSim, an attempt has been made to seamlessly integrate simulation related objects into python. This allows ScriptSim simulation objects to be compared, printed, formatted, and manipulated like normal python objects. If you find a weakness in the implementation, please let me know and I will try to fix it.

ScriptSim Module Functions

The python module for scriptsim is automatically imported for use. The scriptsim module normally serves no other purpose other than to return the 'simulator' object, which is an interface to the verilog simulator, and the 'tk_display' object, which is an interface to the Tk display. All further operations are done to the 'simulator' object and the 'display' object.

The scriptsim module has the following functions:
 
Function Arguments Returns Description
simulator None Simulator
Object		 Return the Simulator object whose methods allow reference to the verilog simulator.
display None Display
Object		 Return the Display object whose methods allow reference to the Python/Tk display server.

Examples:

sim = scriptsim.Simulator()
display = scriptsim.Display()

Simulator Object

The simulator object is the basic object for all interaction with the simulation. It is returned by the scriptsim.Simulator() function. There is only one simulator object and repeated calls to scriptsim.Simulator() always return the same object.

Simulator Object Methods

 
Method Arguments Returns Description
find list of items to search for, and what scope to search in. list of items found Search the verilog design or a specific scope of the verilog design. Return the items found.
vvo String VVO
object		 Return a new VVO object for the specified verilog object. The string argument must be a full name of a verilog object, as returned by the find command.
resume_and_
wait_for_event		 Optional
Integer
Long
Float
String or
Sim_Time		 Integer Suspend the scriptsim process until an event occurs. Events are defined using the setup_event method of the VVO object. The optional timeout can be a either an object of type Sim_Time, or an object that can be converted to an object of type Sim_Time. Some examples of valid arguments are: '25ns', 25, 25.5, 25L. The time is interpreted as a relative time, so '25ns' will pause the simulation in 25ns. The resume_and_wait_for_event method returns an integer value which indicates what caused the wait to terminate. A return value of 0 indicates a timeout. A return value of scriptsim.STATUS_CHANGE indicates the simulator status has changed. This value can only be returned if 'monitor_status' has been set to '1'. A return value of scriptsim.TERMINATED indicates the simulator has terminated (only possible if terminate_with_simulator is not set). If a verilog task call occurs, the returned value is scriptsim.TASK_CALL. Otherwise, the integer gives the simulator argv argument index whose event terminated the wait.
resume Optional
Integer
Long
Float
String or
Sim_Time		 0 Same as 'resume_and_wait_for_event' except used in non-blocking I/O applications. The resume command does not block waiting for data from the simulation. It always returns 0. The simulation is resumed. The resume command is useful if you have other I/O to perform, or have a Tk display to manage. When the simulator sends data, call the 'get_event' method to get the results. You may use the Python 'select' module, or the tkinter.createfilehandler() to detect when the simulator sends data.
get_event None Integer When you have a non-blocking I/O application, use the 'resume' and 'get_event' methods instead of the 'resume_and_wait_for_event' method. The 'get_event' method returns the event cause as documented in 'resume_and_wait_for_event' above.
time Optional
Integer
Long
Float or
String		 Sim_Time Return a new object of type Sim_Time. It is initialized to the current simulator time. You may also provide an argument to initialize the Sim_Time object to some other value. String values can include units, for example: '10ns'. See information about the Sim_Time object for further details.
close None None Terminate the python 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 python program, the simulation will report an error. After invoking this method, do not attempt to use the simulator object.

Simulator Object Attributes

Name R/W Type Description
argc Read
Only		 Integer 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'.
argv Read
Only		 List Return a copy of the list of VVO objects which are the $scriptsim() verilog function arguments. The first list item is always the argument holding the python program filename. The list length is argc. See information about the VVO object for further information.
call_dict
or cd		 Read
Only		 Dictionary If verilog calls this process, reading this attribute returns the verilog function parameters (VVOs) in a dictionary. Once read, this attribute is set to 'None' until the next verilog call. The parameters can be referenced by call_dict[n] or cd[n] where n is the parameter number, starting with 0. The number of arguments is call_dict["argc"]. See information about the VVO object for further information.
fileno Read
Only		 Integer Return the integer file number for the simulation pipe. This is only useful if you are using non-blocking I/O and need the file number for 'select' or 'tkinter.createfilehandler' functions.
id Read
Only		 Integer Each $scriptsim call which has a perl/python filename as the first parameter creates a process with a unique id. This attribute is the id number. It should be used on $scriptsim calls which refer to this process.
module Read
Only		 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'.
monitor_status Read
Write		 Integer When 1, simulator status changes terminate a 'resume_and_wait_for_event' method, returning scriptsim.STATUS_CHANGE as the wait termination reason. Checking the attribute 'status' returns the simulator status. This allows, for example, being notified when the simulation goes into interactive mode, or if a restart or save occurs, or when the simulation exits. By default, this attribute is 0. When the resume_and_wait_for_event() method terminates due to a status change, no interaction with the simulator is possible because the simulator may be in interactive mode or may have exited. Being notified when the simulator goes into interactive mode or exits is useful for updating displays or saving result logs.
path Read
Only		 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 Read
Only		 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'.
status Read
Only		 String This attribute is only valid if the attribute monitor_status is set to 1 and the resume_and_wait_for_event() command returned scriptsim.STATUS_CHANGE indicating a simulator status change. If so, this attribute holds the last status change of the simulator. The possible status strings include 'interactive' which indicates that a verilog $stop command occurred, and 'finish' when the simulation terminates.
terminate_
with_simulator		 Read
Write		 Integer By default, this attribute has a value of '1'. If '1', when the simulator terminates, this process will also automatically terminate. If '0', this process will not automatically terminate. When the simulation terminates, many methods such as 'resume_and_wait_for_event', 'resume', 'get_event', and 'setup_event' are not legal.
time_precision Read Only Integer 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 Read/
Write		 Integer
(String)		 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 examined, it returns the current time_unit as an integer. See the u attribute to get the value as a string.
top Read
Only		 String Returns the name of the top level module. This would be a string like 'Test' or 'Demo'.
u Read
Only		 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 Read
Only		 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'.

Simulator Standard Python Operations

repr(<simulator_object>) and str(<simulator_object>) return a string in the form '<$scriptsim() call in <path>>' where <path> is the path attribute.  For example:  '<$scriptsim() call in Demo.main_block>'.
There is only 1 simulator object. The simulator object is immutable.
 

Simulator Object Examples

The following code shows basic examples using the methods and attributes:

sim = scriptsim.Simulator()

print sim

print sim.version, sim.product, sim.module, sim.path
print 'sim time_precision is',sim.time_precision
print 'sim time_units is',sim.time_unit,'or',sim.u

sim.time_unit('ns')

wait(100) # equivalent to wait('100ns')

t1 = sim.time() # t1 is '100ns'
t2 = sim.time(150) # t2 is '150ns'
t3 = sim.time('1us')

if sim.argc < 2:
    print "Error, no clk argument"
    sys.exit() # exit with error

clk = sim.argv[1]

# insert your useful work here

sim.close()
 
 
 

VVO - Verilog Valued Object

VVO refers to any object in the verilog simulation which has a value. Verilog nets, registers, variables, constants and parameters have values. Verilog modules, functions, cells etc do not have a value. The arguments of the verilog $scriptsim() function call are VVOs, but you can create additional VVOs for any verilog valued object anywhere in the verilog design.  A list of $scriptsim() function parameter VVO objects is held by the Simulator attribute argv. There are a wide variety of VVO objects. Only the methods applicable to that type of object 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.

VVO Methods

Name Argument Returns Description
fmt String String Formats a vector argument value in a way similar to the standard Python % 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".
release None None Cancel any force or assign. See the 'delay' attribute for further information.
setup_event Integer None The argument can be one of scriptsim.RISING, scriptsim.FALLING, scriptsim.CHANGE, or scriptsim.CANCEL. CHANGE sets up an event on any change of the argument. CANCEL deletes any previous setup_event configuration. RISING and FALLING are only allowed on 1 bit (scalar) arguments. RISING refers to a transition from any state to 1. FALLING refers to a transition from any state to 0.

VVO Attributes

General attributes
 
Name R/W Type Description
bits Read
Only		 Integer Returns the number of bits if the type is 'vector'. If not a 'vector', returns 0.
delay Read
Write		 Float or Tuple Configure the delay when writing this argument. Also forcing and assignment can be configured. This gives $scriptsim the full range of verilog assignment capabilities. The argument (or first element of the tuple) must be able to be converted to Sim_Time, i.e. it is numeric or a string which specifies the delay (such as '1ns'). If a tuple, the second argument is one of the following strings, 'NoDelay', 'Inertial', 'Transport', 'PureTransport', 'Force', or 'Assign'. You may abbreviate these strings and use lower case. See your verilog documentation to understand inertial, transport, and pure transport delays. The 'Force' is like the verilog 'force' command, and 'Assign' is like the verilog procedural 'assign' command'. Use the method 'release()' to cancel a 'Force' or 'Assign'. The default is 'NoDelay' at the time of the $scriptsim call for registers, integers, real, and strings (like a verilog blocking assignment). If the delay is non-zero, or the assignment occurs after the $scriptsim call, the default is 'Inertial' for registers, integers, reals, and strings (like a non-blocking assignment). For nets, the default is 'Force'. Use 'None' as the first tuple element if you want no changes to the delay. Reading this attribute returns a tuple whose first element is an float (delay value) and the second element is the delay type string. Examples:
reset.delay = "1ns"
reset.delay = (None,"Deassign") # cease driving the 'reset' net
fullname Read
Only		 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 Read
Only		 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 Read
Only		 Integer Returns 1 if the argument is a vector with a sign bit. Otherwise return 0. Only verilog integers have a sign bit.
no_dup_writes Read
Write		 Integer By default has a value of 0. If set to 1, repeating a write with the same value as the last write will be ignored. This can result in performance improvement, but is only safe if this process is the ONLY driver of the verilog signal.
type Read
Only		 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.
v Write Integer
Long
Float 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 Read
Only		 Integer Returns 1 if the argument can be written. Otherwise returns 0.
x Read
Only		 Integer Returns 1 if the argument is type 'vector' and contains unknown bits. Otherwise returns 0.
neg Read
Write		 Integer If set to 1, negate all bits on read and write. This allows negative-true vectors in the simulation to be manipulated in ScriptSim as if they were positive true. Can be set to 0 or 1.

The following attributes allow access to the value of the argument in various forms:
 
Name R/W Type Description
b Read
Only		 String Returns a string identical to the method fmt("%b").
b0 Read
Only		 String Returns a string identical to the method fmt("%0b").
bin Read
Only		 String Returns a string identical to the method fmt("0b%b").
h Read
Only		 String Returns a string identical to the method fmt("%h").
h0 Read
Only		 String Returns a string identical to the method fmt("%0h").
hex Read
Only		 String Returns a string identical to the method fmt("0x%h").
n Read
Only		 Integer
Long or
Float		 Return the current value of the argument as a numeric type. Fails if type is 'string'. A float is returned if the type is 'float'. Otherwise an integer is returned if the number is small, otherwise a long is returned. Fails if a vector argument has unknown bits.
nx Read
Only		 Integer
Long or
Float		 Same as 'n' except unknown bits (x and z) are interpreted as 0. No error occurs for unknown bits.
str Read
Only		 String Returns the current value of the parameter as a string. If the type is 'string', the string is returned. If the type is float, a "%g" representation is returned. If the type is vector, a binary representation is returned from the method fmt("0b%b"). If the type is event, '0b0' is returned.

The following attributes are of interest to PLI gurus:
 
Name R/W Type Description
acc_type Read
Only		 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 Read
Only		 String Very similar to acc_type but uses the PLI function call 'acc_fetch_fulltype'.
tf_type Read
Only		 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'

Standard Python Operations

repr(<VVO>) or `<VVO>`: Return a string of the form '<argument n of $scriptsim() call in <path>>'.  For example, it might return the string '<argument 1 of $scriptsim() call in Demo.main_block>'.
str(<VVO>): Returns a string identical to the attribute str.
print <VVO>: This is equivalent to print str(VVO).

Sim_time Object

General Description

The sim_time object holds a value representing simulator time. Internally it is stored as a 64-bit unsigned number in units matching the simulator time_precision. It is created by the simulator method time(). When it is created, it can be initialized to any desired value, or by default it is initialized to the current simulation time.

By default, times are in nanoseconds. Using the simulator method 'time_unit', you can set the time unit to other values, such as microseconds or picoseconds.

The simulator runs with a time precision which typically defaults to 'ns' resolution. If you create a time object and attempt to set it to a value less than this precision, it is rounded up to the next higher integer time_precision value. For example, the command 'sim.wait('1ps')' would be interpreted as 'sim.wait('1ns')' if the simulator timescale was 'ns' (-9).

When setting a time object based upon a string, you may include units, such as 'ns' or 'ps'. However, when setting from an integer, long integer, or string without a specified time unit, the current value of time_unit is used. For example, if time_unit has been set to -9, which indicates 'ns', setting a time object to 10 would set it to 10ns. The set methods allow you change a time object to a different time An integer, long integer, float, or string may be used.

Member Functions

None.

Member Attributes

Name Read/Write Type Description
u Read String Returns the units string ('ns', 'ms', etc). This is a read-only attribute. You can change it only by changing the simulator object attribute time_unit. This attribute is a convenience for the python programmer, but is nothing other than the u attribute of the simulator object.

Standard Python Operations

Sim_time objects support some standard python operations: Given a sim_time object called t, the following operations are possible:
str(t): Return a string using the current time_unit plus a units string. For example, it could return '100ns'. No fractional part is present.
print t: Equivalent to print str(t)
repr(t): Return a string similar to str(t) except that the time_units is ignored and instead the time_precision of the simulator is used. This guarantees that no significant digits are ignored.
`t`: Equivalent to repr(t)
int(t): Return an integer showing the time value using the current time_unit.
long(t): Return a long integer showing the time value using the current time_unit.
float(t): Return a float showing the time value using the current time_unit. If the time_unit is larger than the time_precision, a fractional part can be present.

Sim_time objects can be compared to integers, longs, and floats. So for example:
if (t > 100):
would be legal.

Sim_time objects can be formatted with any format appropriate for python integers, floats, or strings. So, for example, you can do the following:
"%d%s %6.3g%s %s" % (t,t.u,t,t.u,t)
could yield (if time_precision was = -10, time_unit was -9, time was 23.5)
23ns 23.500ns 23.5ns

Display Object

You get the display object with the python command scriptsim.Display(). This display is the Tk display of the display server. The display server is a python process which creates a display usable by all python agents. One python agent is created for every $vepthon() command in the verilog code, but only one display server is present.
If no programs use the display object, no Tk windows are created.

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 agent generated the message. The console menu shows the association between the number and the program. The user may specify the foreground and background colors, and the font, in order to make messages stand out, for example: error and warning messages. When the simulation ends, the contents of the console display are automatically written to the file console.cl.

User Displays

The user can create a specialized display such as graphs or complete multi-windowed applications. The user has complete freedom here, but the display object has a feature to make it easier by allowing user code to run as part of the ScriptSim display server. The user creates a python/tk module which describes the interface. This module is sourced into the display server.

user_display_object = display.new(module_name, class_name, args_to_init, callback_function)
user_display_object.write(tuple)  # the tuple is provided to the user display code.

Examples of how this is done are available.

Display Methods

Method Arguments Returns Description
cprint any
number
of any 
type		 None cprint performs a function similar to the print command except it guarantees that text appearing in the console display from different processes is strictly ordered by time. Due to the asynchronous nature of the process scheduling, it is possible that print messages from different processes may not appear strictly in time ordered sequence. However, messages from the same process always appear in time ordered sequence. The cprint command informs the console display how this message should be placed in relation to other text generated from other cprint commands. The cprint command accepts any number of arguments, and each argument is converted to a string using python's str() function. Unlike the print statement, arguments are not automatically separated by 1 space, nor is a newline automatically appended. Note that the cprint command buffers data (without displaying) until a newline is printed. Examples:
cprint('\n My Title\n')
cprint('The value of list l is ',l,' and of dictionary d is ',d,'\n')
cprint('%d %s\n' % (my_int, my_string))
new module, class, callback function new display object Create a new user-defined display. The specified module is imported and an object of the specified class is created. This display can send and receive data from the agent. The callback function is called when the display sends data to the agent. The created object has only a 'write' method which takes a string argument. The callback routine should accept a string. Generally 'cPickle' (with cStringIO) is used to efficiently transfer any type of python objects between the the agent and the display. See the Python 'cPickle' and 'cStringIO' module documentation for details.

 
 

Copyright 2000-2002 NelSim Software Inc. All Rights Reserved.