CATC IBTracer User manual

2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel:
+1/408.727.6600 Fax: [phone]
IBTracer
Verification Script Engine
User Manual
IBTracer VSE Manual Version 1.0
For IBTracer Software Version 2.2 or Higher
1 November, 2002

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 2 of 35
Table of Contents
1. Introduction ................................................................................................................. 4
2. Verification Script Structure....................................................................................... 4
3. Interaction between IBTracer and verification script ............................................... 7
4. Running verification scripts from IBTracer............................................................... 9
4.1 RUNNING VERIFICATION SCRIPTS.............................................................................................. 10
4.2 EDITOR SETTINGS. .................................................................................................................... 12
5. Verification Script Engine Input Context members................................................ 12
5.1 TRACE EVENT-INDEPENDENT SET OF MEMBERS. ....................................................................... 13
5.2 TRACE EVENT-DEPENDENT SET OF MEMBERS. .......................................................................... 13
6. Verification Script Engine Output Context members............................................. 14
7. Verification Script Engine events ............................................................................ 14
7.1 PACKET EVENTS. ...................................................................................................................... 14
7.2 NOTIFICATION EVENTS. ............................................................................................................ 15
8. Sending functions ..................................................................................................... 15
8.1 SENDCHANNEL()...................................................................................................................... 15
8.2 SENDEVENT ().......................................................................................................................... 16
8.3 SENDLINKPKT () ...................................................................................................................... 17
8.4 SENDMAD () ........................................................................................................................... 17
9. Timer functions ......................................................................................................... 19
9.1 VSE TIME OBJECT .................................................................................................................... 19
9.2 SETTIMER().............................................................................................................................. 19
9.3 KILLTIMER() ............................................................................................................................ 19
9.4 GETTIMERTIME() ..................................................................................................................... 20
10. Time construction functions .................................................................................... 20
10.1 TIME() ...................................................................................................................................... 20
10.2 TIMEFROMSYMBOLS() ............................................................................................................. 21
11. Time calculation functions ....................................................................................... 21
11.1 ADDTIME()............................................................................................................................... 21
11.2 SUBTRACTTIME() ..................................................................................................................... 22
11.3 MULTIMEBYINT().................................................................................................................... 22
11.4 DIVTIMEBYINT() ..................................................................................................................... 23
12. Time logical functions............................................................................................... 23
12.1 ISEQUALTIME()........................................................................................................................ 23
12.2 ISLESSTIME() ........................................................................................................................... 24
12.3 ISGREATERTIME().................................................................................................................... 24
13. Time text functions ................................................................................................... 25
13.1 TIMETOTEXT()......................................................................................................................... 25
14. Output functions ....................................................................................................... 25
14.1 REPORTTEXT() ......................................................................................................................... 25
14.2 ENABLEOUTPUT() .................................................................................................................... 26
14.3 DISABLEOUTPUT() ................................................................................................................... 26
15. Common Retrieving functions ................................................................................. 26
15.1 RETRIEVEPKTPAYLOAD() ........................................................................................................ 26
15.2 ISMAD() ................................................................................................................................... 27
16. Packet Header retrieving functions ......................................................................... 27

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 3 of 35
16.1 GETLRHFIELD() ...................................................................................................................... 27
16.2 GETBTHFIELD() ...................................................................................................................... 28
16.3 GETGRHFIELD()...................................................................................................................... 28
16.4 GETDETHFIELD() ................................................................................................................... 29
16.5 GETRETHFIELD().................................................................................................................... 29
16.6 GETATOMICETHFIELD() ......................................................................................................... 30
16.7 GETATOMICACKETHFIELD() .................................................................................................. 30
16.8 GETRDETHFIELD()................................................................................................................. 31
16.9 GETRWHFIELD()..................................................................................................................... 31
16.10 GETPOSTHDRFIELD()........................................................................................................... 31
17. MAD decoded fields retrieving functions................................................................ 32
17.1 GETDECODEDMADFIELD() ..................................................................................................... 32
17.2 GETHEXMADFIELD().............................................................................................................. 33
18. Miscellaneous functions........................................................................................... 34
18.1 SCRIPTFORDISPLAYONLY() ..................................................................................................... 34
18.2 SLEEP()..................................................................................................................................... 34
19. The VSE important script files ................................................................................. 34
APPENDIX A How to Contact CATC ................................................................................................ 35

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 4 of 35
1. Introduction
This document contains a description of the CATC’s Verification Script Engine (VSE) – a new
feature in the IBTracer software that allows users to create custom tests on Infiniband(IB) traffic,
recorded on CATC’s Infiniband protocol analyzers.
The VSE conveniently allows users to ask the IBTracer application to send some of desired
“events” ( packets and some predefined notifications ) that occurred in the recorded IB trace to a
special verification script written using CATC script language. The script then evaluates the sequence
of events (timing, data or both) in accordance with user-defined conditions.
Using the VSE API, users can easily retrieve information about any field in IB packet headers,
Link packets and MADs, make very complex timing calculations between different events in recorded
trace, filter data in or out of the trace with dynamically changing filtering conditions, and display all
interesting information in the special output window.
2. Verification Script Structure.
A varification script file should have extension *.dec, and be located in the subfolder
..\Scripts\VFScripts of the main IBTracer folder. Some other files might be included in the main script
file using directive %include. (see CATC Script Language (CSL) manual for details)
The following schema can present the common structure of verification script:
#
#
# VS1.dec
#
# Verification script
#
# Brief Description:
# Verify something…
#
############################################################################################
# Module info
#
############################################################################################
# Filling of this block is necessary for proper verification script operation...
#
############################################################################################
set ModuleType = "Verification Script"; # Should be set for all verification scripts
set OutputType = "VS"; # Should be set for all verification scripts
set InputType = "VS"; # Should be set for all verification scripts

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 5 of 35
set DecoderType = "<Your VScript name>"; # Should be set for all verification scripts
set DecoderDesc = "<Your Verification Script description>"; # Optional
############################################################################################
##########
#
# include main Verification Script Engine definitions
#
%include "VSTools.inc" # Should be set for all verification scripts
######################################################################################
# Global Variables and Constants #
######################################################################################
# Define your verification script-specific global variables and constant in this section...
# (Optional)
const MY_GLOBAL_CONSTANT = 10;
set g_MyGlobalVariable = 0;
######################################################################################
######################################################################################
# OnStartScript() #
######################################################################################
# #
# It is a main intialization routine for setting up all necessary #
# script parameters before running the script. #
# #
######################################################################################
OnStartScript()
{
######################################################################################
# Specify in the body of this function initial values for global variables #
# and what kind of packets or trace events should be passed to the script. #
# ( By default, only MAD packets and Link state change events from both channels #
# will be passed to the script. #
# #
# For details – how to specify what kind of events should be passed to the script #
# please see the topic ‘sending functions’. #
# #
# OPTIONAL. #
######################################################################################
# Uncomment the line below - if you want to disable output from
# ReportText()-functions.
#
# DisableOutput();
}

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 6 of 35
######################################################################################
# ProcessData() #
######################################################################################
#
# #
######################################################################################
# It is a main script function called by the application when the next waited event #
# occured in the evaluated trace. #
# #
# !!! REQUIRED !!! – MUST BE IMPLEMENTED IN VERIFICATION SCRIPT #
######################################################################################
# #
ProcessData()
{
#
# The function below will show specified message only one time -
# no matter how many times ProcessData is called.
#
ShowStartPrompt("ShowStartPrompt\n");
# Write the body of this function depending on your needs …
return Complete();
}
######################################################################################
# OnFinishScript() #
######################################################################################
#
######################################################################################
# It is a main script function called by the application when the script completed #
# running. Specify in this function some resetting procedures for a successive run #
# of this script. #
# #
# OPTIONAL. #
######################################################################################
OnFinishScript()
{
return 0;
}
######################################################################################
######################################################################################
# Additional script functions. #
######################################################################################
# #
# Write your own script-specific functions here... #
# #
######################################################################################
MyFunction( arg )
{
if( arg == “Blah” ) return 1;

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 7 of 35
return 0;
}
3. Interaction between IBTracer and verification script
The following describes how IBTracer interacts with a verification script to test an open trace:
1. When a verification script is run, VSE looks for the function OnStartScript() and calls it if it is
found. In the OnStartScript() function, setup routines can be created that can perform tasks such
as specifying what kind of trace events should be passed to the script, and setting up initial
values of global script-specific global variables.
2. VSE then goes through the recorded trace and checks if the current packet in the trace meets
specified sending criteria – if the criteria are met, VSE calls the script’s main processing
function ProcessData() and provides input context variables to the script about the current
event. (Please refer to the topic “Input context variables” below in this document for full
description of verification script input context variables )
3. The ProcessData() function, which is present in all verification scripts, then processes whatever
event has been sent to the script and verifies that the information in the event is appropriate for
the current stage of the verification process. At the completion of each stage, the ProcessData()
function determines if VSE should continue running the script or not. If the result for any given
stage of the script is clear, the script tells VSE to complete execution of the script.
The decision to terminate the test prior to evaluating the entire trace is controlled by the
output context variable: out.Result = _VERIFICATION_PASSED or
_VERIFICATION_FAILED.
(Please refer to the topic “Output context variables” below in this document for full description
of verification script output context variables)
4. When script running is finished, VSE looks for the function OnFinishScript() and calls it if it is
found. In this function some resetting procedures can be done.
The following picture describes the interaction between the IBTracer application and the running
verification script:

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 8 of 35
OnStartScript() Starting VSE running …
V
erification Script
Call..
IBTracer Application
(Run verification script)
ProcessData() Call..(If expected event )
ProcessData() Call..(If expected event )
ProcessData() Call..(If expected event )
ProcessData()
Set out.Result =
_
VERIFICATION_PASSED o
r
_
VERIFICATION_FAILED
will com
p
lete the scri
p
t run.
Call..(If expected event )
OnFinishScript() Finishing VSE running … …
Call..
PASSED FAILED DONE
V
erification Script results
NOTE: Verification script result : <DONE> means that the script is intended solely for
extracting and displaying some information from recorded traces and that the user does not
care about the result . To specify that your script is intented only for the purposes of
displaying information, call somewhere in your script ( in OnStartScript() – for instance )
function ScriptForDisplayOnly() )

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 9 of 35
4. Running verification scripts from IBTracer
To run a verification script over a trace –run the command Report>Run verification scripts…
from the menu or push the button shown below on the main toolbar ( if it is not hidden ):
The special dialog will open inviting to choose and run one or several verification scripts:

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 10 of 35
Verification Script List.
Name for scripts are defined in
set DecoderType = "MyName";
Verification Script description.
Descriptions for scripts are defined in
set DecoderDesc= "MyDescription";
Start running selected
verification scripts
Maximize dialog and
expand output window
This option( if set ) clears up the
contents of the output window when
'Run scripts' button is pressed.
Save contents of output
window in a text file
4.1 Running verification scripts.
Push the button ‘Run scripts’ after you selected desired scripts to run. VSE will start the
selected verification scripts, show script report information in the output window and present
results of verification in the script list:

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 11 of 35
Right-click in script list to open a pop-up menu with options for performing additional operations
over selected scripts:
- Run verification script – starts running selected script.

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 12 of 35
- Edit script – allows you to edit selected scripts using whatever editor application has been
specified in ‘Editor settings’.
- New script – creates a new script file using the template specified in ‘Editor settings’.
- Editor settings – allows to specify some settings for editing scripts and creating new ones.
4.2 Editor settings.
After choosing ‘Editor settings’ the following dialog will appear:
This option (if set) allows editor
applications supporting multi-document
interface (MDI) to edit all script files
related to the selected scripts in one
application instance.
Otherwise, a new application instance
will be launched for each script file.
This option (if set) allows editor
applications to edit all included files
(extension : *.inc) along with main
verification script files (extension : *.dec )
Otherwise, only main verification script
files will be open for editing.
Launches editor application in
full screen mode.
Full path to the file to be used
as a template for a new script.
5. Verification Script Engine Input Context members
All verification scripts have input contexts –special structures whose members are set by the script
and can be used inside of the application. ( For more details about input contexts – please refer to the
CATC Script Language(CSL) Manual ). The verification script input contexts have two sets of
members:
- Trace event-independent set of members.
- Trace event -dependent set of members.

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 13 of 35
5.1 Trace event-independent set of members.
This set of members is defined and can be used for any event passed to script:
in.Time - time of the event( type : list, having format : 2 sec 125 ns -> [2 , 125])
in.Channel - channel where the event occured. ( can be _CHANNEL_LEFT or _CHANNEL_RIGHT
indicating on which channel event occurred )
in.TraceEvent - type of trace events( application predefined constants are used. See list of possible
events below )
5.2 Trace event-dependent set of members.
This set of members is defined and can be used only for a specific events or after calling some
functions filling out some of variables:
5.2.1 All packet-specific set of members.
( valid for any packets - but only after RetrievePktPayload()-function was called – see description of
this function for details )
in.Payload - bit source of the packet payload ( you can extract any necessary
information using GetNBits(), NextNBits() or PeekNBits() functions – please refer to CSL Manual for
details about these functions )
in.PayloadLength - the length( in bytes of the retrieved packet payload )
5.2.2 Link packet-specific set of members.
(valid for link packets only, undefined for other events )
in.Opcode
in.VL
in.FCCL
in.FCTBS
in.LPCRC
5.2.3 Link state change notification-specific set of members.
(valid for Link State Change notifications only, undefined for other events )
in.LinkStatePrev - previous link state(Opcode)

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 14 of 35
in.LinkStateCurr - current link state(Opcode)
6. Verification Script Engine Output Context members
All verification scripts have output contexts –special structures whose members are set by the
script and can be used inside of the application ( For more details about output contexts – please refer
to the CATC Script Language(CSL) Manual ). The verification script output contexts have only one
member:
out.Result - the result of the whole verification program defined in the verification script.
This member is supposed to have 3 values:
_VERIFICATION_PROGRESS,( is set by default when script starts running )
_VERIFICATION_PASSED,
_VERIFICATION_FAILED
The last two values should be set if you decide that recorded trace does ( or not ) satisfy the
imposed verification conditions. In both cases the verification script will stop running.
If you don't specify any of those values - the result of script execution will be set as
VERIFICATION_FAILED at exit.
7. Verification Script Engine events
VSE defines a large group of trace “events” – packets or special notifications – that can be
passed to a verification script for evaluation or retrieving and displaying some contained information.
The information about the type of event can be seen in in.TraceEvent. Please refer to the topic
“Sending functions” in this manual for details about how to send events to scripts.
7.1 Packet events.
The table below shows current list of packet events and value of in.TraceEvent:
Packet in.TraceEvent
TS1 _PKT_TS1
TS2 _PKT_TS2
Link Packet _PKT_LINK
MAD packets _PKT_MAD
Reliable Connection packets _PKT_RC
Reliable Datagram packets _PKT_RD
Unreliable Connection packets _PKT_UC
Unreliable Datagram packets _PKT_UD

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 15 of 35
Skips _PKT_SKIPS
7.2 Notification events.
VSE defines a group of notification events that can be passed to a verification script for
evaluation or for retrieving and displaying some contained information. The information about the type
of event can be seen in in.TraceEvent. Please refer to the topic “Sending functions” in this manual for
details about how to send events in scripts. The notification events are not the same as packets – they
basically indicate that something changed in current stream of evaluated data.
The table below shows current list of packet events and value of in.TraceEvent:
Notification event in.TraceEvent
Physical link woke up from silence _EVNT_CONNECT
Physical link came to silence (no physical signal) _EVNT_DISCONNECT
Changing of Opcode in series of link packets _EVNT_LINKSTATE_CHANGE
8. Sending functions
This topic contains information about the special group of VSE functions designed to specify
what kind of event verification script expects to receive.
8.1 SendChannel()
This function specifies that events occurred only on specified channel should be sent to script.
Format : SendChannel( channel )
Parameters: channel – This parameter can be one of following values:
_CHANNEL_LEFT – send events only from left channel
_CHANNEL_RIGHT – send events only from right channel
_CHANNEL_BOTH – send events from both channels
Example:
SendChannel( _CHANNEL_LEFT ); # - send events from left channel

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 16 of 35
8.2 SendEvent ()
This function specifies what kind of events should be sent to script.
Format : SendEvent( event )
Parameters: event – This parameter can be combination of the following values:
event value Description
_PKT_TS1 TS1
_PKT_TS2 TS2
_PKT_LINK Link Packet
_PKT_MAD MAD packets
_PKT_RC Reliable Connection packets
_PKT_RD Reliable Datagram packets
_PKT_UC Unreliable Connection packets
_PKT_UD Unreliable Datagram packets
_PKT_SKIPS Skips
_EVNT_CONNECT Physical link woke up from silence
_EVNT_DISCONNECT Physical link came to silence (no physical signal)
_EVNT_LINKSTATE_CHANGE Changing of Opcode in series of link packets
Some special values can be used covering large groups of events:
_ALL_PACKETS All possible packets
_ALL_EVENTS All possible notification events
_ALL All possible packets and notification events
Example:
SendEvent( _PKT_LINK ); # - send link packets
SendEvent( _PKT_LINK | _PKT_MAD ); # - send link packets and MADs
SendEvent(_ALL_PACKETS | _EVNT_DISCONNECT );
# - send all possible packets and Disconnect notification

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 17 of 35
8.3 SendLinkPkt ()
This function specifies more precise tuning for sending link packets.
Format : SendLinkPkt( opcode = _ALL, vl = _ALL )
Parameters:
opcode – This parameter specifies that only link packets with this Opcode will be sent
( _ALL – means that link packets with all opcodes will be sent )
vl – This parameter specifies that only link packets with this VL will be sent
( _ALL – means that link packets with for all VLs will be sent )
Example:
SendLinkPkt(); # - send all link packets – equal to SendEvent( _PKT_LINK );
SendLinkPkt( 0x1 ); # - send all link packets with Opcode = 0x1
SendLinkPkt( 0x1 , 0x7 ); # - send all link packets with Opcode = 0x1 and VL = 0x7
SendLinkPkt( _ALL, 0x7 ); # - send all link packets with VL = 0x7
8.4 SendMAD ()
This function specifies more precise tuning for MAD packets.
Format : SendMAD( mgmtclass = _ALL,
attrId = _ALL,
method = _ALL,
field_name = “” , # means no care about field_name
field_value =0)
Parameters:
mgmtclass – This parameter specifies that only MADs with this management class will be sent
( _ALL – means that MADs with all management classes will be sent )
attrId – This parameter specifies that only MADs having AttributeId equal to attrId will be
sent
( _ALL – means that MADs with any AttributeIds will be sent )
method – This parameter specifies that only MADs having Method equal to method will be
sent
( _ALL – means that MADs with any Method will be sent )
field_name – This parameter specifies that only MADs having a field with field_name (how it is

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 18 of 35
shown in CATC trace) and value equal to field_value will be sent ( This field
makes sense only if one of the previous parameters are not equal to _ALL )
field_value – This parameter specifies that only MADs having a field with field_name (how it is
shown in CATC trace) and value equal to field_value will be sent ( This field
makes sense only if one of the previous parameters are not equal to _ALL )
NOTE: For fields having size more than 32 bits use raw binary values
( like : ‘0011223344556677FF’) For more information about raw binary
values please refer to CSL Manual.
Example:
SendMAD() # - send all MAD packets – equal to
# SendEvent( _PKT_MAD );
SendMAD (SMP_LIDROUTED); # - send SMP LID routed MADs
SendMAD ( _ALL , PORT_INFO); # - send PortInfo for all classes
SendMAD( SMP_DIRROUTED, PORT_INFO, GET_RESP, "GIDPrefix",
'FE80000000000000' );
#
# - send SMP Directed routed GetResp() MADs with PortInfo: GIDPrefix =
FE80000000000000'
SendMAD (SMP_LIDROUTED, PORT_INFO, GET_RESP, “PortState”, PS_ARMED);
#
# - send SMP LID routed GetResp() MADs with PortInfo:PortState = PS_ARMED
NOTE : SMP_LIDROUTED, PORT_INFO,…areconstantdefinedinfileVS_constants.inc
in ..\Scripts\VFScripts subfolder of main IBTracer folder.

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 19 of 35
9. Timer functions
This group of functions covers VSE capability to work with timers -an internal routines that
repeatedly measures a timing intervals between different events.
9.1 VSE time object
A VSE time object – is a special object that presents time intervals in verification scripts.
From point of view of CSL - the verification script time object is a “list”-object of two elements :
( Please see CSL Manual for more details about CSL types )
[seconds,nanoseconds]
NOTE: The best way to construct VSE time object is to use Time() function (see
below ).
9.2 SetTimer()
Starts timing calculation from the event where this function was called.
Format : SendTimer( timer_id =0)
Parameters:
timer_id – a unique timer identifier.
Example:
SetTimer(); # - start timing for timer with id = 0;
SetTimer(23); # - start timing for timer with id = 23;
Remark :
If this function is called second time for the same timer id – it resets timer and starts timing
calculation again from the point where it was called.
9.3 KillTimer()
Stops timing calculation for a specific timer and frees related resources.
Format : KillTimer( timer_id =0)
Parameters:

Computer Access Technology Corporation IBTracer Verification Script Engine Manual, version 1.0
Page 20 of 35
timer_id – a unique timer identifier.
Example:
KillTimer(); # - stop timing for timer with id = 0;
KillTimer(23); # - stop timing for timer with id = 23;
9.4 GetTimerTime()
Retrieve timing interval from the specific timer
Format : GetTimerTime ( timer_id =0)
Parameters:
timer_id – a unique timer identifier.
Return values:
Returns VSE time object from timer with id = timer_id.
Example:
GetTimerTime (); # - Retrieve timing interval for timer with id = 0;
GetTimerTime (23); # - Retrieve timing interval for timer with id = 23;
Remark :
This function, when called, doesn’t reset timer.
10. Time construction functions
This group of functions is used to construct VSE time objects.
10.1 Time()
Constructs verification script time object.
Format : Time(nanoseconds)
Time(seconds, nanoseconds)
Return values:
First function returns [0, nanoseconds], second one returns [seconds, nanoseconds]