P R O T O C O L S O L U T I O N S G R O U P 3 3 8 5 S C O T T B L V D . S A N T A C L A R A , C A 9 5 0 5 4

User-Defined Decoding (UDD)

Advanced Script Language (ASL)

Reference Manual Manual Version 1.25

For Software Version 3.85

November 2012

ii

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 LeCroy is a trademark of Teledyne LeCroy.

Microsoft and Windows are registered trademarks of Microsoft Inc.

All other trademarks are property of their respective companies.

Copyright Teledyne LeCroy © 2012; All Rights Reserved.

This document may be printed and reproduced without additional permission, but all copies should contain this copyright notice.

iii

Table of Contents

ASL MANUAL ..................................................................................................................................................................... 1

INTRODUCTION ................................................................................................................................................................. 1 ABOUT ASL ......................................................................................................................................................................... 1 USER-DEFINED COMMANDS ............................................................................................................................................... 2 LANGUAGE ELEMENTS ........................................................................................................................................................ 6

Integers ........................................................................................................................................................................... 6 Operators ........................................................................................................................................................................ 6 Expression Structure..................................................................................................................................................... 7 Strings ............................................................................................................................................................................. 7 Comments ...................................................................................................................................................................... 7

ADVANCED SCRIPT LANGUAGE PROGRAMMING .................................................................................................. 8 PRODUCT SECTION ............................................................................................................................................................. 8 PROTOCOL DECODING SECTION ........................................................................................................................................ 9

Define Option Block ...................................................................................................................................................... 9 Valid Ranges Block ..................................................................................................................................................... 10 Main Block .................................................................................................................................................................... 11 ASL Decoding Statements ......................................................................................................................................... 11 Functions ...................................................................................................................................................................... 18

PROTOCOL EXTRACTION SECTION ................................................................................................................................... 20 UDD SCRIPTS CAN DECODE MORE THAN ONE COMMAND .............................................................................. 21

ATAPI USER-DEFINED DECODING ............................................................................................................................ 22 ASSIGNING A SCRIPT TO ATAPI COMMANDS .................................................................................................................. 22 WRITING A SCRIPT FOR ATAPI COMMANDS DECODING ................................................................................................. 22

ASSIGNING A UDD SCRIPT AND SETTING IT AS DEFAULT SCRIPT ................................................................ 24 SOFTWARE USER-DEFINED DECODING ........................................................................................................................... 24 SAMPLE USER DEFINED DECODING ................................................................................................................................. 25

1

ASL Manual This manual describes Advanced Script Language (ASL) for defining protocol decodes. It has sample code, documentation, and examples.

Introduction ASL enables you to extract and interpret arbitrary data by creating custom scripts. ASL protocol decodes can decode any class or vendor-specific requests and descriptors, protocols, and any structured data. You can write decode script files in any text editor. You save a script file with an *.asl file extension. Whenever you write a script with Advanced Script Language, it is equivalent to decoding protocols with a language like Visual C++. But learning and using Advanced Script Language helps you decode protocols faster and easier.

About ASL This manual teaches you to define a program for decoding protocol data with ASL. You can use this script for defining any decoding. This script has functionality of a simple programming language, so you can define format of protocols by introducing fields and their attributes: Name, Start bit, Length, MSB order, and description for each field. For defining a decoding format, you must write a program with Advanced Script Language. The grammar of ASL follows the next section.

2

User-Defined Commands User-defined commands help you add additional decoding to viewer. For example, if you have a new command with a vendor opcode, you can use a user-defined script. Note: If you do not use a user-defined script, the viewer does not know the new opcode and displays "unknown command". To allow viewer to know a new opcode: 1. Write a user-defined script with decoding of the new command and save the script file as an *.asl file. 2. Go to Configuration > User defined Decoding menu and add the script file Using the check boxes, you can specify scripts for SCSI commands, ATA commands, SSP frames, STP frames, and SMP frames (one script for each one).

When you open a trace file that contains the new opcode, the application compiles the script file.

3

If application sees any syntax error in the script file, the software adds an Error In Script field to the command.

The application also adds a log (text) file with the same name as the script file and a .txt extension to the "log" folder of the software installation folder. The log file explains the error. If there is no error in the script file, the software decodes the command using script file and displays it in the viewer.

4

The next figure displays a trace file that contains a command with opcode 0x99. The software shows "unknown command" in the viewer

5

You can go to the Configuration > User Defined Decoding menu, check SCSI command, click browse, go to the \Examples\User Define Decoding Script folder, and specify SCSI Command.asl as the script file for SCSI commands. SCSI Command.asl has the decoding of opcode 0x99. Now, if you click OK in the User-defined Decoding dialog, you can see the decoding of that opcode command.

6

Language Elements

Integers ASL accepts integer values in decimal, binary, or hexadecimal formats. Floating point and negative numbers are not accepted. Examples Hexadecimal: 0x21, 0x0001, 0xA5A5 Binary: 0b00100001, 0b1, 0b101001011010010110100101 Decimal: 33, 1, 42405

Operators The following lists operators accepted by ASL. Operator precedence is that same as in C. Operator Function

( ) Associative

and Logical And

or Logical Or

not Logical Not

> Greater than

< Less than

<> Equal to

= Assignment

+ Arithmetic Addition

- Arithmetic Subtraction

* Arithmetic Multiplication

/ Arithmetic Division

7

Expression Structure An expression can be a combination of:

o Logical and compare operators ( or ,and ,not, >, <, <>, =) o Arithmetic operators (+ , - , * and / ) o Valid functions (see Functions section) o Numbers in these formats:

o Hex number: 0x2A o Binary number: 0b00101010 o Decimal number: 33

Example Expression 1: 0x2A and LengthOf(F1) Expression 2: (ValueOf(F1) < 2) or not(LengthOf(F2) <> 10) Expression 3: (4 + LengthOf(F1))*ValueOf(F2) The priority of calculating is:

Not, ( *, and +, or

Strings Strings in ASL are permitted to be static character strings or can contain variable values that are calculated at runtime. A formatted string structure is: “Constant1 (optional) %d (%x, %b) Constant2 (Optional), Value” Constant1 and constant2 are optional. These can be any character string. The value of expressions is replaced by the corresponding strings in either decimal (%d), hexadecimal (%x), or binary (%b) formats, during running of program:

%d: Value replace with decimal format in string %x: Value replace with Hex format in string %b: Value replace with Binary format in string

The formatted string used when you want to make a string dynamically during running script. Examples "This is a static string" "Field length is %d, LengthOf(F1)"

Comments Comments are enclosed in ‘/*’ and ‘*/’ and may span multiple lines. Examples /* This is a single line comment */ /* This is a multi-line comment */

8

Advanced Script Language Programming A script contains three required sections, with only one of each type:

o Product Section: Indicates the product. o Protocol Decoding Section: Breaks the extracted data stream into protocol fields and

decodes the data per each field. o Protocol Extraction Section: Instructs the decoder on how to extract the high-level

protocol data. A section consists of one or more blocks. A block is a procedure that is formed with a series of statements that are enclosed within the block. Each block has a dedicated function within the section and follows one of two formats: Blockname Statement1; Statement2; . . . StatementN; EndBlock { Statement1; Statement2; . . . StatementN; }

Product Section The product section identifies product name, such as ST. (ST should be used for both SAS and SATA.) [ProductName= ST] End

9

Protocol Decoding Section

[Decoding] Define Options Block

Valid Ranges Block Main Block

End As specified above, the decoding section starts with [Decoding] keyword and ends with End keyword. You should write the decoding program in this section. This section consists of Define Option Block, Valid Ranges Block, and Main Block with ASL Decoding Statements. Keywords designate the start and the end of each block. Define Option Block DefineOptions

fieldId1 = ( Description1, Value11-Value12 ;

Description2, Value21-Value22;

Description3, Value3);

fieldId2 = ( Description4, Value4 ;

Description5, Value51, Value52;

);

EndOptions

Remark If a protocol has a field such that each value of that field has an equivalent string, ASL makes this field an optional field. You can define different options of optional fields by the DefineOptions statement. FieldId is a string that specifies the ID of an optional field. Parameters Value is the value of option of the field with specified fieldId. Value1 is lower range for data of the field with specified fieldId. Value2 is upper range for data of the field with specified fieldId. This value is optional. If you want to specify a range for one of options of a field, you must use Value2. Description string is the description for the specified range (Value1 to Value2) or specified value. For format of this parameter see Formatted String Structure. Example /* F3, F4, F1 and BlockStatus are fields. */ DefineOptions F3 = (“First Option”, 0x0000-0x1000, “Second Option”, 0x1001-4352); F4 = (“Option 1 for F4”, 0x0-14, “Option 2 for F4”, 0x0f); F1 =(“Option for F1”, 0x00-0xff); BlockStatus = (“Option for BlockStatus”, 0-0x1100); EndOptions

10

Valid Ranges Block ValidRanges

fieldId 1 = ( Value1 , Value2 );

fieldId 2 = ( Value1 , Value2 );

...

EndValidRanges

Remark This statement specifies valid range of data that can be in a field. In run time, if data that is set in specified field is not in given range, a protocol error generates in packet. Parameters Value1 is lower range for data of the field with specified fieldId. Value2 is upper range for data of the field with specified fieldId. Example /*F4, F1, BlockID are fields.*/ ValidRanges F4=(0x00, 0xAA); BlockID = (0,32); F1=(0b00001,0b0101010); EndValidRanges

11

Main Block Main block contains statements.

Block { Statement 1 ; Statement 2 ; Statement 3 ; … }

ASL Decoding Statements Below are Advance Script Language statements that can be used in this block.

Addfield fieldId = AddField ( StartBit, Length, Name, Description, Abbreviation, BitOrder )

Remark fieldId is a string that specifies ID of fields. Each field has a unique ID. This IDd is the one that you can use when you want to refer to that field. This statement adds a field to packet with given specification. This function increases CURPOS one Length. Note: CURPOS is a pointer that, when a field is added, moves on input data, so it points to current index of data for next field. Parameters StartBit specifies the start bit position of the specified field. Value of this parameter can be an Expression. Length specifies length of the specified field in bits. Value of this parameter can be an Expression. Name specifies Name of field. Description specifies description of field. For the format of this parameter, see the String section Abbreviation specifies abbreviation of field. If field name is long, you can use an abbreviation for the field. For the format of this parameter, see the String section. BitOrder specifies bit order of data of field. Value of this parameter can be one these constants: MSBLEFT, LSBLEFT. This parameter is optional, and if you do not specify this parameter, default value is MSBLEFT. Example /* This statement adds a field at bit #2 of packet with the length of 3 bits. The data of this field will be read from Lowest Bit. */ F1 = AddField(2, 3, ”Name of Field”, ”This field is the flag field.”, ”Abbreviation of field”, LSBLEFT);

12

BitStuff

BitStuff ( FieldId , n )

Remark If, in a protocol, one field transfers after bitstaffing algorithm, you can see actual value of that field by the BitStaff statement. This statement actually runs a unstaff algorithm on specified field. Parameters FieldId is the fieldId defined in AddField. n specifies number of bits for bitstuffing. Example /* Run the bitstuff algorithm on 5 bits of continues 1. */ Flag = AddField(0,8, "Falg","Falg",""); Data = AddField(8,LengthOf(INPUTDATA) - (CURPOS + 16),"Data","Data",""); FCS = AddField(CURPOS,16, "FCS","FCS",""); BitStaff(Data,5); Note: The BitStaff function must be after all AddFields.

GetData DataId = GetData ( StartBit, Length )

Remark DataId is the fieldId defined in AddField. This statement copies a data segment with given specification from INPUTDATA to DataId. You can use copied data by referring to DataId. This function does not increase CURPOS. If you need to know value of a segment of data without adding a field, use this statement. Note: INPUTDATA is an ASL keyword that means input data steam will be passed to script for decoding. Parameters StartBit specifies the start bit position of the specified field. Value of this parameter can be an Expression. Length specifies length of the specified data in bits. Value of this parameter can be an Expression. Example /*This function puts Data from Bit#0 to Bit#9 in a dataId named D31.*/ DataSegment = GetData (0,9);

13

If If Expression Then Block1 Else If Expression Then Block2 Else If Expression Then Block3 Else Block4

Remark The if statement evaluates the expression. (For information about expression, see Expression section.) The if executes block1 if expression is true (nonzero); if else is present and expression is false (zero), it executes block2. After executing block1 or block2, control passes to the next statement. Each block can have several inner if. Example If CURPOS > 5 and ValueOf(F1) < 8 Then { H1 = AddField(CURPOS,8,"H1","Field H1","H1"); } Else if(CURPOS < 9) then { H2 = AddField(CURPOS,8,"H2","Field H2","H2"); } else { H4 = AddField(CURPOS,548,"H4","Field H4","H4"); }

14

Repeat Repeat Expression

Block

Remark This statement repeats all commands in block until Expression is TRUE. Example F1 = AddField(0, 20, "Field1", "It starts form bit# 2", "F1"); F2 = AddField(20, 40, "Field2", "This field is used for..", "F2"); F31 = GetData(32, 10); /* This loop will repeat till current position > 34 (in bits). */ Repeat CURPOS < 100 { F1 = AddField(CURPOS, 23, "SubField of field f1", "subfield of f1", "subfield"); }

Repeat Count Repeat Count = Expression Block

Remark This statement repeats all commands in block as many as value of Expression. Example F1 = AddField(2, 3, "Field1", "It starts form bit# 2", "F1"); F2 = AddField(2, 3, "Field2", "This field is used for..", "F2"); F31 = GetData(32, 343); F31 = GetData(0b01010101, 349843); /* This loop will be run 2 times. */ Repeat Count = 2 { F1 = AddField(CURPOS, 23, "SubField of field f1", "subfield of f1", "subfield"); }

15

SubFieldOf SubFieldOf (FiledId [, Separeted])

Block

Remark This statement specifies subfields of a specific field. Note that all AddField statements that exist in body of SubField statement are relative to specified field. When you define subfields of a field, the packet view shows subfields below field in the viewer. You can expand/collapse subfields. If you want the packet view to show subfields in a separate table, you must write the Separated keyword after FieldId. Parameter FieldId is the fieldId defined in AddField. Separated is a constant keyword that specifies if you want defined subfield to show in a separated table instead of below parent field. Example F1 = AddField(2, 3, "Field1", "It starts form bit# 2", "F1"); F2 = AddField(5, 3, "Field2", "This field is used for..", "F2"); SubFieldOf(F1) { s1 = AddField(0, 1, "Subfield1", "This is subfield of F1", "s1"); s2 = AddField(1, 2, "s2", "a Subfield of f1", "subfield f1"); } SubFieldOf(F2, Separated) /* Viewer shows these subfields in a separated table. */ { s21 = AddField(0, 1, "Subfield1", "This is subfield of F2", "s1"); s22 = AddField(1, 2, "s2", "a Subfield of f2", "subfield f1"); } You can define inner SubFieldOf statements until eight levels.

16

SetTableHeader SetTableHeader(string); SetTableHeader(OptionalFieldId);

Remark This statement sets table header of interpreted data. Viewer shows string in header of table that shows interpretation of data. If you use SetTableHeader(OptionalFieldId) form of this statement, option string of specified OptionalFieldId is set as table header. Parameter String specifies the string that you want to show in header of table. OptionalFieldId specifies FieldId of an optional field. Example OpCode = AddField (0, 8, “Op Code”, “Op Code”, “Op Code”); If (ValueOf (OpCode) = 0x01) then /* Read command */ { SetTableHeader (“Read”); /* Remaining decoding */ }

17

SetFieldTableHeader SetFieldTableHeader(FieldId, string); SetFieldTableHeader(FieldId, OptionalFieldId);

Remark If you specify that subfields of a field are shown as a separated table (see SubFieldOf statement), this statement can set table header. If you use SetFieldTableHeader(FieldId, string) form of this statement, specified string is set in table header. If you use SetFieldTableHeader(FieldId, OptionalFieldId) form of this statement, option string of specified OptionalFieldId is set as table header. For more information about optional field, see the DefineOption statement. Parameter FieldId is the fieldId defined in AddField. String specifies the string that you want to show in header of table. OptionalFieldId specifies FieldId of an optional field. Example OpCode = AddField (0, 8, “Op Code”, “Op Code”, “Op Code”); Type = AddField (CURPOS, 8, “Type”, “Type”, “Type”); SubFieldOf(Type, Separated) { SetFieldTableHeader(Type, “Sub fields of Type”); T1= AddField (0, 4, “T1”, “T1”, “T1”); T2= AddField (4, 8, “T2”, “T2”, “T2”); }

18

Functions

LengthOf ( Data ) Remark This function returns the length of Data. Parameters Data can be INPUTDATA or can be DataId of a data segment specified in the GetData statement or can be a fieldId specified in AddField. If you pass INPUTDATA as parameter, this function returns length of all input data passed to script for decoding.

StartOf ( FIELDIdentifier ) Remark This function returns the start position of the field specified by FieldIdentifier. Parameters FieldIdentifier is the Id of a field that has been described in AddField statement.

ValueOf ( Identifier ) Remark This function returns the value of the Identifier. When you need to know value of a field (or data segment specified by the GetData statement), you can call this function. Parameters Identifier is the Id of a field that has been described in AddField statement or DataId described in GetData Statement.

Find (StartBit, Value) Remark This function searches in input data from the given start bit for specified value. It returns the first position of the first found value. If value is not found, it returns LengthOf(INPUTDATA) + 1. Parameter StartBit specifies the start bit position from which you want to search to end of input data. Value of this parameter can be an Expression. Value is the item to be searched for in this call. Value can be a constant BIN or HEX number or can be an expression. .

19

CURPOS Remark This function returns the current position of the cursor in bits of INPUTDATA. At first, CURPOS is zero and increases one field’s length in each AddField call. CURPOS has a local scope in script, that is, in each SubFieldOf statement, CURPOS has a local scope, too. In each SubFieldOf statement, CURPOS is set to zero and increases one subfield length. When it returns out of subfield statement, CURPOS value is set to the value that it had before SubFieldof statement. Example F1 = AddField(0, 8, “F1”, “F1”, “F1”); F2 = AddField(CURPOS, 8, “F2”, “F2”, “F2”); /* CURPOS is equal to 8 and will be 16 after this statement. */ SubFieldOf(F2) { F11 = AddField(0, 2, “F11”, “F11”, “F11”) ; F12 = AddField(CURPOS, 2, “F12”, “F12”, “F12”) ; /* CURPPOS = 2 */ F13 = AddField(CURPOS, 4, “F13”, “F13”, “F13”) ; /* CURPPOS = 4 */ } F3 = AddField(CURPOS, 2, “F3”, “F3”, “F3”); /* CURPPOS = 16 */

EOD Remark If CURPOS is at the end of data, this function returns TRUE. If not, returns FALSE. That is, if all input data has been decoded, this function returns TRUE.

INPUTDATA Remark INPUTDATA is a symbolic representation of the entire data stream that is passed to the decoder.

20

Protocol Extraction Section The Protocol Extraction section specifies how the data is extracted from traffic to one or more endpoints. This section is required in every script file and must precede all other sections. This section has: ProtocolName, ProtocolTransferRequirement, and ProtocolTransferDefinition. ProtocolName (required) is the name of that is shown in the User-defined page. ProtocolTransferRequirement block identifies all endpoints involved in the transfer of the high-level protocol data. The data can be sourced from either a control endpoint zero or non-control endpoints, or both. Each type of source has additional properties that completely specify the endpoint. ProtocolTransferDefinition block is the mechanism by which high-level protocols are transferred and specifies how Command, Data, and Status stages are arranged across the assigned endpoints. Depending on the protocol, the Data and Status stages can be omitted. Example ProtocolName = "NameString" ProtocolTransferRequirement { < ControlTransfer { ControlType = Class | Vendor <ControlRequest = number1 <, ..., numberN>> } > < Endpoint = EndpointId1 { EndpointNumber = number EndpointType = Bulk | Interrupt | ISO MaximumPacketSize = number Direction = In | Out } > < Endpoint = EndpointIdN { EndpointNumber = number EndpointType = Bulk | Interrupt | ISO MaximumPacketSize = number Direction = In | Out } > } < ProtocolTransferDefinition { ProtocolCommand = ControlTransfer | DataStage | EndpointId <MCS = number> <ProtocolData = EndpointId1 <, EndpointId2> <MDS = number> <IsOptional>> <ProtocolStatus = EndpointId <MSS = number> <IsOptional>> <ToggleEndpoints = EndpointId1, …, EndpointIdN > } > End

21

UDD Scripts Can Decode More Than One Command UDD scripts can decode more than one command, so it is not necessary to run more than one script at a time. Here is an example: OpCode = AddField (0, 8, "Op Code", "Op Code", "Op Code"); If (ValueOf (OpCode) = 0x01) then /* First command */ { H1 = AddField(CURPOS,8,"H1","Field H1","H1"); H2 = AddField(CURPOS,2,"H2","Field H2","H3"); // more decodings } Else If (ValueOf (OpCode) = 0x02) then /* Second command */ { F1 = AddField(CURPOS,8,"F1","Field F1","F1"); F2 = AddField(CURPOS,2,"F2","Field F2","F2"); F2 = AddField(CURPOS,3,"F3","Field F3","F3"); // More decodings } Else If (ValueOf (OpCode) = 0x03) then /* Third command */ { // decodings } Else { /// decodings } Note: You can add more Else If instrunctions.

22

ATAPI User-Defined Decoding

Assigning a Script to ATAPI Commands Open a sample, then choose User defined decoding … from the Configuration pull-down menu to display the following dialog. Select ATAPI & SCSI command(s) and assign a user-defined script to the sample.

Writing a Script for ATAPI Commands Decoding If you want the SCSI fields of a UDD ATAPI commands to have the same color as a SCSI command fields, do the following. A user-defined ATAPI command has two or more fields. The first field must have the name Operation Code, with length 1 byte. The options of the Operation Code field must be defined in the DefineOptions section of the script. OperationCode =( "Vendor 99", 0x99; "Vendor 66", 0x66; "Vendor 77", 0x77); For example: OperationCode = AddField(CURPOS,8,"Operation Code", "Operation Code","Operation Code"); Otherwise, different fields can be defined, and the fields of UDD ATAPI commands would have the same color as ATA-command fields. If the length of the last field is not certain, define the last field with the length LengthOf(INPUTDATA)- CURPOS – 8, as in following example: VendorSpecific = AddField(CURPOS, LengthOf(INPUTDATA)- CURPOS – 8 , "Vendor Specific","Vendor Specific","Vendor Specific");

23

The UDD ATAPI command can have one or more additional fields. In the following example, the UDD ATAPI command has four fields with a specific length. OperationCode = AddField(CURPOS, 8 , "Operation Code", "Operation Code", "Operation Code");

LBA = AddField(CURPOS,24,"LBA","LBA","LBA");

TransferLength = AddField(CURPOS, 8, "Transfer Length", "Transfer Length", "Transfer Length"); Control = AddField(CURPOS, 8, "Control", "Control", "Control");

24

Assigning a UDD Script and Setting It as Default Script You can specify UDD items using two methods.

Software User-Defined Decoding In this mode, you can set UUD items for the next captured sample file. When the active view has no sample file, this following SAS or SATA dialog opens:

SAS Software UDD Dialog

SATA Software UDD Dialog

25

Sample User Defined Decoding In this mode, you can set UDD items for the current active sample file. Changes only apply to that sample file. When the active view is a sample file, the following SAS or SATA dialog opens.

SAS Sample UDD Dialog

SATA Sample UDD Dialog Note: The Set as default button sets these sample UDD items to software UDD items.