How it Works
Teledyne
Loading...
SierraFC
User Manual
64 pgs3.57 Mb0
User Manual
71 pgs485.58 Kb0
Table of contents
Loading...

Teledyne SierraFC User Manual

Verification Scr ip t Engine
for
SierraFC Protocol Suite
Reference Manual
Manual Version 1.4
November 2013
Verification Script Engine Reference Manual
ii
Teledyne LeCroy Protocol Solutions Group
Trademarks and Servicemarks
Teledyne LeCroy, CATC Trace, and SierraFC Protocol Suite are trademarks of Teledyne LeCroy. Microsoft and Windows are registered trademarks of Microsoft Corporation. Intel and Pentium are registered trademarks of Intel Corporation. All other trademarks and registered trademarks are property of their respective owners. THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE
SUBJECT TO CHANGE WITHOUT NOTICE. ALL INFORMATION, EXAMPLES AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE REPRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS ARE FULLY RESPONSIBLE FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN INFORMATION THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT Teledyne LeCroy FOR A COPY.
Teledyne LeCroy © 2012; All rights reserved. This document may be printed and reproduced without additional permission, but all copies should
contain this copyright notice. WEEE Program
Teledyne LeCroy 3385 Scott Blvd. Santa Clara, CA 95054 TEL: 800-909-7112 (USA and Canada) TEL: 408-653-1260 (worldwide)
Verification Script Engine Reference Manual
iii
Table of Contents
1 INTRODUCTION .......................................................................................................... 1
2 VERIFICATION SCRIPT STRUCTURE ....................................................................... 2
3 INTERACTION BETWEEN SIERRAFC PROTOCOL SUITE AND VERIFICATION
SCRIPT ........................................................................................................................... 5
4 RUNNING VERIFICATION SCRIPTS FROM SIERRAFC PROTOCOL SUITE .......... 7
4.1 RUNNING VERIFICATION SCRIPTS .......................................................................... 9
4.2 VSE GUI SETTINGS. .......................................................................................... 11
5 VERIFICATION SCRIPT ENGINE INPUT CONTEXT MEMBERS ............................ 11
5.1 TRACE EVENT-INDEPENDENT SET OF MEMBERS .................................................... 12
5.2 TRACE EVENT-DEPENDENT SET OF MEMBERS ....................................................... 13
6 VERIFICATION SCRIPT ENGINE OUTPUT CONTEXT MEMBERS ........................ 15
7 VERIFICATION SCRIPT ENGINE EVENTS .............................................................. 15
8 FRAME LEVEL EVENTS ........................................................................................... 16
9 SEQUENCE LEVEL EVENTS ................................................................................... 16
10 SENDING FUNCTIONS ........................................................................................... 17
10.1 SENDLEVEL() .................................................................................................... 17
10.2 S
10.3 D
ENDLEVELONLY() ............................................................................................ 17
ONTSENDLEVEL() ........................................................................................... 18
10.4 SENDCHANNEL() ............................................................................................... 18
10.5 SENDCHANNELONLY() ....................................................................................... 19
10.6 DONTSENDCHANNEL () ...................................................................................... 19
10.7 S
10.8 S
ENDALLCHANNELS() ........................................................................................ 20
ENDTRACEEVENT () ........................................................................................ 20
10.9 DONTSENDTRACEEVENT() ................................................................................. 21
10.10 S
10.11 S
ENDTRACEEVENTONLY() ............................................................................. 22
ENDALLTRACEEVENTS() .............................................................................. 22
10.12 SENDPRIMITIVE() ........................................................................................... 23
10.13 SENDFCPSEQ () ........................................................................................... 23
10.14 SENDFCPCMNDSEQ () .................................................................................. 25
10.15 0SENDFCPRSPSEQ () ................................................................................... 26
11 TIMER FUNCTIONS ................................................................................................ 27
11.1 VSE TIME OBJECT ............................................................................................. 27
11.2 SETTIMER() ...................................................................................................... 27
11.3 KILLTIMER() ...................................................................................................... 28
11.4 GETTIMERTIME() ............................................................................................... 28
12 TIME CONSTRUCTION FUNCTIONS ..................................................................... 29
12.1 TIME() .............................................................................................................. 29
Verification Script Engine Reference Manual
iv
13 TIME CALCULATION FUNCTIONS ........................................................................ 30
13.1 ADDTIME() ........................................................................................................ 30
13.2 SUBTRACTTIME() .............................................................................................. 30
13.3 MULTIMEBYINT() ............................................................................................... 31
13.4 DIVTIMEBYINT() ................................................................................................ 31
14 TIME LOGICAL FUNCTIONS .................................................................................. 32
14.1 ISEQUALTIME() ................................................................................................. 32
14.2 ISLESSTIME() .................................................................................................... 32
14.3 ISGREATERTIME() ............................................................................................. 33
14.4 ISTIMEININTERVAL() .......................................................................................... 33
15 TIME TEXT FUNCTIONS ......................................................................................... 34
15.1 TIMETOTEXT() .................................................................................................. 34
16 OUTPUT FUNCTIONS ............................................................................................. 35
16.1 REPORTTEXT() ................................................................................................. 35
16.2 ENABLEOUTPUT() .............................................................................................. 35
16.3 D
ISABLEOUTPUT() ............................................................................................. 36
17 COMMON RETRIEVING FUNCTIONS .................................................................... 37
17.1 G
ETTRAPAYLOADLIMIT () ................................................................................... 37
17.2 SETTRAPAYLOADLIMIT () ................................................................................... 37
17.3 ISFCP() ............................................................................................................ 37
18 FC DATA FRAME RETRIEVING FUNCTIONS ....................................................... 38
18.1 GETNETHFIELD() .............................................................................................. 38
19 SCRIPT DECODED FIELDS RETRIEV ING FUNCTIONS ....................................... 39
19.1 GETDECODEDSCRIPTFIELD() ............................................................................. 39
19.2 GETHEXSCRIPTFIELD() ..................................................................................... 40
20 INFORMATION FUNCTIONS .................................................................................. 41
20.1 GETTRACENAME() ............................................................................................ 41
20.2 GETSCRIPTNAME() ........................................................................................... 41
20.3 GETAPPLICATIONFOLDER() ................................................................................ 41
20.4 GETCURRENTTIME() ......................................................................................... 42
20.5 GETEVENTSEGNUMBER() .................................................................................. 42
21 NAVIGATION FUNCTIONS ..................................................................................... 43
21.1 GOTOEVENT () .................................................................................................. 43
21.2 SETMARKER() ................................................................................................... 44
\
Verification Script Engine Reference Manual
v
22 FILE FUNCTIONS .................................................................................................... 45
22.1 OPENFILE() ...................................................................................................... 45
22.2 CLOSEFILE() ..................................................................................................... 46
22.3 WRITESTRING() ................................................................................................ 46
22.4 SHOWINBROWSER() .......................................................................................... 47
23 COM/AUTOMATION COMMUNIC ATION FUNCTIONS .......................................... 48
23.1 NOTIFYCLIENT() ................................................................................................ 48
24 USER INPUT FUNCTIONS ...................................................................................... 49
24.1 MSGBOX() ........................................................................................................ 49
24.2 INPUTBOX() ...................................................................................................... 51
24.3 GETUSERDLGLIMIT() ......................................................................................... 53
24.4 SETUSERDLGLIMIT() ......................................................................................... 53
25 STRING MANIPULATION/FORMATING FUNCTI ONS ........................................... 54
25.1 FORMATEX() ..................................................................................................... 54
26 MISCELLANEOUS FUNCTIONS ............................................................................ 56
26.1 S
26.2 S
CRIPTFORDISPLAYONLY() ............................................................................... 56
LEEP() ............................................................................................................ 56
26.3 CONVERTTOHTML() ......................................................................................... 56
26.4 PAUSE() ........................................................................................................... 57
27 THE VSE IMPORTANT SCRIPT FILES .................................................................. 58
Verification Script Engine Reference Manual
1

1 Introduction

This document contains a description of the CATC’s Verification Script Engine (VSE), a new utility in the SierraFC Protocol Suite software that allows users to perform custom analyses of Fibre Channel (FC) traffic, recorded using the new generation of CATC’s Fibre Channel protocol analyzers.
VSE allows users to ask the SierraFC Protocol Suite application to send some desired “events” (currently defined as frames and sequences ) from an FC trace to a verification script written using CATC script language. This script then evaluates the sequence of events (timing, data or both) in accordance with user-defined conditions and performs post-processing tasks such as exporting key information to external text-based files or sending special Automation/COM notifications to user client applications.
VSE is designed to allow users to easily retrieve information about any field in FC frame headers or FCP SSCI sequences, and to make complex timing calculations between different events in recorded trace. It also allows the filtering-in or filtering-out of data with dynamically changing filtering conditions, the porting of information to a special output window, the saving of data to text files, and the sending of data to COM clients connected to SierraFC Protocol Suite application.
Verification Script Engine Reference Manual
2

2 Verification Script Structure

Writing verification scripts is easy so long as you follow a few rules and have some understanding of how SierraFC Protocol Suite application interacts with running scripts.
The main script file that contains the text of the varification script should have extension .vse, and be located in the subfolder ..\Scripts\VFScripts of the main SierraFC Protocol Suite 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.vse # # Verification script # # Brief Description: # Verify something… #
############################################################################################ # Module info # ############################################################################################ # Filling of this block is necessary for proper verification script operation... # ############################################################################################
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;
######################################################################################
Verification Script Engine Reference Manual
3
###################################################################################### # 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 kinds of trace events should be passed to the script. # # ( By default, only Primitive events from all 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();
}
###################################################################################### # ProcessEvent() # ###################################################################################### # # #
###################################################################################### # 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 # ######################################################################################
# #
ProcessEvent() {
# # The function below will show specified message only one time ­ # no matter how many times ProcessEvent is called. # ShowStartPrompt("ShowStartPrompt\n");
# Write the body of this function depending on your needs …
return Complete();
}
Verification Script Engine Reference Manual
4
###################################################################################### # 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; return 0; }
Verification Script Engine Reference Manual
5
3 Interaction between SierraFC Protocol Suite and
verification script
When a user runs a script over a recorded trace, the following sequence occurs:
1. Prior to sending information to the script's main processing function ProcessEvent(), VSE looks for the function OnStartScript() and calls it if it is found. In this function, some setup routines can be made 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. Next, the VSE goes through the recorded trace and checks if the current frame suits specified sending criteria – if it does, VSE calls the script main processing function ProcessEvent() and sends some information about the current event to the script input context variables. (Please refer to the topic “Input context variables” below in this document for full description of verification script input context variables )
3. ProcessEvent() – is the main verification routine in which all processing of incoming trace event is done. This function must be present in all verification scripts. When the verification program consists of a few stages, the ProcessEvent() function processes the event sent to the script, verifies that information contained in the event is appropriate for the current stage and decides if VSE should continue script running or if the whole result is clear on the current stage – tell VSE to complete execution of the script.
The completion of the test before the entire trace has been evaluated is usually done by setting 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)
NOTE: Not only does a verification script evaluate recorded traces by som e criteria - but it can also extract information of interest and post-process it later by some third-party applications( There is a set of script functions allowing to save extracted data in text files or send it to other applications via COM/Automation interfaces )
4. When script running has completed, VSE looks for function : OnFinishScript() and calls it if it is found. In this function some resetting procedures can be done.
The following figure illustrates the interaction between SierraFC Protocol Suite application and running verification script:
Verification Script Engine Reference Manual
6
The Verification script result "DONE" occurs when the script has been configured to extract and display some information about the trace but to not display PASSED/FAILED results. To configure a script so that it only displays information – place a call somewhere in your script for the function ScriptForDisplayOnly() ) - for example in OnStartScript().
Verification Script Engine Reference Manual
7
4 Running verification scripts from SierraFC Protocol
Suite
In order to run a verification script over a trace - you need to open the SierraFC Protocol Suite
main menu item: Report\Run verification scripts… or push the button on the main toolbar ( if it is not hidden ):
Verification Script Engine Reference Manual
8
The special dialog will open displaying a list of verifications scripts. You can select one or several scripts from the list to run:
Verification Script Engine Reference Manual
9

4.1 Running verification scripts

Push the button ‘Run scripts’ after you selected desired scripts to run. VSE will start running
selected verification scripts, show script report information in the output windows and present results of verifications in the script list:
Verification Script Engine Reference Manual
10
Right-click in script list opens a pop-up menu with options for performing additional operations on
the selected scripts:
- Run verification script(s) – starts running selected script(s)
- Edit script – allows the editing of selected scripts using whatever editor was specified in
‘Editor settings’
- New script – creates a new script file using the template specified in ‘Editor settings’.
- Show Grid – shows/hides a grid in the verification script list.
- Show Description window – shows/hides the script description window.( Shortcut key : F2 )
- Show Output - shows/hides the script output windows. ( Shortcut key : F3 )
- Settings – opens a special ‘Setting’ dialog which allows to specify different settings for VSE.
Verification Script Engine Reference Manual
11

4.2 VSE GUI settings.

After choosing ‘Settings’ the following dialog will appear:

5 Verification Script Engine Input Context members

All verification scripts have input contexts – some special structures which members are filled by the application and can be used inside of the scripts ( 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.
Verification Script Engine Reference Manual
12

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.Level - transaction level of the trace event ( 0 – frames, 1- sequences ) in.Index - Index of the event in the trace file ( frame number for frames, sequence number
f or sequences )
in.Time - time of the event( type : list, having format : 2 sec 125 ns -> [2 , 125].
See 11.1 VSE time object for details)
in.Channel - channel where the event occured. ( may be from _CHANNEL_1 (1) to
_CHANNEL_8 (8) ) indicating on which channel the event occurred )
in.TraceEvent - type of trace events( application predefined constants are used. See list of possible
events below )
in.Notification - type of notifications ( application predefined constants are used.
Currently no notifications are defined )
Verification Script Engine Reference Manual
13

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 frame/sequence-specific set of members Members of this set are valid for any frames.

in.Payload - bit source of the frame/sequence payload ( you can extract any necessary information using GetNBits(), NextNBits() or PeekNBits ( ) functions – please refer to CSL Manual for details about these functions )
in.Frm_PldBytes - the length( in bytes of the retrieved frame payload )
NOTE: in.Frm_Data/in.Seq_Data ... etc depending on the context.
NOTE: Because a payload may be very large – the VSE sets up the in.Payload member up to special limit ( by default 16Mb ). All attempts to get data beyond this limit will produce null values. This limit can be changed via SetTraPayloadLimit () function.
Preferably in.Payload and in.Frm_PldBytes should call a function to return

5.2.2 Primitive fra me-specific set of members (valid for primitive frames only, undefined for other events )

in.Byte1 – first byte of primitive in.Byte2 – second byte of primitive in.Byte3 – third byte of primitive in.Byte4 – fourth byte of primitive in.Primitive – DWORD value of primitive in.NumOfPackedPrims – Contains the number of packed primitives ( 0 – for regular
primitives )

5.2.3 Data frame-specific set of members (valid for data frames only, undefined for other events )

in.R_CTL – Routing Control in.D_ID – Destination ID in.CS_CTL – Class Specific Control in.S_ID – Source ID in.TYPE – Data structure type in.F_CTL – Frame Control in.SEQ_ ID – Sequence ID in.D_ID – Destination ID in.DF_CTL – Data Field Control in.SEQ_CNT – Sequence Count in.OX_ID – Originator Exchange ID in.RX_ID – Responder Exchange ID in.Param – Parameter in.CRC – CRC
Verification Script Engine Reference Manual
14

5.2.4 Sequence-specific set of members ( valid for sequences only, undefined for other events)

in.S_ID – Source ID in.D_ID – Destination ID in.OX_ID – Originator Exchange ID in.RX_ID – Responder Exchange ID in.SEQ_ID – Sequence ID in.EC – Exchange context ( 0 – Originator, 1 - Responder )
in.FML – integer value which is either 0 for middle sequence of exchange or combination of the following flags : _SEQ_FIRST, _SEQ_LAST. ( Hint : use '&' operator to check if this value contains some flag. Like: if( in.FML & _SEQ_FIRST ) DoSomething(); )
in.SI – Sequence Initiative ( 0 – hold, 1 – transfer ) in.TYPE – Data structure type of the first frame of sequence in.R_CTL – Routing Control of the first frame of sequence
in.NumOfFrames – Number of frames in the sequence
in.Pld_Bytes – Number of payload bytes the sequence transferred
in.RespTime – Time from the beginning of the first frame to the end of the last frame ( it has the same format as in.Time. See 11.1 VSE time object for details )
in.Thrpt – The sequence payload divided by response time expressed in megabytes per second
Verification Script Engine Reference Manual
15

6 Verification Script Engine Output Context members

All verification scripts have output contexts – some special structures which members are filled 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.
NOTE: If you don’t care about result of script running please call function
ScriptForDisplayOnly() one time before stopping script – then the result will be DONE.

7 Verification Scr ipt Engine events

VSE defines a large group of trace “events” – both on frame and sequence levels – 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 specify transaction levels and which events should be sent to verification scripts.
Loading...
+ 44 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use