Transaction Engine Instructions

Starting with software version 3.70, the Voyager USB 3.2 Exerciser implements Transaction Engine, an advanced high-performance logic facility supporting all the basics of the USB3 Super Speed transaction layer protocol. Transaction Engine allows easy scripting of application level functionality scenarios for Super Speed device enumeration, configuration, data transfer, and other functions, for both Host and Device emulation.

Transaction Engine accepts a list of Pipe Commands, each specifying a data transfer on an endpoint. While executing this data transfer, it automatically follows Super Speed protocol for sequence numbering, bursting, and transaction-level flow control (NRDY/ERDY and NumP-based flow control).

Transaction Engine has one basic instruction to operate it and one instruction to initialize and configure non-default endpoint operation. These two instructions are described in the following sections.

SendPipeCommand Instruction

This instruction sets up all transactions or transfers to be executed by the Transaction Engine.

SendPipeCommand( command, pipe type, total length, setup, 
data pattern, asn, store data, send ERDY, transaction engine index )
{
    PipeCommandData
    {
        Field = Value
        ...
    }
}

The SendPipeCommand has the following parameters:

• command: Defines the specific Pipe Command. Possible values are described in the Pipe Command table below..

• pipe type: Specifies the Pipe Type for the endpoint on which the command is being set up. Possible values are described in the Pipe Type table below..

• total length: Specifies the total length of data transfer associated with this Pipe Command.

• setup: Equals 1 if the specified transaction is a Setup transaction. Equals 0 (zero) for all other cases.

• data pattern: Specifies which data pattern to use for seeding the payload, if one should be included with this transaction/transfer. Possible values are described in the Data Pattern table below.

• asn: Automatic Sequence Number. Equals 1 for Transaction Engine to automatically handle Sequence Numbers for the TPs and DPs that it generates for the specified endpoint.
  Equals 0 (zero) to override Transaction Engine behavior, for example to create Sequence Number errors. If asn = 0, specify the starting Sequence Number in the PipeCommandData structure.

• store data:

  • Voyager M3x, M310, and M310C:Specifies whether the packets sent by the DUT during execution of this Pipe Command are stored by Firmware (for PIPE_CMD_READ_DATA commands) or sent by the Exerciser using the previously stored data (for PIPE_CMD_WRITE_DATA commands). For details on this use, see Loopback Featurebelow.Default is zero (data is not stored in and not sourced from the internal buffer).

  • Voyager M3i:Specifies whether the packets sent by the DUT during execution of this Pipe Command are stored for processing by Firmware. Currently, there is no facility in the M3i Firmware to utilize stored packets, so the default and only acceptable value is 0 (zero), for no storage.

• send ERDY: Only applicable to the Device Emulation mode. If set, the Trainer will start the transfer for this Pipe Command by sending the ERDY TP to the host.

• transaction engine index: Optional index of the Transaction Engine to execute this command on. Current Exerciser supports two instances of the Transaction Engine, so the value can be 0 or 1. Starting transfers on different Transaction Engines can be used to achieve concurrent execution of the transfers in the same direction.

Pipe Commands

The following are the defined Pipe Command types (and the corresponding constants defined in PipeCommands.ginc):

Pipe Type

The following are the defined Pipe Type values (and the corresponding constants defined in PipeCommands.ginc):

Data Patterns

The following are the defined Data Patterns (and the corresponding constants defined in PipeCommands.ginc):

Loopback Feature for Voyage M3x, M310, and M310C (Added in Release 7.45)

Firmware keeps and internal buffer with size of 16 KB (16384 bytes). If a PIPE_CMD_READ_DATA command is executed with store data set to one, the data returned upon the command is stored in this internal buffer starting from its beginning. If a subsequent PIPE_CMD_WRITE_DATA command is executed with store data set to one, the data sent by the Exerciser upon this command will be taken from the internal buffer, starting from its beginning. This allows for “Data Loopback” type of functionality.

When store data is set to one, the total length of the transfer should not exceed 16384 bytes, and data pattern must be set to SB_USER_DEFINED.

Data Structure

The SendPipeCommand instruction uses a special PipeCommandData data structure (defined in PipeCommands.ginc) to specify relevant protocol fields for the command. The following is the definition of this data structure to be used inside the SendPipeCommand instruction:

Packet PipeCommandData
{
    #Dword 0
    Type      : 5 = 0
    RouteStr  : 20
    DevAddr   : 7

    #Dword 1
    SubType   : 4 = 0
    Rsvd1     : 2 = 0
    Rty       : 1 = 0
    Dir       : 1 = 0
    Endp      : 4    
    Rsvd2     : 3 = 0
    HstErr    : 1 = 0
    NumP      : 5 = 1
    SeqN      : 5    
    Rsvd3     : 6 = 0

    #Dword 2
    StreamID  : 16
    ForceSeq  : 1 = 0  # Special bit, to force the sequential
                       # processing of this Pipe Command
    BrkOnNRDY : 1 = 0  # Special bit, to force break on NRDY for
                       # this Pipe Command
    BrkImmed  : 1 = 0  # Special bit, to force break immediately
                       # for this Pipe Command
    Crc32Err  : 1 = 0  # Special bit, to force CRC32 error for 
                       # the first Data Packet for this Pipe Command
    Rsvd4     : 7 = 0
    PP        : 1 = 0
    Rsvd5     : 4 = 0

    #Dword 3
    CRC_16    : 16 = 0
    Hseq      : 3 = 0
    LcwRsvd   : 3 = 0
    HDepth    : 3    
    D1        : 1 = 0
    D2        : 1 = 0
    CRC_5     : 5 = 0

    # Payload
    Data : *
}

The following fields in this structure are relevant to the instruction and are reflected in the Pipe Command when it is executed:

DeviceAddr: Specifies the USB address of the device to be used for the command.

Endp, Dir: Specifies the Endpoint number and direction for the command.

NumP: Specifies the burst size for the data transfer.

Route String: Used if the traffic should be passing through a hub.

SeqN: Specifies the starting sequence number, if the asn parameter is set to zero.

StreamID: Specifies the Stream ID to be used for this data transfer. For endpoints supporting the USB3 Bulk Streaming protocol, when a non-zero Stream ID is used, special handling is applied for the Pipe Command (see below).

The following special considerations are applied while executing Pipe Commands:

Sequential versus Parallel Processing

Transaction Engine can send IN transactions in parallel with OUT transactions. If a Pipe Command is started in the IN direction and the next Pipe Command defines a transfer in the OUT direction, the second Pipe Command starts immediately. However, if the second command is in the IN direction, Transaction Engine will wait until the first command in the IN direction completes before starting.

Since Control transfers include transactions in both directions, an order of execution of Control Transfer stages should be guaranteed. For this purpose, there is an option to process a Pipe Command in a sequential manner, after all the previous commands in both directions have completed. This mode is automatically turned on for all Pipe Commands on the control endpoint (default endpoint zero).

To define sequential processing for a non-control endpoint, set the ForceSeq bit in the PipeCommandData structure to 1.

Bulk Streaming Operation

Transaction Engine includes support for the Bulk Streaming protocol. For this purpose, it holds a special Stream List for pending stream Pipe Commands. In Host Emulation mode, when a Pipe Command with a non-zero Stream ID is queued, it is not executed immediately, but instead placed on the Stream List. Later, when the device executes stream selection on a certain endpoint with a specific Stream ID (by sending the EDRY packet with this Stream ID), the corresponding Pipe Command is removed from the Stream List and scheduled for execution.

To support the transition to Idle state of Bulk Streaming state machines, special handling of the Prime Stream ID is added. A Break on NRDY option is added for Pipe Commands. When it is selected, command operation will stop upon receiving an NRDY TP from the device. This option is automatically turned on for transactions with Prime Stream ID. To turn it on for other Pipe Commands, set the BrkOnNRDY bit in the PipeCommandData structure to 1.

The Bulk Streaming facilities of Transaction Engine are used to implement UASP storage protocol scripting.

Examples of calling the SendPipeCommand instruction

# Host emulation
%include "Generation\Include\TransactionEngine\PipeCommands.ginc"
  
Main
{
    # Send Setup transaction to a device at address 1
    # specifying GET_DESCRIPTOR request for Device descriptor.
  SendPipeCommand( PIPE_CMD_WRITE_DATA, PIPE_TYPE_CONTROL, 8, 1,
          SB_USER_DEFINED, 1 )
    {
        PipeCommandData
        {
           DevAddr = 1
           Endp    = 0
           Data    = { 80 06 00 01 00 00 12 00 }
        }
    }

    # Perform a read of 80000 bytes on a Bulk IN endpoint number 3 
    # device address 2, with burst size of 4
  SendPipeCommand( PIPE_CMD_READ_DATA, PIPE_TYPE_BULK, 80000, 0, 
  0, 1 )
    {
        PipeCommandData
        {
           DevAddr = 2
           Endp    = 3
           Dir     = 1
           NumP    = 4
        }
    }

SendPipeCommand( PIPE_CMD_WRITE_DATA, PIPE_TYPE_CONTROL, 
                            8, 1, SB_USER_DEFINED, 1 )
    {
        PipeCommandData
        {
           DevAddr  = 0
           Endp     = 0
           Data     = $RequestPayload
           Crc32Err = 1  # Will send the data packet with CRC32 error
                           # and retry it properly when it is not 
                           # acknowledged by the device.
        }
     }
}

SetSequenceNumber Instruction

This instruction initializes automatic sequence number processing for an endpoint.
For Device Emulation, it is also used to enable the endpoint operation.

SetSequenceNumber( pipe type, device addr, endp num, data dir, sequence num, enable, transaction engine index )

SetSequenceNumber has the following instruction parameters:

• pipe type: Specifies the Pipe Type for the endpoint that is being set up. Possible values are described in SendPipeCommand section Pipe Type table.

• device addr: Specifies the USB address for the device.

• endp num: Specifies the endpoint number for the endpoint.

• data dir: Specifies the data transfer direction for the endpoint.

• sequence num: Specifies the initialization sequence number for the endpoint operation.

• enable: Only relevant for Device emulation. Used to enable or disable operation of the endpoint. When the endpoint is enabled, it will automatically send NRDY for the Host transactions directed to it, if there is no Pipe Command currently queued for it.

• transaction engine index: Optional index of the Transaction Engine to initialize this endpoint on (with the intention to run Pipe Commands on it later) . Current Exerciser supports two instances of the Transaction Engine, so the value can be 0 or 1. Starting transfers on different Transaction Engines can be used to achieve concurrent execution of the transfers in the same direction.

The Host enumeration script would usually call this instruction after setting an interface on the device to initialize operation for all the endpoints in that interface.

Examples of calling the SetSequenceNumber instruction

# Host emulation
%include "Generation\Include\TransactionEngine\PipeCommands.ginc"

Main
{
    # Initialize sequence number for Bulk IN endpoint 2
    # on device address 1
SetSequenceNumber( PIPE_TYPE_BULK, 1, 2, EP_DIR_IN, 0 )
}

Transaction Engine Scripts supplied with Voyager

A set of include files supplied with the Voyager software provides wrapper functions around Transaction Engine functionality for easy writing of scripts at the application level. These include files are in the \Generation\Include\TransactionEngine folder. The following files are provided:

PipeCommands.ginc: The main include file provides definitions for the SendPipeCommand instruction. Include it in all scripts utilizing Transaction Engine.

Host_DeviceRequests.ginc: Provides a function framework for implementing USBDevice Requests for Host emulation. Contains generic functions for setting up device requests, as well as specific functions for standard device requests.

Host_EndpointOperations.ginc: Provides a function framework for implementing Bulk transfers for Host emulation. Contains generic functions for reading from and writing to Bulk endpoints.

Host_UASP.ginc: Provides a function framework for implementing UASP protocol and SCSI commands for Host emulation. Includes generic functions for queuing no data, data-in, data-out, and bidirectional UASP operations, as well as a set of functions for queuing specific SCSI commands.

Device_UASP.ginc: Provides a function framework for implementing some aspects of UASP protocol and SCSI commands for Device emulation.

Use the include files described above to write scripts related to their areas of functionality. You can also use the files as examples for creating scripts.

Example Transaction Engine scripts are provided with Voyager software in the TransactionEngineScripts folder under the 3.2 sample files folder:

DeviceEnumeration.usb3g: Has an example of enumerating a device for Host emulation using Transaction Engine.

uasp_scsi_cmd1.usb3g

uasp_scsi_cmd2.usb3g: Has examples of setting up SCSI commands to a device for Host emulation.

Device_RespondToEnumeration.usb3g: Has an example of Device emulation using Transaction Engine features. Can be used on a second Trainer with the first Trainer running the DeviceEnumeration.usb3g Host emulation script.

Device_RespondToSCSI.usb3g: Has an example of Device emulation using Transaction Engine features. Can be used on a second Trainer with the first Trainer running the uasp_scsi_command1.usb3g Host emulation script, after enumeration using the DeviceEnumeration.usb3g and Device_RespondToEnumeration.usb3g scripts.