How it Works
Teledyne
Loading...
SATracer
User Manual
68 pgs1.27 Mb0
Table of contents
Loading...

Teledyne SATracer User Manual

Protocol Solutions Group
3385 Scott Blvd., Santa Clara, CA 95054 Tel: +1/408.727.6600 Fax: +1/408.727.6622
Verification Script Engine
for
LeCroy SATracer /SASTracer
Reference Manual
Manual Version 1.01
February 13, 2006
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
Document Disclaimer
The information contained in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected.
LeCroy reserves the right to revise the information presented in this document without notice or penalty.
Trademarks and Servicemarks
LeCroy, CATC, SASTracer, SATracer, SASTrainer, SATrainer Automation are trademarks of LeCroy.
Microsoft, Windows, Windows 2000, and Windows XP are registered trademarks of Microsoft Inc.
All other trademarks are property of their respective companies.
Copyright
Copyright © 2006, LeCroy; All Rights Reserved.
This document may be printed and reproduced without additional permission, but all copies should contain this copyright notice.
Version
This is version 1.0 the SASTracer/SATracer Verification Script Engine Reference Manual. This manual applies to SASTracer/SATracer software version 2.60/4.60 and higher.
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
Table of Contents
1 INTRODUCTION........................................................................................................................... 1
2 VERIFICATION SCRIPT STRUCTURE ................................................................................... 2
3 INTERACTION BETWEEN SASTRACER/SATRACER AND A VERIFICATION
SCRIPT............................................................................................................................................... 5
4 RUNNING VERIFICATION SCRIPTS FROM THE SASTRACER/SATRACER................ 7
4.1 R
4.2 VSE GUI
UNNING VERIFICATION SCRIPTS .......................................................................................... 9
SETTINGS............................................................................................................ 11
5 VERIFICATION SCRIPT ENGINE INPUT CONTEXT MEMBERS .................................. 12
5.1 TRACE EVENT-INDEPENDENT SET OF MEMBERS................................................................... 12
5.2 T
RACE EVENT-DEPENDENT SET OF MEMBERS ...................................................................... 13
5.2.1 Primitives ..................................................................................................................... 13
5.2.2 OOB.............................................................................................................................. 13
5.2.3 SAS/SATA Generic Frame members........................................................................ 13
5.2.4 SAS Open Address Frame members......................................................................... 14
5.2.5 SAS Identify Address Frame members..................................................................... 14
5.2.6 SAS Broadcast and Short Broadcast Address Frame members ............................ 14
5.2.7 SAS SSP Frame members .......................................................................................... 15
5.2.8 SAS SMP Frame members......................................................................................... 16
5.2.9 SATA/STP Frame Members...................................................................................... 24
6 VERIFICATION SCRIPT ENGINE OUTPUT CONTEXT MEMBERS .............................. 28
7 VERIFICATION SCRIPT ENGINE EVENTS ......................................................................... 29
7.1 F
7.2 C
RAME LEVEL EVENTS ........................................................................................................ 29
OMMAND LEVEL EVENTS .................................................................................................. 29
8 SENDING FUNCTIONS.............................................................................................................. 30
8.1 SENDLEVEL()...................................................................................................................... 30
8.2 S
ENDLEVELONLY() ............................................................................................................ 30
8.3 DONTSENDLEVEL() ............................................................................................................ 31
8.4 S
8.5 S
8.6 D
8.7 S
8.8 S
8.9 D
ENDCHANNEL() ................................................................................................................ 31
ENDCHANNELONLY() ....................................................................................................... 32
ONTSENDCHANNEL () ...................................................................................................... 32
ENDALLCHANNELS()........................................................................................................ 33
ENDTRACEEVENT ().......................................................................................................... 33
ONTSENDTRACEEVENT() ................................................................................................. 33
8.10 SENDTRACEEVENTONLY() ................................................................................................. 33
8.11 S
ENDALLTRACEEVENTS().................................................................................................. 34
9 TIMER FUNCTIONS .................................................................................................................. 35
9.1 VSE TIME OBJECT ............................................................................................................... 35
9.2 S
ETTIMER() ........................................................................................................................ 35
9.3 KILLTIMER()....................................................................................................................... 36
9.4 G
ETTIMERTIME()................................................................................................................ 36
ii
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
10 TIME CONSTRUCTION FUNCTIONS.................................................................................. 37
10.1 TIME()................................................................................................................................. 37
11 TIME CALCULATION FUNCTIONS .................................................................................... 38
11.1 ADDTIME() ......................................................................................................................... 38
11.2 SUBTRACTTIME()................................................................................................................ 38
11.3 M
11.4 D
ULTIMEBYINT() .............................................................................................................. 38
IVTIMEBYINT()................................................................................................................ 39
12 TIME LOGICAL FUNCTIONS ............................................................................................... 40
12.1 ISEQUALTIME() .................................................................................................................. 40
12.2 I
12.3 I
SLESSTIME()...................................................................................................................... 40
SGREATERTIME() .............................................................................................................. 40
12.4 ISTIMEININTERVAL().......................................................................................................... 41
13 TIME TEXT FUNCTIONS ....................................................................................................... 42
13.1 T
IMETOTEXT() ................................................................................................................... 42
14 OUTPUT FUNCTIONS .............................................................................................................43
14.1 REPORTTEXT().................................................................................................................... 43
14.2 E
14.3 D
NABLEOUTPUT()............................................................................................................... 43
ISABLEOUTPUT().............................................................................................................. 43
15 INFORMATION FUNCTIONS ................................................................................................ 45
15.1 GETTRACENAME() ............................................................................................................. 45
15.2 G
15.3 G
15.4 G
15.5 G
15.6 G
ETSCRIPTNAME() ............................................................................................................. 45
ETAPPLICATIONFOLDER() ................................................................................................ 45
ETCURRENTTIME()........................................................................................................... 46
ETEVENTSEGNUMBER()................................................................................................... 46
ETTRIGGERPACKETNUMBER()......................................................................................... 46
16 NAVIGATION FUNCTIONS.................................................................................................... 47
16.1 G
16.2 S
OTOEVENT ().................................................................................................................... 47
ETMARKER()..................................................................................................................... 48
17 FILE FUNCTIONS..................................................................................................................... 49
17.1 O
17.2 C
PENFILE()......................................................................................................................... 49
LOSEFILE() ....................................................................................................................... 50
17.3 WRITESTRING() .................................................................................................................. 50
17.4 S
HOWINBROWSER()............................................................................................................ 50
18 COM/AUTOMATION COMMUNICATION FUNCTIONS................................................. 52
18.1 N
OTIFYCLIENT()................................................................................................................. 52
19 USER INPUT FUNCTIONS...................................................................................................... 53
19.1 MSGBOX() .......................................................................................................................... 53
19.2 INPUTBOX() ........................................................................................................................ 55
19.3 G
19.4 S
ETUSERDLGLIMIT()......................................................................................................... 57
ETUSERDLGLIMIT().......................................................................................................... 57
iii
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
20 STRING MANIPULATION/FORMATING FUNCTIONS ................................................... 58
20.1 FORMATEX() ...................................................................................................................... 58
21 MISCELLANEOUS FUNCTIONS........................................................................................... 60
21.1 SCRIPTFORDISPLAYONLY()................................................................................................ 60
21.2 SLEEP() ............................................................................................................................... 60
21.3 C
21.4 P
ONVERTTOHTML() ......................................................................................................... 60
AUSE() .............................................................................................................................. 61
22 THE VSE IMPORTANT SCRIPT FILES ............................................................................... 62
22.1 EXAMPLE SCRIPT FILES ....................................................................................................... 62
iv
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
1 Introduction
This document contains a description of the LeCroy Verification Script Engine (VSE), a new utility in the SATracer/SASTracer software that allows users to perform custom analyses of SAS/SATA traffic, recorded using the new generation of SAS/SATA protocol analyzers.
VSE allows users to ask the SASTracer/SATracer application to send some desired “events” (currently defined as Primitive/Frame/Transaction/Command) from a trace to a verification script written using the LeCroy 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 was designed to allow users to easily retrieve information about any field in a SAS/SATA Frame/Transaction/Command, and to make complex timing calculations between different events in a pre-recorded trace. It also allows filtering-in or filtering-out of data with dynamically changing filtering conditions, porting of information to a special output window, saving of data to text files and sending of data to COM clients connected to a SASTracer/SATracer application.
1
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
2 Verification Script Structure
Writing a verification script is easy, as long as you follow a few rules and have some understanding of how the SASTracer/SATracer application interacts with running scripts.
The main script file that contains the text of the verification script should have extension .sasvs, and be located in the subfolder ..\Scripts\VFScripts of the main SASTracer/SATracer folder. Some other files might be included in the main script file using directive %include. (see CATC Scripting Language Reference Manual for details).
The following schema presents a common structure of a verification script (this is similar to the content of the script template [VSTemplate.pev_] which is included with VSE):
# # # VS1.sasvs # # Verification script # # Brief Description: # Performs specific verification #
############################################################################################# # 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 that # output only Report string and Result. set InputType = "VS";
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.
#
2
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
######################################################################################
OnStartScript() {
###################################################################################### # Specify in the body of this function the initial values for global variables # and what kinds of trace events should be passed to the script. # ( By default, all packet level 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. ######################################################################################
g_MyGlobalVariable = 0;
# 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() {
# Write the body of this function depending upon your needs.
# It might require branching on event type:
# select { # in. TraceEvent == … : … # in. TraceEvent == … : … # … # }
} 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;
######################################################################################
3
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
###################################################################################### # Additional script functions. ###################################################################################### # # Write your own script-specific functions here... # ######################################################################################
MyFunction( arg ) { if( arg == “My Arg” ) return 1; return 0; }
4
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
3 Interaction Between SASTracer/SATracer and a Verification
Script
When a user runs a script against a pre-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, setup actions are defined, such as specifying the kind of trace events that should be passed to the script and setting up initial values for script-specific global variables.
2. Next, the VSE parses the recorded trace to verify that the current packet or other event meets specific criteria—if it does, VSE calls the script’s main processing function ProcessEvent(), placing information about the current event in the script’s input context variables. (Please refer to the topic Input context variables later in this document for a full description of verification script input context variables )
3. ProcessEvent() is the main verification routine for processing incoming trace events. 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 running the script 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 the output context variable in this manner: out.Result = _VERIFICATION_PASSED or _VERIFICATION_FAILED. (Please refer to the topic Output context variables later in this document for a full description of verification script output context variables)
NOTE: Not only does a verification script evaluate recorded traces against some 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 you to save extracted data in text files, or send it to other applications, via COM/Automation interfaces).
4. When the script has completed running, VSE looks for the function OnFinishScript() and calls it if found. In this function, some resetting procedures can be done.
The following figure illustrates the interaction between the SASTracer/SATracer application and a running verification script:
5
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
V
_
_
V
erification Script
OnStartScript()
ProcessEvent()
ProcessEvent()
ProcessEvent()
ProcessEvent()
(If expected event )
(If expected event )
(If expected event )
(If expected event )
Data…
Text File
COM Client
Call..
Call
..
Call
..
Call..
Call
..
SASTracer Application
(Run verification script)
Starting VSE running …
ProcessEvent()
Set out.Result =
VERIFICATION_PASSED
or
VERIFICATION_FAILED
will complete the script run.
OnFinishScript()
PASSED
erification Script results
FAILED
Call
..
(If expected
event )
Call..
DONE
Finishing VSE running … …
The Verification script result "DONE" occurs when the script has been configured to extract and display some information about the trace, but not to display PASSED/FAILED results. To configure a script so that it only displays information—place a call somewhere in your script to the function ScriptForDisplayOnly()in OnStartScript(), for example.
6
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
4 Running Verification Scripts from the SASTracer/SATracer
In order to run a verification script over a trace—you need to open the SASTracer/SATracer
main menu item Report\Run verification scripts… or push the icon on the main toolbar if it is not hidden.
7
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
V
V
A
The special dialog will open displaying a list of verifications scripts. You can select one script to run, or several scripts from the list to run in parallel:
output windows
erification Script List
Name for scripts are file names without extension.
Finds a view related to the verified trace and place this window under it.
.
Starts running selected verification scripts
Finds a view related to the verified trace and place this window by the right side of it.
erification Script description
Descriptions for scripts are defined in set DecoderDesc="MyDescription";
.
Expands. ( Shortcut key : F11. Shift+F11 also maximizes dialog. )
Tabbed output windows for selected verification scripts.
Saves contents of output windows in text files.
llows to set
different settings.
8
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
4.1 Running verification scripts
Push the button Run scripts after you selected the desired script(s) to run. VSE will start
running the selected verification script(s), show script report information in the output windows, and present results of verifications in the script list:
9
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
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 editing of the selected script(s) 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 you to specify different settings for VSE.
10
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
p
g
p

4.2 VSE GUI settings.

After choosing 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 : *.vse )
Otherwise, only main verification script files will be opened for editing.
Launches editor application in full screen mode.
Full path to the file to be used as a template for a new script.
This setting (if set) specifies that the last saved output for selected scripts should be loaded into the out
This setting (if set) brings Run VS dialog to foreground when scripts stopped
.
runnin
This setting (if set) forces the application to save output automatically when the
ts stopped running.
scri
ut windows.
See screen pop-up tooltips for explanation of other settings…
11
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
5 Verification Script Engine Input Context Members
All verification scripts have input contexts – some special structures whose 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.
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
for sequences)
in.Time - time of the event (type: list, having the format: 2 sec 125 ns -> [2 , 125].
(See 9.1 VSE time object for details)
in.Channel - channel where the event occured. (may be
in.TraceEvent - type of trace event (application predefined constants are used. See the list of possible
events, below)
in.Notification - type of notification (application predefined constants are used.
Currently, no notifications are defined)
_CHANNEL_2 (2) indicating which direction of the SAS/SATA link the event occurred)
_CHANNEL_1 (1) or
12
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
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 the variables:
5.2.1 Primitives
in.Primitive – 4-byte value of the Primitive in.Count – Primitive count
5.2.2 OOB
in.OOBType – OOB Types are defind as:
SAS_OOB_UNDETERMINED = 0 SAS_OOB_COMWAKE = 1 SAS_OOB_COMRESET = 2 SAS_OOB_COMSAS = 3
in.OOBBurstIdleList – list of pairs (<burst_or_idle>, <count>), where <burst_or_idle> is 0 for
idle and 1 for burst. Example:
oob_burst_idle_list = in.OOBBurstIdleList;
for ( i = 0; i < sizeof( oob_burst_idle_list ); i++ ) { oob_burst_idle = oob_burst_idle_list[ i ]; report += repIndent; select { oob_burst_idle[ 0 ] == SAS_OOB_ELEMENTTYPE_IDLE :
oob_burst_idle[ 0 ] == SAS_OOB_ELEMENTTYPE_BURST :
}; }
report += Format( "OOBIdle : %ld oobi\n", i, oob_burst_idle[ 1 ] );
report += Format( "OOBBurst : %ld oobi\n", i, oob_burst_idle[ 1 ] );
5.2.3 SAS/SATA Generic Frame members
in.Payload - bit source of the frame/sequence payload (you can extract any necessary information using GetNBits(), NextNBits() or PeekNBits() functions—please refer to the CSL Manual for details about these functions)
in.PayloadLength - the length (in bytes of the retrieved payload)
in.SOF, in.StartOfFrame – 4-byte value of Start of frame primitive
in.EOF,
in.EndOfFrame – 4-byte value of End of frame primitive
in.CRC – CRC value as transmitted
13
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
in.CalculatedCRC – CRC value as calculated

5.2.4 SAS Open Address Frame members

Note: All members return the content of the matching field name (in.xyz returns the value of field “xyz”) based on the SAS specification.
in.Protocol in.InitiatorPort in.SourceAddress in.SourceAddressHi in.SourceAddressLo in.DestinationAddress in.DestinationAddressHi in.DestinationAddressLo in.ConnectionRate in.InitiatorConnectionTag
in.AccessZoneManagement in. SourceZoneGroup
in.PathwayBlockedCount in.ArbitrationWaitTime

5.2.5 SAS Identify Address Frame members

Note: All members return the content of the matching field name (in.xyz returns the value of field “xyz”) based on the SAS specification.
in.DeviceType in.PhyIdentifier in.SSPInitiatorPort in.STPInitiatorPort in.SMPInitiatorPort in.SSPTargetPort in.STPTargetPort in.SMPTargetPort in.SASAddress in.SASAddressHi in.SASAddressLo in. ZoneDevice in. ZoneBroadcastMethod

5.2.6 SAS Broadcast and Short Broadcast Address Frame members

in.BroadcastType in.SourceZoneGroup
14
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01

5.2.7 SAS SSP Frame members

Note: All members return the content of the matching field name (in.xyz returns the value of field xyz) based on the SAS specification.
in.FrameType in. RetryDataFrames in.Retransmit in.ChangingDataPointer in.FillBytes in.Tag in.TargetPortTransferTag in.DataOffset in.HashedDestinationAddress in.HashedSourceAddress
5.2.7.1 COMMAND SSP Frame
in.FrameType is SSP_FRAME_TYPE_COMMAND (0x06)
in.SspCommandScsiOpcode in.SspCommandHasScsiLBA in.SspCommandScsiLBA in.SspCommandLUNHi in.SspCommandLUNLo in.SspCommandTaskAttribute in.SspCommandAdditionalCDBLen
5.2.7.2 XFER_RDY SSP Frame
in.FrameType is SSP_FRAME_TYPE_ XFER_RDY (0x05)
in.SspXferRdyRequestedOffset in.SspXferRdyWriteDatalength
5.2.7.3 RESPONSE SSP Frame
in.FrameType is SSP_FRAME_TYPE_RESPONSE (0x07)
in.SspResponseDATAPRE in.SspResponseStatus in.SspResponseSenseDataLength in.SspResponseResponseDataLength
15
LeCroy Corporation Verification Script Engine Reference Manual Version 1.01
5.2.7.4 TASK SSP Frame
in.FrameType is SSP_FRAME_TYPE_TASK (0x16)
in.SspTaskLUNHi in.SspTaskLUNLo in.SspTaskTaskMGMTFunc in.SspTaskTAG

5.2.8 SAS SMP Frame members

Note: All members return the content of the matching field name (in.xyz returns the value of field xyz) based on the SAS specification.
5.2.8.1 Common SMP Frame members
in.FrameType in.Function
5.2.8.2 SMP Request Frame members
5.2.8.2.1 Report General Frame members
5.2.8.2.2 Report Manufacturer Info Frame members
5.2.8.2.3 Discover Frame members
in.Ignored_1A in.Ignored_2A in.PhyIdentifier in.Reserved_2A in.Reserved_2B in.NoZoneMask
5.2.8.2.4 Report Phy Error Log Frame members
in.Ignored_1A in.Ignored_2A in.PhyIdentifier in.Reserved_2A in.Reserved_2B
16
Loading...
+ 47 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use