USB Decoders

Decoding scripts for Teledyne LeCroy USB Analyzers can now be written in the new CATC Script Decoding Language. The document describing this decoding language is included with the Teledyne LeCroy software on the CD, and also online.

The USB Protocol Suite ships with decoder scripts for many of the classes and their attributes. These files are located in the \LeCroy\USB Protocol Suite\Scripts directory. Users may edit the decoder scripts or create new scripts to accommodate specific development needs, especially decoding of vendor- and application-specific classes and attributes.

This chapter discusses the purposes of the decoder files, along with the common constants, global variables, and functions that make up the USB Protocol Suite Decoding API. The procedures for adding attribute decoders for existing management classes and for creating new management class decoders are provided as well.

Decoder Files

USB Protocol Suite decoders are used to decode packets with vendor-specific data or other custom information so that the custom content can be displayed as a CATC Trace in USB Protocol Suite. The view settings in the scripts may be edited to either reveal or hide particular fields when the header cells are expanded or collapsed. For instance, it may be desirable to have a field visible even when its header cell is collapsed; on the other hand, cells can also be defined so that they are revealed only when the header cell is expanded.

In addition to displaying decoded custom content as data as a trace, the decoder scripts create a special View window that presents the decoded data in a text format. The window is opened by left-clicking on any cell in the trace to access the pop-up View menu and then selecting the “View fields” option.

Script Decoding Mechanisms

The older script decoding mechanism is still supported, and the scripts are now stored in a directory called Legacy in the Scripts directory. The older mechanism is still used for many of the decoding types, such as the Standard descriptors. The scripts for it are the same as those used on USB Chief, the previous generation USB Analyzer. The newer decoding scripts are NOT compatible with USB Chief.

The new script language can be implemented using two different methods. These are distinguished in the scripts by the script variable UsbScriptDecodeType.

When UsbScriptDecodeType=1, the decoding for the colored fields of the trace display are handled separately from the decoding for the text-based decoding seen in the decoding dialogs. If this variable is not initialized in a .dec file, this is the default behavior. The Field Displays are handled through the normal ProcessData() script function, whereas the text is handled through either the DataDecode() or RequestDecode() functions (depending on which one you are trying to decode). You can build up formatted output text in a manner which looks a lot like the older script mechanism this way. It does require some redundant code, however, since this creates a separate execution path in the script. When using this method for creating text, the user is essentially building up a text stream which will be retrieved for display in the Decode Dialog or as a tooltip. An example of this usage is found in the files in the HubClass directory under Scripts. For comparison with the old decoding method, you can look at the old hub decoding scripts in the Scripts/Legacy/Replaced directory. It contains the old version of the Hub and Bluetooth HCI decoders which have been replaced with new Script Decoder based files.

An alternative method (and the one used for all the MassStorage decoders) is when UsbScriptDecodeType=2. In these files, there is one main execution path through ProcessData() which outputs either colored field cells or formatted text, depending on a context variable named PrepareFldsForDlg. This is passed in as a 0 by the software when the decoding is occurring in the normal Trace View, and is set to 1 when being called in situations where text decoding is desired by the software. This is described in detail in earlier chapters. The advantage of this mechanism is that it is easier to program and there is less redundancy of code. The disadvantage is that the format of the output is fixed and not flexible. It is currently implemented to output the decoding fields in simple columns, and the comments/tooltip strings are provided in the last column whenever the trace view for the transfer is shown in Expanded mode. In other words, it is not as pretty, but at least you can select the text and copy it to an editor, etc.

Reserved Variable and Constant Names

The following names are reserved for use in the Script Decoding Files (in addition to those described in earlier chapters). These are case-sensitive, so pay attention to the capitalization.

UsbDecodeType

Values: “Endpoint” or “Request”. Used to distinguish whether the .dec file is to be used for endpoint decoding or for decoding control transfers (The ones that start with a Setup packet).

UsbReqType

Values: “Class” or “Vendor”. Used to distinguish the request types for decoding.

UsbEndpType

Values: “Bulk” or “Interrupt”. Used to distinguish transfer types of the endpoints.

UsbEndpDir

Values: “In” or “Out”. Used to distinguish the endpoint direction. Any endpoint can provide 2 pipes: one in each direction.

UsbMaxPktSize

Value: The maximum packet size allowed for this endpoint/direction com- bination. This will be used to help decode the file.

UsbMaxXferSize

Value: The maximum transfer size allowed for this endpoint/direction combination. This will be used to help decode the file.

UsbMaxXferDecodeSize

Value: The maximum portion of the transfer size that will be examined for possible decoding. If, for example, each transfer had a 25 byte header at the beginning, this value could be used to improve the speed at which the decoding occurs, since the software would only pass the first N bytes to the decoding logic. In cases where there might be a trailer, the value would have to be equal to the maximum transfer length to insure that the last bytes would be examined.

UsbClassCode

Value: The value assigned by the USB IF for this particular Class. For example, Mass Storage is 8 and the Hub Class is 9.

UsbSubClass

Value: If defined, it is specified by the Class Specification. For example, the Mass Storage Class provides for SubClass 4 for UFI (USB Floppy Interface) and SubClass 6 for Transparent SCSI.

UsbProtocol

Value: If defined, it is specified by the Class Specification. For example, the Mass Storage Class provides for Protocol 0x50 for Bulk-Only Transport, and Protocol 0 for CBI (Control/Bulk/Interrupt) Transport.

UsbVendorId

Value: If defined, it is provided for by the Vendor as registered with the USB IF. This is used in the case where you have vendor-specific decoding. For example, if Teledyne LeCroy engineers created a file to decode its communication for its analyzer’s USB Host connection, we would use our USB-IF identification number of 1059.

UsbProductId

Value: If defined, it is provided for by the Vendor. It is used to distinguish decoding based on product-specific differences.

UsbEndpId

Value: You must assign a unique value between 1 and 127 to differentiate endpoint decoders used for the same Class/Vendor group. This value has nothing to do with the actual Endpoint value the device will use for this particular decoder, it is merely a mechanism used by the software to avoid confusion over the mapping of an endpoint decoder to a particular instance of an endpoint.

UsbIgnoreSetupData

Value: 0 (Default) means that the data being passed to this request decoder should include the 8 bytes of the Setup Packet. If the value is 1, the data passed to this decoder starts with that found in the first DATA packet. This is used to provide compatibility with decoders such as the Bluetooth HCI decoder, which is built to be compatible with other non-USB Teledyne LeCroy products which don’t have an 8 byte ‘header’. If this variable is not declared, the default behavior is applied by Software: the 8 byte header is included.

UsbLsbToMsb

Value: 0 (Default) means the data passed to this decoder should have its most significant bit in bit position 7 and it’s least significant bit in bit position 0. If 1, the opposite is true: the data is expected to be LsbToMsb. If this variable is not declared, the default (0) behavior is applied by the software: the bytes are passed as MsbToLsb, otherwise known as “normal”.

UsbReqStr

Value: This will contain the string you build up for the Request portion of the Request text decoding when you have selected “UsbDecodeType =1”. This string will be displayed in the left-hand pane of the text decode dialog.

UsbDescTooltipStr

Value: This will contain the string you build up for the Descriptor portion of the Request text decoding when you have selected “UsbDecodeType=1”. This string should only contain an amount appropriate for displaying as a tooltip.

UsbDataDecodeStr

Value: This will contain the string you build up for the Data portion of the Endpoint text decoding, or the Descriptor portion of a Request decoding when you have selected “UsbDecodeType =1”. This string will be displayed in the text decoding dialog. If this is an endpoint decode, it will be displayed in the only pane of the dialog. If this is a request decode, it will display in the right-hand side pane of the dialog.

UsbDecHdrType

Value: Used to pass explicit information to the decoder to help decoding where the normal data byte stream does not contain enough information or context to allow it to be decoded all by itself. Currently, only the value 2 is used in the case of Mass Storage Decoding. This tells the software that this decoder needs the SCSI or UFI Opcode of the previous transfer to help determine if this is supposed to be a response to a SCSI/UFI Command that was just sent. Without this, it would be impractical to distinguish a normal READ data stream from a SCSI/UFI control request response. This item requires explicit support in the software, so you cannot use it arbitrarily.

UsbDecHdrLen

Value: This specifies the length (up to 8 bytes) of additional context information that will be passed in conjunction with the use of "UsbDecHdrLen". This item requires explicit support in the software, so you cannot use it arbitrarily. It is currently only used for Mass Storage decode, and in that case has a value of 1.

UsbDecExtraInfoBytePos

Value: The byte offset in this transfer where the information byte potentially used for decoding the next transfer exists. For example, in CBI-UFI decoding, the byte at offset 8 contains the UFI Opcode. For Bulk-Only SCSI, the opcode is at offset 15. In both cases, this byte can be used to identify that a subsequent Transfer contains the response data to an issued command. This item requires explicit support in the software, so you cannot use it arbitrarily.

UsbScriptDecodeType

Value: 1 (default) for explicit text decoding, 2 for combined text/field decoding as described in earlier chapters.

Reserved Parameter Strings (Used as values in the above string declarations):

• Request

• Endpoint

• Class

• Vendor

• Bulk

• Interrupt

• In

• Out

Constants

• const COLLAPSED = 0 const EXPANDED = 1

• const WarningColor = RGB(255, 255, 0) #Yellow const ERROR_COLOR = RGB(255, 0,0) #Red

The next constant, WARNING_SIGN, is used in cell tooltips as a delimiter of the “normal” part of the tooltip and the part containing a message about USB specification errors in the subfield.

• const WARNING_SIGN = "\n\n!!! WARNING !!!\n";

This is an example of its use:

...
tooltip = normal_tooltip + WARNING_SIGN +
error_tooltip;
Add...Cell( caption, value, tooltip, _ERROR );
...

Global Variables

val = 0 # global buffer for keeping temporary values of any type.

str = "" # global buffer for keeping temporary values of presumedly string type.

base_tooltip = "" # global buffer for keeping temporary values of presumedly parts of tooltips.

ViewAll = 0 # global variable that keeps View All fields parameter of currently decoded attribute -- this variable is the set attribute decoder responsible for decoding of the current attribute.

HideAll = 0 # global variable that keeps Hide All fields parameter of currently decoded attribute -- this variable is the set attribute decoder responsible for decoding of the current attribute.

Prefix = "" # global variable that keeps the prefix, which is a kind of identifier for the decoder responsible for decoding of the current attribute.

VS = [] # global variable that stores the View setting of the cell currently being shown. It can be used only as a list of two values: [ show_in collapsed, show in expanded ]. When show_in collapsed > 0, it means that the current cell will be shown in collapsed state; otherwise, it will be hidden. show in expanded means the same, but for expanded state only.

The following variables are specific to dialog view:

set Global_BitField_offset = 0; # global variable that contains the offset, in bits, from the beginning of packet for beginning of current attribute. Roughly speaking, it is the entry point from which an attribute decoder starts decoding.

set BitCurrentFieldOffset = 0; # global variable that contains the offset, in bits, from the starting point of decoding for the current field inside of the decoder.

set BitCurrentFieldLength = 0; # the length, in bits, of the currently decoded field.

Common Functions

These are the most commonly-used functions from CATCScriptAPI.inc.

RGB()

RGB(r, g, b)

Comments

Used to define a color based on red, green, and blue values.

Example

RGB(255, 255, 255); #white

SaveFieldSettings()

SaveFieldSettings()

Comments

Saves the global field settings. Can be used in conjunction with RestoreFieldSettings() to show one attribute inside another.

Example

...
...	# pre-decoding of container attribute
SaveFieldSettings();
Global_BitField_offset = MAD_HEADER_LEN_BITS +
amount_of_bits_before_attribute; ShowSomeAttribute(); RestoreFieldSettings( );
...	# post-decoding of container attribute
...

RestoreFieldSettings()

RestoreFieldSettings()

Comments

Restores the global field settings. Can be used in conjunction with SaveFieldSettings() to show one attribute inside another.

Example

See SaveFieldSettings().

Find()

Find(table, table_key)

Comments

Finds a string in the table by a key value. If the key is not found, the first string is returned.

Example

val = Find(AttrIDValue_Table, PacketType);

ShowDataBlock()

ShowDataBlock(len, no_cells)

Comments

Used to display a DataBlock.

Example

ShowDataBlock(40, !VEX_MyDataBlock[in.Expanded]);

AddDecSeparator()

AddDecSeparator()

Comments

Used to create a separator cell.

Example

AddDecSeparator();

Warning()

Warning(text, tooltip)

Comments

Creates a warning cell.

Example

if(in.Expanded) Warning("Bad value", "This is example of Warning-cell.");

WarningForDlg()

WarningForDlg(text, tooltip)

Comments

Creates a warning for dialog view.

Example

WarningForDlg(Format("Not correct AttrM(0x%X)", AttModifier),"Valid values for Attribute Modifier as a pointer to a block of 8 GUIDs\n" + "are from 0 to 31." );

AddWarningTooltip()

AddWarningTooltip(error_tooltip)

Comments

Adds a special warning or error description part to a tooltip string.

Example

...
LID_number = 2345;
tooltip = "LID block number.";
error = null;
error_tooltip = "";
if( LID_number > UPPER_BOUND ) {	error = _ERROR;
error_tooltip = "LID number is out of range"; }
AddSimplePLCell("LID", Format("%d", LID_number ), tooltip + AddWarningTooltip(error_tooltip), error);
...

If there is an error for the cell, the tooltip will display this text:

LID block number.

!!! WARNING !!!

LID number is out of range

The warning message will be displayed in dark red in dialog view.

Another way to add a warning message to a tooltip is to use the WARNING_SIGN constant like this:

...
if( error_tooltip != "" )
error_tooltip = WARNING_SIGN + error_tooltip;

ReservedCheck()

ReservedCheck(bits_reserved)

Comments

Makes a check for next bits_reserved bits that are reserved and should be set to zero. If the bits are not zero, a corresponding warning cell will be shown in expanded state.

Example

ReservedCheck( reserved_bits );

IncFieldOffset()

IncFieldOffset(len)

Comments

Increments the field offset by designated length (len) and sets the field length variable equal to len. This is useful when it’s not possible to obtain a field value using only one GetNBits_ or NextNBits_ command.

Example

IncFieldOffset( 64 );

PrepareFieldForDlg()

PrepareFieldForDlg(field_name, str_value, tooltip, addparam)

Comments

Prepares the field for dialog view. Writes passed data to out.FieldList, using current values of field offset and field length.

Example

PrepareFieldForDlg(caption , text, tooltip );

PrepareZeroFieldForDlg()

PrepareZeroFieldForDlg(field_name, str_value, tooltip, addparam)

Comments

ZeroField means that the field to be added to out.FieldsList is not a data field. Rather, it is an additional field such as a caption or a separator.

Example

PrepareZeroFieldForDlg(caption , text, tooltip);

PrepareFieldForDlgExt()

PrepareFieldForDlgExt(field_name, len, offset, str_value, tooltip, addparam)

Comments

Writes passed data to out.FieldList, using passed values of field offset and field length.

Example

PrepareFieldForDlgExt("FIELD_INIT", 0, Global_BitField_offset);

AddCaptionToDlg()

AddCaptionToDlg(caption, text, tooltip, addparam)

Comments

Writes passed data to out.FieldList as a special field called ‘CAPTION’.

Example

AddCaptionToDlg("Common USB Header", caption + " " + text, tooltip);

AddStringToDlg()

AddStringToDlg(caption, text, tooltip, addparam)

Comments

Writes passed data to out.FieldList as a special field called ‘STRING’.

Example

AddStringToDlg(caption , text, tooltip);

AddDataBlockToDlg()

AddDataBlockToDlg(len)

Comments

Makes a special record about DataBlock with length equal to len for dialog view.

Example

AddDataBlockToDlg(72);

CheckBadDataLength()

CheckBadDataLength()

Comments

Checks offset from beginning of data payload for packet with bad data length and sets the current field color to the error color when the offset exceeds the length of the data payload.

Example

CheckBadDataLength();

NextNBits_()

NextNBits_(next_n_bits)

Comments

This is a redefinition of the NextNBits primitive which increments field offset and field length.

Example

NextNBits_(8);

PeekNBits_()

PeekNBits_(next_n_bits)

Comments

This is a redefinition of the PeekNBits primitive which increments field offset and field length.

Example

PeekNBits_(16);

GetNBits_()

GetNBits_(offset, len)

Comments

This is a redefinition of the GetNBits primitive which increments field offset and field length.

Example

GetNBits_(640, 4);

GetRangeBits()

GetRangeBits(start_bit, end_bit, source)

Comments

Extracts a range of bits from source starting from start_bit and ending at end_bit. Most Significant Bit —> Least Significant Bit order is used here.

Example

GetRangeBits(10, 15, peek_value);

GetBit()

GetBit(bit_needed, source)

Comments

Extracts a bit (bit_needed) from source.

Example

GetBit(3, peek_value);

AddCaptionCell()

AddCaptionCell(caption, text, tooltip, addparam)

Comments

Used to draw a special caption cell.

Example

AddCaptionCell(VNDR_DATA_CAP, "VendorExample", "Example of vendor-attribute decoder.\n\n" + "This attribute is completely fictive and\n" + "was contemplated for example ONLY.\n\n" + "We use AddCaptionCell() for depiction of attribute captions." + "\r" + "Use '\\r' - as delimiter to add extended part of your\n" + "tooltip");

AddPayLoadCell()

AddPayLoadCell(caption, text, tooltip, addparam)

Comments

Draws a payload cell.

Example

AddPayLoadCell("Field_1", "Value : " + Format("0x%04X", NextNBits_(16)), "Field 1\n" + "View setting for this field is set to show field\n" + "both in collapsed and expanded states.\n\n" + "We use AddPayLoadCell() to depict this cell.");

AddPayLoadCellMono()

AddPayLoadCellMono(caption, text, tooltip, addparam)

Comments

Draws a monocolor cell that is similar to the usual payload cell except that both the upper and lower parts of the cell are the same color.

Example

AddPayLoadCellMono("MonoColorField", text, tooltip + "\n\nWe use AddPayLoadCellMono() to depict this cell.\n" + "This monocolor cell is similar to usual payload cell but both upper and\n" + "lower parts of Cell are depicted by the same color defined for this attribute\n" + "in file MAD_colors.inc");

AddPLCellMonoStr()

AddPLCellMonoStr(caption, text, tooltip, addparam)

Comments

Used to begin new group of cells and a table in dialog view that allows the tooltip to be shown below a table caption.

Example

AddPLCellMonoStr("CellMonoStr", Format("%d", NextNBits_(8)), "CellMonoStr.\n\n" + "The AddPLCellMonoStr function is used to begin new group of cells\n" + "and table in dialog view allowing tooltip to be shown below\n" + "a caption of the table.");

AddPLCellMonoCap()

AddPLCellMonoCap(caption, text, tooltip, addparam)

Comments

Creates a monocolored cell. It is intended to be used to start a new group of cells and table in dialog view.

Example

AddPLCellMonoCap("DiagData", "->", "Vendor specific diagnostic information.\n" +
"Format is not defined by USB specification.");

AddPLCellMonoNoDlg()

AddPLCellMonoNoDlg(caption, text, tooltip, addparam)

Comments

Creates a monocolored cell. It is intended to be used to start a new group of cells but doesn’t create a table in dialog view.

Example

AddPLCellMonoNoDlg("LIDs : ", "Valid Ports : ", "");

AddSimplePLCell()

AddSimplePLCell(caption, text, tooltip, addparam)

Comments

A ‘simple’ payload cell does not respond to view settings. It is always hidden when collapsed and always shown when expanded.

Example

AddSimplePLCell("Field 6", "Value : " + Format("0x%01X", NextNBits_(8)), "Field 6\n\n" + "Here we use AddSimplePLCell for showing field.\n" + "The ...SimpleCell-functions don't care about view settings for the field.\n" + "They DON'T show cell in collapsed state but DO show in expanded state.");

AddSimpleCellMonoCap()

AddSimpleCellMonoCap(caption, text, tooltip, addparam)

Comments

A ‘simple’ payload cell does not respond to view settings. It is always hidden when collapsed and always shown when expanded.

Example

AddSimpleCellMonoCap("Private", "Data", "This block contains private data.\n\n" + "This is an example of datablock.");

AddBlockPLCell()

AddBlockPLCell(caption, text, tooltip, addparam)

Comments

Used instead of AddPayLoadCell() for cells in group. ‘Block’ payload cells use view settings contained in global view setting variable VS. This way, one view setting can be applied toa block of cells.

Example

AddBlockPLCell("Group Field_1", "Value : " + Format("0x%04X", NextNBits_(16)), "Block Group Field 1" + "\n\nWe use AddBlockPLCell() to depict this cell.");

AddBlockPLCellMonoStr()

AddBlockPLCellMonoStr(caption, text, tooltip, addparam)

Comments

‘Block’ payload cells use view settings contained in global view setting variable VS. This way, one view setting can be applied to a block of cells.

Example

AddBlockPLCellMonoStr("BM class Notice", str, "This block describes a BaseBoard Management class-specific part of Notice.\n\n" + 
GetBASE_NTooltip());

AddBlockPLCellMonoCap()

AddBlockPLCellMonoCap(caption, text, tooltip, addparam)

Comments

Used to start a new group of cells and table in dialog view, similarly to AddPLCellMonoCap(), except that ‘Block’ payload cells use view settings contained in a global view setting variable VS. This way, one view setting can be applied to a block of cells.

Example

AddBlockPLCellMonoCap("NewGroupOfCells", "MonoColorFieldCap", "MonoColorFieldCap\n" + "This cell and two next follow one common for this group\n" + "view setting : VEX_NewGroupOfCells\n\n" + "We start new group using AddBlockPLCellMonoCap function.\n" + "The same as AddPLCellMonoCap it is intended to start new group of cells -\n" +
"(both part of this cell is painted by the same color) -\n" + "and table in dialog view but it could share the same view setting\n" + "(assigned to global variable VS) for all cells in group.");

ShowItem()

ShowItem(view_setting)

Comments

Used to determine whether an item defined with view_setting is shown.

Example

ShowDataBlock(bytes, !ShowItem(CME_ReadWriteData));

PLReservedCheck()

PLReservedCheck(reserved_bits)

Comments

Used to make a common check of reserved bits while taking into account the view settings. If these bits are not zero, a corresponding warning cell will be shown in the expanded state.

Example

PLReservedCheck(32); PLReservedCheck(8);

UnsignedCompare()

UnsignedCompare(op1, op2)

Comments

This function returns difference between integer values and considers them to be unsigned values. So, the value 0xFFFFFFFF is -1 and less than 0 in logical condi- tions, but as an unsigned integer it is so much bigger than 0. Use this function in places where you want integer values to be thought of as unsigned.

Example

select {
        (low_limit == high_limit) :
          {
          ...
          }
        # (AttModifier < low_limit) || (AttModifier > 
high_limit)	:
        (UnsignedCompare(AttModifier, low_limit) < 0) || (UnsignedCompare(AttModifier, high_limit) > 0) :

      {  
        ...
      }

default : {attrm_chk_error = null; chk_attrmod_tlp = null;}
      };

CurrentFldInit()

CurrentFldInit()

Comments

This function performs necessary initialization routine for a field to be decoded. It must be called before starting field decoding.

Example

CurrentFldInit();

SetFieldOffsetLen()

SetFieldOffsetLen(offset, len)

Comments

This function sets values for field (or subfield) length and offset from beginning of field structure.

Example

SetFieldOffsetLen(24, 8);