Teledyne Verification User Manual
PROTOCOL SOLUTIONS GROUP
3385 SCOTT BLVD
SANTA CLARA, CA 95054
Verification Script Engine
for
Teledyne LeCroy USB Protocol Suite™
Reference Manual
Manual Version 2.1
For USB Protocol Suite version 4.70 and above
July 2013
Teledyne LeCroy Verification Script Engine Reference Manual
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.
Teledyne LeCroy reserves the right to revise the information presented in this document without notice
or penalty.
Trademarks and Servicemarks
Teledyne, Teledyne LeCroy, LeCroy, CATC, and USB Protocol Suite are trademarks of Teledyne
LeCroy.
Microsoft and Windows are registered trademarks of Microsoft Inc.
All other trademarks are property of their respective companies.
Copyright
Copyright © 2009, Teledyne LeCroy, Inc. All Rights Reserved.
This document may be printed and reproduced without additional permission, but all copies should
contain this copyright notice.
Page 2 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
Contents
1 INTRODUCTION ..............................................................................................................................................6
2 VERIFICATION SCRIPT STRUCTURE ...........................................................................................................7
3 INTERACTION BETWEEN APPLICATION AND VERIFICATION SCRIPT ................................................ 10
4 RUNNING VERIFICATION SCRIPTS FROM APPLICATION ...................................................................... 12
4.1 RUNNING VERIFICATION SCRIPTS ............................................................................................................ 14
4.2 VSE GUI SETTINGS ............................................................................................................................... 16
5 VERIFICATION SCRIPT ENGINE INPUT CONTEXT MEMBERS ............................................................... 17
5.1 TRACE EVENT-INDEPENDENT SET OF MEMBERS ...................................................................................... 17
5.2 TRACE EVENT-DEPENDENT SET OF MEMBERS ......................................................................................... 18
5.2.1 USB Packet-specific Set of Members .............................................................................................. 18
5.2.1.1 USB Bus Condition-specific Set of Members .......................................................................... 20
5.2.1.2 USB2 Packet-specific Set of Members ................................................................................... 21
5.2.1.3 USB3 Packet-specific Set of Members ................................................................................... 24
5.2.2 Transaction-specific Set of Members.............................................................................................. 29
5.2.3 Split Transaction-specific Set of Members ..................................................................................... 31
5.2.4 Transfer-specific Set of Members .................................................................................................... 32
6 VERIFICATION SCRIPT ENGINE OUTPUT CONTEXT MEMBERS ........................................................... 33
7 VERIFICATION SCRIPT ENGINE EVENTS ................................................................................................. 34
7.1 PACKET LEVEL EVENTS .......................................................................................................................... 35
7.2 TRANSACTION LEVEL EVENTS ................................................................................................................. 37
7.3 SPLIT TRANSACTION LEVEL EVENTS ....................................................................................................... 37
7.4 TRANSFER LEVEL EVENTS ...................................................................................................................... 37
8 SENDING FUNCTIONS................................................................................................................................. 38
8.1 SENDLEVEL() ......................................................................................................................................... 38
8.2 SENDLEVELONLY() ................................................................................................................................ 39
8.3 DONTSENDLEVEL() ................................................................................................................................ 40
8.4 SENDCHANNEL() .................................................................................................................................... 41
8.5 SENDCHANNELONLY() ........................................................................................................................... 42
8.6 DONTSENDCHANNEL() ........................................................................................................................... 43
8.7 SENDALLCHANNELS() ............................................................................................................................ 44
8.8 SENDTRACEEVENT() .............................................................................................................................. 45
8.9 DONTSENDTRACEEVENT() ..................................................................................................................... 46
8.10 SENDTRACEEVENTONLY() ..................................................................................................................... 47
8.11 SENDALLTRACEEVENTS() ...................................................................................................................... 48
8.12 SENDDIRECTION() .................................................................................................................................. 49
8.13 SENDUSB2BUSCONDITIONS() ................................................................................................................. 50
8.14 SENDUSB2TOKENPACKETS() ................................................................................................................. 51
8.15 SENDUSB2DATAPACKETS () .................................................................................................................. 52
8.16 SENDUSB2HSKPACKETS() ..................................................................................................................... 53
8.17 SENDTRANSACTION() ............................................................................................................................. 54
8.18 SENDTRANSFER() .................................................................................................................................. 55
8.19 SENDPKTSWITHBADCRC() .................................................................................................................... 56
9 PACKET AND SCRIPT DECODED FIELDS RETRIEVING FUNCTIONS ................................................... 57
Page 3 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
9.1 GETDECODEDPKTFIELD() ....................................................................................................................... 57
9.2 GETHEXPKTFIELD() ............................................................................................................................... 58
9.3 GETDECODEDSCRIPTFIELD() .................................................................................................................. 59
9.4 GETHEXSCRIPTFIELD() .......................................................................................................................... 60
10 TIMER FUNCTIONS................................................................................................................................. 61
10.1 VSE TIME OBJECT ................................................................................................................................. 61
10.2 SETTIMER() ............................................................................................................................................ 62
10.3 KILLTIMER() ........................................................................................................................................... 63
10.4 GETTIMERTIME() .................................................................................................................................... 64
11 TIME CONSTRUCTION FUNCTIONS ..................................................................................................... 65
11.1 TIME() .................................................................................................................................................... 65
12 TIME CALCULATION FUNCTIONS ........................................................................................................ 66
12.1 ADDTIME() ............................................................................................................................................. 66
12.2 SUBTRACTTIME() ................................................................................................................................... 67
12.3 MULTIMEBYINT().................................................................................................................................... 68
12.4 DIVTIMEBYINT() ..................................................................................................................................... 69
13 TIME LOGICAL FUNCTIONS .................................................................................................................. 70
13.1 ISEQUALTIME() ...................................................................................................................................... 70
13.2 ISLESSTIME() ......................................................................................................................................... 71
13.3 ISGREATERTIME() .................................................................................................................................. 72
13.4 ISTIMEININTERVAL() ............................................................................................................................... 73
14 TIME TEXT FUNCTIONS ......................................................................................................................... 74
14.1 TIMETOTEXT()........................................................................................................................................ 74
15 OUTPUT FUNCTIONS ............................................................................................................................. 75
15.1 REPORTTEXT() ....................................................................................................................................... 75
15.2 ENABLEOUTPUT() .................................................................................................................................. 76
15.3 DISABLEOUTPUT() ................................................................................................................................. 77
16 INFORMATION FUNCTIONS .................................................................................................................. 78
16.1 GETTRACENAME() ................................................................................................................................. 78
16.2 GETSCRIPTNAME()................................................................................................................................. 79
16.3 GETAPPLICATIONFOLDER() .................................................................................................................... 80
16.4 GETCURRENTTIME() ............................................................................................................................... 81
16.5 GETTRACESTARTTIME() ......................................................................................................................... 82
16.6 GETTRACEENDTIME() ............................................................................................................................ 83
17 POWER TRACKER FUNCTIONS ........................................................................................................... 84
17.1 ISPOWERCAPTURED () ............................................................................................................................... 84
17.2 GETPWRPOWERVALUE() ........................................................................................................................ 85
17.3 GETPWRVOLTAGEVALUE() ..................................................................................................................... 86
17.4 GETPWRCURRENTVALUE() .................................................................................................................... 87
18 NAVIGATION FUNCTIONS ..................................................................................................................... 88
18.1 GOTOEVENT() ........................................................................................................................................ 88
18.2 SETMARKER() ........................................................................................................................................ 89
19 FILE FUNCTIONS .................................................................................................................................... 90
Page 4 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
19.1 OPENFILE() ............................................................................................................................................ 91
19.2 CLOSEFILE() .......................................................................................................................................... 92
19.3 WRITESTRING() ...................................................................................................................................... 93
19.4 WRITE() ................................................................................................................................................. 94
19.5 SHOWINBROWSER() ............................................................................................................................... 95
20 TRACE FILE EXPORTING FUNCTIONS ................................................................................................ 96
20.1 CREATETRACEFILE() .............................................................................................................................. 97
20.2 CLOSETRACEFILE()................................................................................................................................ 98
20.3 ADDEVENTTOTRACEFILE() ..................................................................................................................... 99
20.4 OPENTRACEFILE() ............................................................................................................................... 100
21 COM/AUTOMATION COMMUNICATION FUNCTIONS ....................................................................... 101
21.1 NOTIFYCLIENT() ................................................................................................................................... 101
22 USER INPUT FUNCTIONS .................................................................................................................... 102
22.1 MSGBOX() ........................................................................................................................................... 102
22.2 INPUTBOX() ......................................................................................................................................... 104
22.3 GETUSERDLGLIMIT() ........................................................................................................................... 106
22.4 SETUSERDLGLIMIT() ............................................................................................................................ 107
23 STRING MANIPULATION/FORMATING FUNCTIONS ........................................................................ 108
23.1 FORMATEX() ........................................................................................................................................ 108
24 MISCELLANEOUS FUNCTIONS .......................................................................................................... 110
24.1 SCRIPTFORDISPLAYONLY() .................................................................................................................. 110
24.2 SLEEP() ............................................................................................................................................... 111
24.3 CONVERTTOHTML() ............................................................................................................................ 112
24.4 PAUSE() ............................................................................................................................................... 113
25 THE IMPORTANT VSE SCRIPT FILES ................................................................................................ 114
26 HOW TO CONTACT TELEDYNE LECROY .......................................................................................... 115
Page 5 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
1 Introduction
This document describes the Teledyne LeCroy USB Protocol Suite™ Verification Script Engine (VSE), which
allows users to perform complicated custom analyses of traffic recorded using the Teledyne LeCroy protocol
analyzers.
The VSE allows you to create verfication scripts that ask the application to send specific "events" (see Chapter
7: "Verification Script Engine Events") that occur in the recorded trace to a function that can process them. This
function, along with other logic in a verification script, can be used to evaluate the sequence of events (timing,
data, or both) in accordance with user-defined conditions and perform post-processing tasks; such as exporting
key information to external files (in text or binary format) or sending special Automation™/COM notifications to
client applications.
Verfication scripts are based on the CATC Scripting Language (CSL). It is recommended to review the "CATC
Scripting Language Reference Manual for CATC USB Analzyers" (USBScriptDecodeManual.pdf). This
document covers the semantics, functions, and other specifics for the VSE, however the sematics of the
scripting language itself, such as data types and other helper functions and primitives can be found in the CSL
reference manual.
The VSE fully utilizes the high performance and intelligence of Teledyne LeCroy decoding capabilities, making
processing of information easy and fast. VSE can:
Retrieve information about any field in frame headers, contents of frame payloads, serial data, and bus
states.
Make complex timing calculations between different events in pre-recorded traces.
Filter-in or filter-out data with dynamically changing filtering conditions.
Port information to a special output window.
Save data to text or binary files.
Send data to COM clients connected to the application.
Page 6 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
2 Verification Script Structure
Writing verification scripts is easy, if you understand how the application interacts with running scripts and if you
follow some rules imposed by the verification script syntax.
The main file with the text of the verification script must have extension .vse. It must be located in the subfolder
..\Scripts\VFScripts of the main folder. Some other files must be included in the main script file using the
directive %include.
The following schema presents a common structure of a verification script. It is similar to the script template
VSTemplate.vs_, which is included with VSE.
#
# 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.
Page 7 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
######################################################################################
# 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() #
# #
# Main intialization routine for setting up all necessary #
# script parameters before running the script. #
# #
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, only Primitive events from all channels #
# are passed to the script. #
# #
# For details about how to specify the kind of events to pass to the script, #
# please see the topic ‘Sending Functions’. #
# #
# OPTIONAL. #
######################################################################################
# Uncomment the line below if you want to disable output from
# ReportText()-functions.
#
# DisableOutput();
}
Page 8 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
######################################################################################
# ProcessEvent() #
#
# #
# Main script function called by the application when the next waited event #
# occurs in the evaluated trace. #
# #
# !!! REQUIRED !!! MUST BE IMPLEMENTED IN THE VERIFICATION SCRIPT #
# #
ProcessEvent()
{
# Write the body of this function depending on your needs.
Return Complete();
}
# OnFinishScript() #
#
# Main script function called by the application when the script has 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;
}
Page 9 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
3 Interaction between Application and Verification
Script
The following steps describe the interaction between the application and a verification script run over a recorded
trace:
1. Before sending any information to the script main processing function ProcessEvent() (which must be
present in any verification script),VSE looks for function OnStartScript() and calls it if it is found. In this
function, some setup routines can be made, like specifying the channels, specifying the trace events to
pass to the script, and setting up initial values of the global script-specific global variables.
2. Then VSE goes through the recorded trace and checks if the current frame in the trace meets specified
sending criteria. If it does, VSE calls the script main processing function ProcessEvent(), providing
some information about the current event in the script input context variables.
(See the topic "Input context variables" below in this document for a full description of verification script
input context variables.)
3. ProcessEvent() is the main verification routine, in which all processing of incoming trace events is done.
Basically, when the whole verification program consists of a few stages, this 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. If the whole result is clear on the current
stage, it tells VSE to complete execution of the script.
The completion of the test before the whole trace has been evaluated is usually done by setting the
output context variable:
out.Result = _VERIFICATION_PASSED or _VERIFICATION_FAILED.
(See the topic "Output context variables" below in this document for a full description of verification script
output context variables.)
Note: Not only does a verification script verify recorded traces by some criteria, but it is also possible to
extract some information of interest and post-process it later by third-party applications. (There is a set
of script functions to save extracted data in text or binary files or send it to other applications via
COM/Automation™ interfaces.)
1 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 presents the interaction between the application and a running verification script:
Page 10 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
OnStartScript()
Starting VSE running …
Verification Script
Call..
Application
(Run verification script)
ProcessEvent()
Call..
(If expected event )
ProcessEvent()
Call..
(If expected event )
ProcessEvent()
Call..
(If expected event )
ProcessEvent()
Set out.Result =
_VERIFICATION_PASSED
or
_VERIFICATION_FAILED
will complete the script run.
Call..
(If expected
event )
OnFinishScript()
Finishing VSE running … …
Call..
PASSED
FAILED
DONE
Verification Script results
ProcessEvent()
Call..
(If expected event )
File
COM
Client
Data…
Note: Verification script result <DONE> means that the script is intended for extracting and displaying some
information from recorded traces only, and you do not care about results. To specify that your script is for
displaying information only, call the function ScriptForDisplayOnly() somewhere in your script (in
OnStartScript(), for instance).
Page 11 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
4 Running Verification Scripts from Application
To run a verification script over a trace, you select the main menu item Report > Run verification scripts or
click the Run verification scripts button on the main tool bar (if it is not hidden):
Page 12 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
Verification Script List.
Name for scripts are file names
without extension.
Verification Script description.
Descriptions for scripts are defined in
set DecoderDesc= "MyDescription";
Starts running selected
verification scripts
Expands output windows. (
Shortcut key : F11. Shift+F11
also maximizes dialog. )
Tabbed output
windows for selected
verification scripts.
Saves contents of
output windows in
text files.
Allows to set
different settings.
Finds a view related to the
verified trace and place this
window under it.
Finds a view related to the
verified trace and place this
window by the right side of it.
The Run verification scripts dialog opens where you choose then run one or several verification scripts:
Page 13 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
4.1 Running Verification Scripts
Push the button Run scripts after you select scripts to run. VSE starts running the selected verification scripts,
shows script report information in the output windows, and presents the results of verifications in the script list:
Page 14 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
Right-clicking the script list displays some additional operations over selected scripts:
Run verification script(s): Start running selected script(s).
Edit script: Edit selected scripts in the editor application specified in Editor settings.
New script: Create a new script file using the template specified in Editor settings.
Show Grid: Show/hide a grid in the verification script list.
Show Description window: Show/hide the script description window (Shortcut key F2).
Show Output: Show/hide the script output windows (Shortcut key F3).
Settings: Open a special Setting dialog to specify different settings for VSE.
Page 15 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
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 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 setting (if set) specifies that the last
saved output for selected scripts should
be loaded into the output windows.
This setting (if set) brings Run VS dialog
to foreground when scripts stopped
running.
This option specifies that potential runtime errors and warnings like calling not
defined functions etc. shouldn't be
reported.
See screen pop-up tooltips for
explanation of other settings…
This setting (if set) forces the application
to save output automatically when the
scripts stopped running.
4.2 VSE GUI Settings
After choosing Settings, the following dialog appears:
Page 16 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5 Verification Script Engine Input Context Members
All verification scripts have input contexts, special structures that can be used inside of the scripts. The
application fills their members. The verification script input contexts have two sets of members:
Trace event-independent set of members
Trace event-dependent set of members
Note: All input context members have integer type values unless their types are explicitly specified.
If possible values for input context members are not explicitly specified, they should comply with the current USB
specifications.
5.1 Trace Event-independent Set of Members
This set of members is defined and can be used for any event passed to a script:
in.Level: Transaction level of the trace event. It can be one of the following constants:
_PKT: Packet level (value = 0)
_TRA: Transaction level (value = 1)
_SPL_TRA: Split Transaction level (value = 2)
_XFER: Transfer level (value = 3)
in.Index: Index of the event in the trace file (packet number for packets etc).
in.Time: Time of the event (type = list, having format = 2 sec 125 ns -> [2 , 125]. For more information, see
section 10.1 VSE Time Object.
In.Channel: Indicates on which channel the event occured. It can be one of the following constants:
_USB2: USB2 traffic (value = 1)
_USB3_RX: USB3 Host Receive traffic (Upstream, value = 2)
_USB3_TX: USB3 Host Transmit traffic (Downstream, value = 3)
in.Speed: Indicates the speed for the trace event. It can be one of the following constants:
_FS: USB2 Full Speed (value = 1)
_LS: USB2 Low Speed (value = 2)
_HS: USB2 High Speed (value = 3)
_SS: USB3 Super Speed (value = 4)
in.Direction: Indicates the direction for the trace event. It can be one of the following constants:
_IN: Direction is from Host to Device (value = 2)
_OUT: Direction is from Device to Host (value = 3)
_BOTH: Trace event involves traffic in both directions (value = 4)
in.TraceEvent: Type of trace events. (Application predefined constants are used. See list of possible events
in Chapter 7. Verification Script Engine Events.)
in.Notification: Type of notifications. (Application predefined constants are used. Currently no notifications
are defined.)
Page 17 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
Error type
Bit position
Description
USB2 Errors:
PID_ERROR
1
Bad PID value
CRC5_ERROR
2
Bad CRC5
CRC16_ERROR
3
Bad CRC16
PACKETLEN_ERROR
4
Wrong packet length
BIT_STUFF_ERROR
5
Bit stuffing error
EOP_ERROR
6
Bad End Of Packet
BABBLE_START_ERROR
7
Babble start error
BABBLE_END_ERROR
8
Babble end (Loss Of Activity) error
FRAME_LENGTH_ERROR
9
Wrong frame length
HANDSHAKE_TIMEOUT_ERROR
10
Bad turnaroud timing or timeout
condition for handshake
INTERNAL_ERROR
11
Analyzer internal error
DATA_TOGGLE_ERROR
12
Data toggling error
MICROFRAME_ERROR
13
Bad frame or microframe number
MOD_8_ERROR
14
Last Byte Incomplete error
OTG_ERROR
15
Bad OTG Signal value
USB3 Errors. TBD.
5.2 Trace Event-dependent Set of Members
This set of members is defined and can be used only for a specific event or after calling functions that provide
values of variables:
5.2.1 USB Packet-specific Set of Members
Members of this set are valid for all USB packet events:
in.RawPacket: Bit source of the whole packet. Note: You can extract any necessary information using the
GetNBits(), NextNBits(), or PeekNBits() functions. (Refer to section 14 in the USBScriptDecodeManual.pdf.)
in.RawPacketLength: Length of the packet (in bytes).
in.Duration: Time it took to transmit the packet on the bus (VSE Time object).
in.Errors: A bitmap of packet level errors. The table below describes the current list of possible packet errors
and their bit positions in the error bitmap:
Page 18 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
Vbus Power parameter values:
in.Power: The value of Vbus power as measured at the time the packet was transmitted (in microwatts). Will
be set to a null value if the power information is not present in the trace.
in.Voltage: The value of the Voltage as measured at the time the packet was transmitted (in microvolts). Will
be set to a null value if the power information is not present in the trace.
in.Current: The value of the Current as measured at the time the packet was transmitted (in microampers).
Will be set to a null value if the power information is not present in the trace.
Page 19 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
Bus Condition
in.BusCondition
Value
Description
CHIRP_K
_CHIRP_K
0
Device "K" Chirp to notify host
of Hi Speed capability
CHIRP_J
_CHIRP_J
1
Device "J" Chirp to notify host
of Hi Speed capability
FS_K_ON_HS
_FS_K_ON_HS
2
Full Speed "K" signaling on Hi
Speed branch
FS_J_ON_HS
_FS_J_ON_HS
3
Full Speed "J" signaling on Hi
Speed branch
SUSPEND
_SUSPEND
4
Suspend signaling
RESUME
_RESUME
5
Resume signaling
SE1
_SE1
6
SE1 signaling
SE0
_SE0
7
SE0 FS or LS signaling (can
be keep-alive for LS)
VBUS_VOLTAGE_CHANGE
_VBUS_VOLTAGE_CHANGE
44(0x2C)
Change of Vbus Voltage
5.2.1.1 USB Bus Condition-specific Set of Members
Note: Valid for Bus Condition trace events only, undefined for other events.
in.BusCondition: Type of Bus Condition events.
The table below describes the current list of possible Bus Condition events and values of in.BusCondition:
in.BusCondDuration: Duration of the Bus Condition event in nanoseconds.
Page 20 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.2 USB2 Packet-specific Set of Members
Note: Valid for USB2 packets only, undefined for other events.
The following input context members apply to most of the USB2 packets.
in.Pid: Packet Identifier value for the packet. It is the full PID value, the following constants are defined in the
VS_constants.inc include file and can be used by scripts:
# USB 2.0 PID values
const PID_OUT = 0x87;
const PID_IN = 0x96;
const PID_SOF = 0xA5;
const PID_SETUP = 0xB4;
const PID_DATA0 = 0xC3;
const PID_DATA1 = 0xD2;
const PID_DATA2 = 0xE1;
const PID_MDATA = 0xF0;
const PID_ACK = 0x4B;
const PID_NAK = 0x5A;
const PID_STALL = 0x78;
const PID_NYET = 0x69;
const PID_PRE = 0x3C;
const PID_ERR = 0x3C;
const PID_SPLIT = 0x1E;
const PID_PING = 0x2D;
const PID_EXT = 0x0F;
in.SubPidPacket: If non-zero, signals that this packet is a protocol extension token as defined by the Link
Power Management ECN. In this case the Pid value should be treated as the SubPid (only LPM currently
defined).
in.CRC5: CRC5 value for packets (not relevant for Data packets).
Page 21 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.2.1 USB2 Token Packet Members
in.Addr: Value of the Address (ADDR) field of the Token packet.
In.Endp: Value of the Endpoint (ENDP) field of the Token packet.
5.2.1.2.2 USB2 Start Of Frame Packet Members
in.FrmNum: Frame number for the current USB2 frame.
In.MicroFrmNum: Microframe number for the current microframe as determined by the Analyzer (would be
zero for Full Speed frames).
5.2.1.2.3 USB2 Data Packet Members
in.Payload: Bit source of the packet payload. Note: You can extract any necessary information using
GetNBits(), NextNBits(), or PeekNBits() function. (Refer to section 14 in the USBScriptDecodeManual.pdf.)
in.PayloadLength: Length (in bytes) of the packet payload.
in.CRC16: CRC16 value for the Data packet.
5.2.1.2.4 USB2 Split Token Packet Members
in.HubAddr: Value of the Hub Address field, the USB device address of the hub supporting the specified full-
/low-speed device for this full-/low-speed transaction.
in.SC: Value of the Start/Complete bit for the split token.
in.Port: Value of the Port field – the port number of the target hub for which this full-/low-speed transaction is
destined.
in.S: Value of the Speed bit for the split token.
in.E: Value of the End bit for the split token.
in.ET: Value of the Endpoint Type field for the split token.
Page 22 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.2.5 Link Power Management Extended Token Members
in.HIRD: Value of the Host Initiated Resume Duration field.
in.bLinkState: Value of the bLinkState field for the LPM extended token.
in.bRemoteWake: Value of the bRemoteWake bit for the LPM extended token.
in.Reserved: Value of the reserved field for the LPM extended token.
Page 23 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.3 USB3 Packet-specific Set of Members
Note 1: Valid for USB3 packets only, undefined for other events.
Note 2: The system does not pass all possible fields of USB3 packets as members of Input Context. If a script
needs to use the values of those fields, use the GetHexPktField and GetDecodedPktField functions. See
5.2.1.3.12 for examples.
5.2.1.3.1 TSEQ Training Sequence Ordered Set Members
in.Count: Value of TSEQ count, the number of sequential TSEQ sequences sent
5.2.1.3.2 TS1/TS2 Training Sequence Ordered Set Members
in.Count: Value of TS count, the number of sequential TS1 or TS2 sequences sent
in.LnkFunctionality: Value of the whole Link Functionality (Link Configuration) byte in the training
sequence
in.Reset: Value of the Reset bit in the Link Configuration byte.
in.SSDisable: Value of the Spread Spectrum bit in the Link Configuration byte.
in.Loopback: Value of the Loopback asserted/deasserted bit in the Link Configuration byte.
in.ScrDisable: Value of the Disable Scrambling bit in the Link Configuration byte.
5.2.1.3.3 LFPS Packet Members
in.Type: Type of LFP signaling
in.Duration: Duration of LFP signaling in nanoseconds
5.2.1.3.4 Inter-Packet Symbols Packet Members
in.NumOfSymbols: Number of symbols in the IPS sequence
Page 24 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.3.5 Link Command Packet Members
in.LnkCmd: Index of the Link Command type (constants are defined in VS_constants.inc)
in.LinkCmdInfo: Value of the Link Command Information field for the Link Command Word
in.CRC5: Value of CRC5 for the Link Command Word
in.LinkCmdInfo_2: Value of the Link Command Information field for the replica of the Link Command Word
in.CRC5_2: Value of CRC5 for the replica of the Link Command Word
5.2.1.3.6 SKIP Packet Members
in.Count: Count of symbols in the SKIP sequence
5.2.1.3.7 Logical Idle Packet Members
in.Count: Count of symbols in the Logical Idle sequence
5.2.1.3.8 Link Management Packet Members
in.SubType: SubType value for LMP. Use constant definitions in VS_constants.inc.
5.2.1.3.9 Isochronous Timestamp Packet Members
in.BusICounter: Bus Interval Counter value for ITP, in 1/8 of a millisecond
in.Delta: Time Delta value for ITP
in.BusIAdjCtrl: Bus Interval Adjustment Control value for ITP, specifying the device in control of
bus interval adjustment
Page 25 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.3.10 Transaction Packet Members
in.SubType: SubType value for Transaction Packet. Use constant definitions in VS_constants.inc.
in.Addr: Address of the device that receives this Transaction Packet
in.Endp: Endpoint number on the device that receives this Transaction Packet
in.Dir: Direction for the specified Endpoint
in.StreamID: Value of the StreamID field
5.2.1.3.11 Data Packet Members
in.Addr: Address of the device which is the recipient of this Data Packet
in.Endp: Endpoint number on the device which is the recipient of this Data Packet
in.Dir: Direction for the specified Endpoint
in.StreamID: Value of the StreamID field
in.SeqN: Value of the Sequence Number for this Data Packett
in.DataLength: Length of the payload for this Data Packet
in.PayloadLength: Length of the payload actually recorded for this Data Packet
in.Payload: Bit source of the packet payload for this Data Packet. Note: You can extract any necessary
information using the GetNBits(), NextNBits(), or PeekNBits() function. (Refer to section 14 in the
USBScriptDecodeManual.pdf.)
in.CRC32: Value of CRC32 protecting the payload for this Data Packet
Note: In USB Protocol Suite software versions earlier than 3.71 (namely, 3.60 and 3.70), Data Packet Header
and Data Packet Payload were two separate packet types with input context members split accordingly between
them. Those were combined into a single Data Packet starting with version 3.71.
Page 26 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.1.3.12 Getting Values of the Fields not present in Input Context
As mentioned earlier, not all the possible fields of USB3 packets are passed as members of Input Context. The
following are examples of using GetHexPktField and GetDecodedPktField functions to get values of the fields
not present in Input Context.
If( in.TraceEvent == _USB3_LMP_PKT )
{
# Example of using decoded packet information for LMPs.
# ‘SubType’ field,
# String value
str = FormatEx("\tSubType(str) = ‘%s’", GetDecodedPktField("SubType"));
ReportText( str );
# Hex Value
val = GetHexPktField ( "SubType" );
str = FormatEx( "\tSubType(hex) = 0x%X\n", val );
ReportText( str );
# ‘Hseq’ field
# String value
str = FormatEx( "\tHseq(str) = ‘%s’", GetDecodedPktField ( "Hseq" ) );
ReportText( str );
# Hex Value
val = GetHexPktField ( "Hseq" );
str = FormatEx( "\tHseq(hex) = 0x%X\n", val );
ReportText( str );
}
if( ( in.TraceEvent == _USB3_TP_PKT ) && ( in.SubType == TP_ACK ) )
{
# Example of using decoded packet information for TPs.
# ‘SeqN’ field
# String value
str = FormatEx( "\tSeqN(str) = ‘%s’", GetDecodedPktField ( "SeqN" ) );
ReportText( str );
# Hex Value
val = GetHexPktField ( "SeqN" );
str = FormatEx( "\tSeqN(hex) = 0x%X\n", val );
ReportText( str );
# ‘NumP’ field
# String value
str = FormatEx( "\tNumP(str) = ‘%s’", GetDecodedPktField ( "NumP" ) );
ReportText( str );
Page 27 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
# Hex Value
val = GetHexPktField ( "NumP" );
str = FormatEx( "\tNumP(hex) = 0x%X\n", val );
ReportText( str );
}
if( in.TraceEvent == _USB3_DP_PKT )
{
# Example of using decoded packet information for DPs.
# ‘SeqN’ field
# String value
str = FormatEx( "\tSeqN(str) = ‘%s’", GetDecodedPktField ( "SeqN" ) );
ReportText( str );
# Hex Value
val = GetHexPktField ( "SeqN" );
str = FormatEx( "\tSeqN(hex) = 0x%X\n", val );
ReportText( str );
# ‘ENDP’ field
# String value
str = FormatEx( "\tENDP(str) = ‘%s’", GetDecodedPktField ( "ENDP" ) );
ReportText( str );
# Hex Value
val = GetHexPktField ( "ENDP" );
str = FormatEx( "\tENDP(hex) = 0x%X\n", val );
ReportText( str );
}
# Link Control Word
if( ( in.TraceEvent == _USB3_TP_PKT ) ||
( in.TraceEvent == _USB3_DP_PKT ) )
{
ReportText( "LCW:" );
val = GetHexPktField ( "Hseq" );
str = FormatEx( "\tHseq = %d", val );
ReportText( str );
val = GetHexPktField ( "Hdepth" );
str = FormatEx( "\tHDepth = %d", val );
ReportText( str );
val = GetHexPktField ( "D1" );
str = FormatEx( "\tDelayed (D1) = %d", val );
ReportText( str );
val = GetHexPktField ( "D2" );
str = FormatEx( "\tDeferred (D2) = %d\n", val );
ReportText( str );
}
Page 28 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
5.2.2 Transaction-specific Set of Members
in.TraToken: Token PID for the transaction. Possible values are:
const PID_OUT = 0x87;
const PID_IN = 0x96;
const PID_SETUP = 0xB4;
const PID_SPLIT = 0x1E;
const PID_PING = 0x2D;
const PID_EXT = 0x0F;
in.Addr: Device Address value for this Usb transaction.
in.Endp: Device Endpoint Number value for this Usb transaction.
in.TraCompletionFlag: Handshake PID for the transaction (if any). Possible values are:
const PID_ACK = 0x4B;
const PID_NAK = 0x5A;
const PID_STALL = 0x78;
const PID_NYET = 0x69;
const PID_ERR = 0x3C;
0xFFFFFFFF – in case no handshake was sent for the transaction.
in.Complete: Flag, signaling if the transaction was complete.
in.XferType: Type of the USB Transfer this transaction belongs to. See Transfer Types for possible values.
in.CtrlDirection: For a Setup transaction represents the direction of the corresponding Control Transfer.
0 = Host-to-device
1 = Device-to-host
in.FirstInXfer: This flag is set when the transaction is first in the transfer it belongs to.
in.LastInXfer: This flag is set when the transaction is last in the transfer it belongs to.
in.Errors: Error code for the transaction, if any error happened.
If the transaction is a Setup transaction, the following input context members provide values of the
corresponding fields of the USB Device Request:
in.ReqType
in.ReqRecipient
in.bRequest
in.wIndex
in.wValue
in.wLength
Page 29 of 115
Teledyne LeCroy Verification Script Engine Reference Manual
in.Split: Signals that the transaction is a start-split or complete-split.
in.HubAddr: Value of the Hub Address field, the USB device address of the hub supporting the specified full-
/low-speed device for this full-/low-speed transaction.
in.SC: Value of the Start/Complete bit for the split token.
in.Port: Value of the Port field – the port number of the target hub for which this full-/low-speed transaction is
destined.
in.S: Value of the Speed bit for the split token.
in.E: Value of the End bit for the split token.
in.ET: Value of the Endpoint Type field for the split token.
in.OTGHostId: For USB On-The-Go transactions, indicates if the A-device is acting as the host (value of 0) or
the B-device is acting as the host (value of 1).
in.OTGErrorCode: For USB On-The-Go transactions, indicates error code if non-zero.
in.OTGErrorCodeOffset: For USB On-The-Go transactions with errors, indicates the offset from the first
packet in the transaction to the packet with error.
in.PayloadLength: Length (in bytes) of the packet payload. If zero, the transaction does not have any
payload.
in.Payload: Bit source of the transaction data payload. Note: You can extract any necessary information using
the GetNBits(), NextNBits(), or PeekNBits() function. (Refer to section 14 in the USBScriptDecodeManual.pdf.)
Page 30 of 115
Loading...