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: