Packet structure

+----------------------------------------+
|            Version of header           |
|                (2 Octets)              |
+----------------------------------------+
|             Length of header           |
|                (1 Octet)               |
+----------------------------------------+
|               Request type             |
|                (1 Octet)               |
+----------------------------------------+
|  Amount of data requested/transferred  |
|                (4 Octets)              |
+----------------------------------------+
|              Returned status           |
|                (4 Octets)              |
+----------------------------------------+
| Number of isochronous frames following |
|                (4 Octets)              |
+----------------------------------------+
|                Unique ID               |
|                (4 Octets)              |
+----------------------------------------+
|                locationID              |
|                (4 Octets)              |
+----------------------------------------+
|              Endpoint speed            |
|                (1 Octet)               |
+----------------------------------------+
|              Device address            |
|                (1 Octet)               |
+----------------------------------------+
|      Endpoint address and direction    |
|                (1 Octet)               |
+----------------------------------------+
|              Endpoint type             |
|                (1 Octet)               |
+----------------------------------------+
|                 Payload                |
.                                        .
.                                        .
.                                        .

Description

All multi-byte fields are little-endian.

The version number field is a 2-octet value with the upper 8 bits giving the major version number, the next 4 bits giving the minor version number, and the next 4 bits giving the sub-minor version number. The current version is 1.0.0, so the value is 0x0100.

The length field indicates how long the header is; this value includes the length of the length field itself. It should be at least 32; if it's larger, there is additional data in the header following the endpoint type.

The request type field contains a value that is one of:

• 0, if this packet indicates a submitted request;
• 1, if this packet indicates a completed request.

The "amount of data requested/transferred" field indicates how much data was requested or transferred by the request.

The returned status field contains a status value for the request. A status value has a system identifier in the upper 6 bits, a subsystem identifier in the next 12 bits down, and a per-subsystem error code in the lower 14 bits. The system identifier is usually 0, for "kernel"; if the system identifier is 0 and the subsystem identifier is 3, for "Unix", the code is a Darwin errno value.

For an isochronous endpoint, the "number of isochronous frames following" field indicates the number of isochronous frames in the packet. For other endpoints, it is 0.

The unique ID field contains an identifier for the operation; this will be the same for all packets for a request, so that it can be used to match submitted and completed requests.

The locationID field contains a value that describes the bus topology to which the device is connected. The upper 8 bits contain the bus number; all subsequent 4-bit fields correspond to the port numbers through which the device is connected, so that, for example, a device on bus 26 that is connected to port 1 of the hub that is connected to root port 1 on the host controller would have a locationID of 0x1a110000. If there are fewer than 6 ports in the route, the unused port number fields are zero.

The endpoint speed field contains a value that is one of:

• 0, for Low Speed;
• 1, for Full Speed;
• 2, for High Speed;
• 3, for SuperSpeed;
• 4, for SuperSpeedPlus.

The device address field contains a device address in the lower 7 bits; the uppermost bit is clear.

The endpoint address and direction field contains an endpoint number in the lower 4 bits and a direction indicator in the uppermost bit; if the uppermost bit is 0, the endpoint is an OUT endpoint, and if the uppermost bit is 1, the endpoint is an IN endpoint.

The endpoint type field contains a value that is one of:

• 0, for control;
• 1, for isochronous;
• 2, for bulk;
• 3, for interrupt.

For non-isochronous endpoints:

• If the packet indicates a completed request, the payload is the data transferred.
• If the packet indicates a submitted request, then if the endpoint is is the Default Control Pipe, the payload is the setup data as specified in section 9.3 "USB Device Requests" of the USB 2.0 specification, otherwise there is no payload.

For isochronous endpoints:

• If the packet indicates a completed request, the payload is a sequence of "number of isochronous frames following" isochronous frames. Each isochronous frame begins with 0–3 bytes of padding to put the data following it on a 4-byte boundary. After that is a header of the form:

  +----------------------------------------+
  |             Length of header           |
  |                (4 Octets)              |
  +----------------------------------------+
  |               Frame length             |
  |                (4 Octets)              |
  +----------------------------------------+
  |               Frame status             |
  |                (4 Octets)              |
  +----------------------------------------+
  |               Frame number             |
  |                (8 Octets)              |
  +----------------------------------------+
  |                Time stamp              |
  |                (8 Octets)              |
  +----------------------------------------+
  

  The length field indicates how long the header is; this value includes the length of the length field itself. It should be at least 28; if it's larger, there is additional data in the header following the time in which the frame completed.

  The frame length field indicates how many bytes of data are in the frame.

  The frame status field contains a status value for the frame. It is in the same format as the returned status field in the packet header.

  The frame number field is the frame number, from the Start-of-Frame packet, as specified by section 8.3.3 "Frame Number Field" of the USB 2.0 specification, on which this frame was scheduled/executed by the controller.

  The time stamp field is time at which the frame completed. It is a Mach absolute time, so it is a time in platform-dependent units; no indication of the units on the platform on which the capture was performed is available.

  Following the header is the data for the frame; the frame length field indicates how many bytes of data there are for that frame.

• If the packet indicates a submitted request, the payload is a sequence of "number of isochronous frames following" isochronous frame headers, with the frame length set to the number of bytes to be transferred, the frame status field set to 0xe0000001, and without any data following the header.