Packet and Script Decoded Fields Retrieving Functions | Protocol Solutions User Documentation

This group of functions covers VSE generic capability to extract information about data payload fields decoded with CATC Script Language (CSL) at Transfer level and all decoded fields at Packet level for USB3 packets.

GetDecodedPktField()

Extracts information about a USB3 or Power Delivery packet field and determines how it is shown in the USB Protocol Suite trace view or the "View … Fields" dialog.

GetDecodedPktField ( fld_name )

Parameters
fld_name	Name of the field supposedly existing in the current packet

Return Values

If the field name is in the current packet, the return value is the text value of the decoded field and how to display it in the trace view. Otherwise, the return value is the empty string.

Example

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 );
  }

Remarks

The field name should be exactly the same as it is in the trace. The field name is case-sensitive.

This rule also applies to power delivery packet fields but if the field name contains blank or non-alpha numeric characters, all those characters must be replaced with "_" character

Fields containing ' or ' ' characters are replaced with "Prime" or "DPrime" strings respectively.

GetHexPktField()

Extracts the raw hexadecimal value of the USB3 packet field.

GetHexPktField ( fld_name )

Parameters
fld_name	Name of the field supposedly existing in the current packet.

Return Values

If the field name is in the current packet, the function returns the hex value of the decoded field:

integer value if field length is less than 32 bits
raw binary value if field length is greater than 32 bits. The raw binary value gives a list of bytes.
See the CSL Manual for further details about raw binary values.
null value if the field was not found.

Example

# 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 );
}

Remarks

The field name should be exactly the same as it is in the trace. The field name is case-sensitive.

GetDecodedScriptField()

Extracts information about the script decoded field and determines how it is shown in the USB Protocol Suite trace view or the "View … Fields" dialog.

GetDecodedScriptField ( fld_name )

Parameters
fld_name	Name of the field supposedly existing in the current transfer.

Return Values

If the field name is in the current transfer, the return value is the text value of the decoded field and how to display it in the trace. Otherwise, the return value is the empty string.

Example

# Extract the decoded value of wValue field
# for a Control transfer that uses a certain Class
# or Vendor specific decoding.
str  = GetDecodedScriptField ("wValue");

# If the bulk transfer payload decoded by the script decoder 
# has a field named 'Code' (i.e., PTP transfers):
str = FormatEx( " Code(str) = '%s' ", GetDecodedScriptField ( "Code" ) );

Remarks

The field name should be exactly the same as it is in the trace. The field name is case-sensitive.

This function can be used only at the transfer level.

GetHexScriptField()

Extracts the raw hexadecimal value of the script decoded field.

GetHexScriptField ( fld_name )

Parameters
fld_name	Name of the field supposedly existing in the current transfer.

Return Values

If the field name is in the current Transfer, the function returns the hex value of the decoded field:

integer value if field length is less than 32 bits
raw binary value if field length is greater than 32 bits. The raw binary value gives a list of bytes.
See the CSL Manual for further details about raw binary values.
null value if the field was not found.

Example

# Extract the hex value of the LBA field for mass storage.
val  = GetHexScriptField ( "Logical Block Addr" );

# Extract the hex value of the SomeBig field.
if( GetHexScriptField ( "Some Big" ) ==  'FE80000000000000' )
     ReportText( "Some Big field = FE80-0000-0000-0000");

Remarks

The field name should be exactly the same as it is in the trace. The field name is case-sensitive.

This function can be used only at the transfer level.

HasPacketError()

Сhecks if the current packet contains an error.

HasPacketError ( erorr_bit_index )

Parameters
error_bit_index	Bit index of the error to check. May be one of the values in the table below.

Error type	Bit position	Description
USB4 Errors
USB4_SB_FALSE_CONNECT	83	At least 25 us of high-logic is needed for Connect
USB4_SB_FALSE_DISCONNECT	84	At least 14 us of low-logic is needed for Disconnect
USB4_SB_INCOMPLETE_PACKET	85	Incomplete packet
USB4_INVALID_CLSE	86	Invalid CLSE
USB4_CRC_ERROR	87	CRC error
USB4_RSVD_NOT_ZEROED	88	Reserved field not zeroed
USB4_UNEXPECTED_DLE	89	Unexpected DLE symbol
USB4_DATA_SYMBOLS_LEN	90	Invalid command len
USB4_DLE_NOT_DUPLICATED	91	DLE symbol not duplicated
USB4_ETX_MISSING	92	EXT symbol missing
USB4_LEN_FIELD_ERROR	93	LEN field error
USB4_DATA_SIZE_ERROR	94	Incorrect data size
USB4_UNDEFINED_DATA_SIZE_ERROR	95	Undefined data size
USB4_INVALID_LSE_SYMBOL	96	Invalid LSESymbol
USB4_HS_INCOMPLETE_PACKET	97	Incomplete packet
USB4_UNKNOWN_PACKET_TYPE_USS	98	Unidentified Symbol Sequence - USS
USB4_ERROR_PACKET_CONTENT	99	Error packet content
USB4_TS_LANE_NUMBER_ERROR	100	TS Lane Number field contains incorrect value
USB4_TS_LANE_BONDING_ERROR	101	LBT (Lane bonding target) field value does not match LBT2
USB4_UNKNOWN_PACKET_TYPE_IPS	102	Unknown packet - IPS
USB4_ERROR_SCR	103	SCR content error
USB4_ERROR_HEC	104	HEC Error
USB4_ERROR_PAYLOAD_CRC	105	CRC Error
USB4_ERROR_PAYLOAD_ECC	106	ECC Error
USB4_ERROR_CONTROL_PACKET_DATA_SIZE	107	Data Size is either less 0 dw or greater 60 dw
USB4_ERROR_CONTROL_PACKET_ADAPTER_NUM	108	Adapter Num is invalid
USB4_WARNING_NOTIFICATION_EVENT_CODE	109	Unknown Notification Code
USB4_WARNING_NOTIFICATION_PG	110	Notification Packet is not a Hot Plug Acknowledgment
USB4_ERROR_CONTROL_INTERDOMAIN_PACKET_ROUTE_STRING_CM	111	Interdomain CM is invalid
USB4_ERROR_TLP_HEADERS_GAP	112	Invalid gap between HS packets
USB4_ERROR_LEN_AND_DATA_SIZE_NOT_MATCH	113	Length and size values don't match
USB4_ERROR_PAYLOAD_LENGTH	114	Payload length is invalid
USB4_WARNING_INCOMPLETE_SLOS_WAKE_PACKET	115	Incomplete SLOS/WAKE packet
USB4_TUNNELED_PCIE_RSVD_NOT_ZEROED	128	Tunneled PCIe: Reserved field not zeroed
USB4_TUNNELED_PCIE_CRC_ERROR	129	Tunneled PCIe: CRC Error
USB4_TUNNELED_PCIE_INVALID_ENCODING	130	Tunneled PCIe: TLP/DLLP Invalid Encoding
USB4_TUNNELED_PCIE_ERROR_PAYLOAD	131	Tunneled PCIe: TLP Error Payload
USB4_TUNNELED_PCIE_ERROR_LENGTH_FIELD	132	Tunneled PCIe: TLP Error Length
USB4_TUNNELED_PCIE_ERROR_TC_FIELD	133	Tunneled PCIe: TLP TC Error (not 0)
USB4_TUNNELED_PCIE_ERROR_ATTR_FIELD	134	Tunneled PCIe: TLP Attr Error (not 0)
USB4_TUNNELED_PCIE_ERROR_BYTE_ENABLES	135	Tunneled PCIe: TLP Byte Enables Violation
USB4_TUNNELED_PCIE_MEM_ERROR_ADDR_LEN	136	Tunneled PCIe: Memory TLP Address/Length crosses 4K
USB4_TUNNELED_PCIE_MEM_ERROR_WRONG_TYPE	137	Tunneled PCIe: Mem64 TLP used incorrectly
USB4_TUNNELED_PCIE_CFG_ERROR_REGISTER	138	Tunneled PCIe: Cfg TLP Register error
USB4_TUNNELED_PCIE_MSG_ERROR_ROUTING	139	Tunneled PCIe: Msg TLP Invalid Routing
USB4_TUNNELED_PCIE_OS_NOT_START_WITH_BC	140	Tunneled PCIe: OS not starting with BCh
USB4_TUNNELED_PCIE_EIS_PERST_DATA_ERROR	141	Tunneled PCIe: EIS/PERST Payload error (not 0)
USB4_TUNNELED_PCIE_UNKNOWN_PRE_HEADER	142	Tunneled PCIe: TLP/DLLP unknown pre-header
USB4_TUNNELED_PCIE_PRE_HEADER_LEN_ERROR	143	Tunneled PCIe: TLP pre-header LEN field error
USB4_TUNNELED_PCIE_PRE_HEADER_CHK_ERROR	144	Tunneled PCIe: TLP pre-header CHK field error
USB4_TUNNELED_PCIE_RSVD_PDF_ERROR	145	Tunneled PCIe: Reserved PDF is used
USB4_TUNNELED_PCIE_TS_DATA_RATE_ERROR	146	Tunneled PCIe: Training Sequence Data Rate error
USB4_TUNNELED_PCIE_TS_FORMAT_ERROR	147	Tunneled PCIe: Training Sequence Format error
USB4_TUNNELED_PCIE_OS_INVALID_CONTENT	148	Tunneled PCIe: Ordered Set content is Invalid (not TS/EIOS)
USB4_ERROR_MULTIPLE_RETIMER_INDEXES_IN_CL_WAKE	149	Multiple Re-timer Indexes in CL_WAKE (CL_WAKE1, CL_WAKE2)
USB4_ERROR_ZERO_RETIMER_INDEX	150	Zero Re-timer Index in CL_WAKE (CL_WAKE1, CL_WAKE2, CL_WAKE1-2)
USB4_ERROR_DESKEW_SYMBOL_LOCATION	151	Location of De-Skew within symbol is incorrect (each De-Skew should be sent on both Lanes in the same locations within the symbol)
PD_EPR_BATTERY_VARIABLE_NOTSUPPORTED	152	Battery/Variable PDOs are not supported in EPR
USB4_XFER_CAPABILITY_LENGTH_ERROR	153	USB4 Transfer: Capability Length exceeds NextCapPtr value
USB4_ERROR_INVALID_ELT_TYPE	154	Invalid ELTtype
USB4_SB_INVALID_WAKE_DURATION	155	The wake duration is not between 1000 and 9000 ns
USB3_NAKed_DATA_PACKET_ERROR	156	Not Acknowledged DP
USB4_ERROR_INVALID_CELSE	157	Invalid CELSE
USB4_G4_TS_BAD_INDICATION_COMPLEMENT	158	Incorrect bitwise complement of Indication
USB4_G4_TS_BAD_COUNTER	159	Invalid Counter associated with Indication field
USB4_G4_TS_BAD_COUNTER_COMPLEMENT	160	Incorrect bitwise complement of Counter
USB4_G4_TS_BAD_PAYLOAD	161	Error in PRBS11 or PRTS7 part of the TS
USB4_G4_OS_CORRUPTED_SYMBOL	162	Invalid Symbol in OS
USB4_G4_OS_TSNOS_DELAY_EXCEED	163	Delay Symbol exceeds 1000 Symbols
USB4_SB_SHORT_DISCONNECT	164	50 ms of low-logic is needed for SBTX to identify a Disconnect

Return Values

If the current packet contains the required error, the function returns 1 (true), otherwise – 0 (false).

Example

# loop over the range of error indices 
for( err_idx = USB4_FIRST_ERROR_INDEX; err_idx <= USB4_LAST_ERROR_INDEX; err_idx++ )
{
  if( HasPacketError( err_idx ) ) # call the function with some error index
  {
    # packet has some error
  }
}
# packet has no error from the given range

HasUsb4TraceError()

Checks if a USB4 error occurred in a trace file.

HasUsb4TraceError ( erorr_bit_index )

Parameters
error_bit_index	Bit index of the USB4 error to check. May be one of the USB4 values in the table from HasPacketError().

Return Values

If the trace contains the required error, the function returns 1 (true), otherwise – 0 (false).

Example

if (HasUsb4TraceError(USB4_ERROR_HEC))
{
  ReportText("HEC error occurred \n");
}
else
{
  ReportText("HEC error has not occurred \n");
}

GetUsb4LegacyTBT3Protocol()

Checks if a USB4 trace file was recorded on TBT3 protocol.

GetUsb4LegacyTBT3Protocol ()

Return Values

If the trace file was recorded on TBT3 protocol, the function returns 1 (true), otherwise – 0 (false).

Example

if (GetUsb4LegacyTBT3Protocol())
{
  ReportText("TBT3 Prorocol \n");
}
else
{
  ReportText("USB4 Protocol \n");
}

GetUsb4HopIDListSize()

Returns the number of HopIDs (for Control packets and Tunneled packets) for the specified channel.

GetUsb4HopIdListSize( channel )

Parameters
channel	Channel number. May be one of the values from the list of constants for in.Channel

Return Values

The number of HopIDs for the specified channel

GetUsb4HopIDList()

Returns the list of HopIDs (for Control packets and Tunneled packets) for the specified channel.

Note: Use “GetUsb4HopIDListSize” function to get the number of HopIDs in the list.

GetUsb4HopIdList( channel )

Parameters
channel	Channel number. May be one of the values from the list of constants for in.Channel

Return Values

The list of HopIDs for the specified channel

Example

hop_id_count = GetUsb4HopIDListSize(_USB4_HS_ANALYZER_LEFT);
hop_ids = GetUsb4HopIDList(_USB4_HS_ANALYZER_LEFT);
for (hop_id_idx = 0; hop_id_idx < hop_id_count - 1; hop_id_idx++)
{
  summary += Format("%d, ", hop_ids[hop_id_idx]);
}

GetUsb4TunneledHopIDListSize()

Returns the number of HopIDs (for Tunneled packets, excluding Control packets) for the specified channel.

GetTunneledUsb4HopIdListSize( channel )

Parameters
channel	Channel number. May be one of the values from the list of constants for in.Channel

Return Values

The number of HopIDs for the specified channel.

GetUsb4TunneledHopIDList()

Returns the list of HopIDs (for Tunneled packets, excluding Control packets) for the specified channel.

Note: Use GetUsb4TunneledHopIDListSize to get the number of HopIDs in the list.

GetUsb4TunneledHopIdList( channel )

Parameters
channel	Channel number. May be one of the values from the list of constants for in.Channel

Return Values

The list of HopIDs for the specified channel.

Example

hop_id_count = GetUsb4TunneledHopIDListSize(_USB4_HS_ANALYZER_LEFT);
hop_ids = GetUsb4TunneledHopIDList(_USB4_HS_ANALYZER_LEFT);
for (hop_id_idx = 0; hop_id_idx < hop_id_count - 1; hop_id_idx++)
{
  summary += Format("%d, ", hop_ids[hop_id_idx]);
}

GetUsb4LinkType()

Note: This function is deprecated. Use the associated in.LinkType to query each Gen4 TxFFE register mapping type.

GetOppositePortRole()

Returns the port role that is opposite to the one provided.

GetOppositePortRole ( packet_port_role )

Parameters
packet_port_role	Packet port role. A value of in.PacketPortRole for a Sideband packet.

Return Values

The port role for the opposite side.

Example

port_role = in.PacketPortRole;
if(in.WnR == 1)
{
  # get opposite port role for write request
  port_role = GetOppositePortRole(port_role);
}
link_type = GetUsb4LinkType(port_role);