The Setup Packet

    Every USB device must respond to setup packets on the default pipe. The setup packets are used for detection and configuration of the device and carry out common functions such as setting the USB device’s address, requesting a device descriptor or checking the status of a endpoint.

    A USB compliant Host expects all requests to be processed within a maximum period of 5 seconds. It also specifies stricter timing for specific requests :

    • Standard Device requests without a data stage must be completed in 50ms.

    • Standard Device requests with a data stage must start to return data 500ms after the request.

      • Each data packet must be sent within 500ms of the successful transmission of the previous packet.
      • The status stage must complete within 50ms after the transmission of the last data packet.

    • The SetAddress command (which contains a data phase) must process the command and return status within 50ms. The device then has 2ms to change address before the next request is sent.

    These timeout periods are quite acceptable for even the slowest of devices, but can be a restriction during debugging. 50mS doesn't provide for many debugging characters to be sent at 9600bps on an asynchronous serial port or for a In Circuit Debugger/Emulator to single step or to break execution to examine the internal Registers. As a result, USB requires some different debugging methods to that of other microcontroller projects.

      Casually reading through the XP DDK, one may note the Host Controller Driver now has a USBUSER_OP_SEND_ONE_PACKET command which is commented to read "This API is used to implement the 'single step' USB transaction development tool." While such a tool has not been released yet, we can only hope to see one soon.

    Each request starts with a 8 byte long Setup Packet which has the following format,

    0 bmRequestType 1 Bit-Map D7 Data Phase Transfer Direction
    0 = Host to Device
    1 = Device to Host
    D6..5 Type
    0 = Standard
    1 = Class
    2 = Vendor
    3 = Reserved
    D4..0 Recipient
    0 = Device
    1 = Interface
    2 = Endpoint
    3 = Other
    4..31 = Reserved
    1 bRequest 1 Value

    Request

    2 wValue 2 Value

    Value

    4 wIndex 2 Index or Offset

    Index

    6 wLength 2 Count

    Number of bytes to transfer if there is a data phase

    The bmRequestType field will determine the direction of the request, type of request and designated recipient. The bRequest field determines the request being made. The bmRequestType is normally parsed and execution is branched to a number of handlers such as a Standard Device request handler, a Standard Interface request handler, a Standard Endpoint request handler, a Class Device request handler etc. How you parse the setup packet is entirely up to your preference. Others may choose to parse the bRequest first and then determine the type and recipient based on each request.

    Standard requests are common to all USB device's and are detailed in the next coming pages. Class requests are common to classes of drivers. For example, all device conforming to the HID class will have a common set of class specific requests. These will differ to a device conforming to the communications class and differ again to that of a device conforming to the mass storage class.

    And last of all are the vendor defined requests. These are requests which you as the USB device designer can assign. These are normally different from device to device, but this is all up to your implementation and imagination.

    A common request can be directed to different recipients and based on the recipient perform different functions. A GetStatus Standard request for example, can be directed at the device, interface or endpoint. When directed to a device it returns flags indicating the status of remote wakeup and if the device is self powered. However if the same request is directed at the interface it always returns zero, or should it be directed at an endpoint will return the halt flag for the endpoint.

    The wValue and wIndex fields allow parameters to be passed with the request. wLength is used the specify the number of bytes to be transferred should there be a data phase.

Standard Requests

    Section 9.4 of the USB specification details the "Standard Device" requests required to be implemented for every USB device. The standard provides a single table grouping items by request. Considering most firmware will parse the setup packet by recipient we will opt to break up the requests based by recipient for easier examination and implementation.

Standard Device Requests

    There are currently eight Standard Device requests, all of which are detailed in the table below.

    1000 0000b GET_STATUS (0x00) Zero Zero Two Device Status
    0000 0000b CLEAR_FEATURE (0x01) Feature Selector Zero Zero None
    0000 0000b SET_FEATURE (0x03) Feature Selector Zero Zero None
    0000 0000b SET_ADDRESS (0x05) Device Address Zero Zero None
    1000 0000b GET_DESCRIPTOR (0x06) Descriptor Type & Index Zero or Language ID Descriptor Length Descriptor
    0000 0000b SET_DESCRIPTOR (0x07) Descriptor Type & Index Zero or Language ID Descriptor Length Descriptor
    1000 0000b GET_CONFIGURATION (0x08) Zero Zero 1 Configuration Value
    0000 0000b SET_CONFIGURATION (0x09) Configuration Value Zero Zero None

    • The Get Status request directed at the device will return two bytes during the data stage with the following format,

      Reserved Remote Wakeup Self Powered

      If D0 is set, then this indicates the device is self powered. If clear, the device is bus powered. If D1 is set, the device has remote wakeup enabled and can wake the host up during suspend. The remote wakeup bit can be by the SetFeature and ClearFeature requests with a feature selector of DEVICE_REMOTE_WAKEUP (0x01)

    • Clear Feature and Set Feature requests can be used to set boolean features. When the designated recipient is the device, the only two feature selectors available are DEVICE_REMOTE_WAKEUP and TEST_MODE. Test mode allows the device to exhibit various conditions. These are further documented in the USB Specification Revision 2.0.

    • Set Address is used during enumeration to assign a unique address to the USB device. The address is specified in wValue and can only be a maximum of 127. This request is unique in that the device does not set its address until after the completion of the status stage. (See Control Transfers.) All other requests must complete before the status stage.

    • Set Descriptor/Get Descriptor is used to return the specified descriptor in wValue. A request for the configuration descriptor will return the device descriptor and all interface and endpoint descriptors in the one request.

    • Get Configuration/Set Configuration is used to request or set the current device configuration. In the case of a Get Configuration request, a byte will be returned during the data stage indicating the devices status. A zero value means the device is not configured and a non-zero value indicates the device is configured. Set Configuration is used to enable a device. It should contain the value of bConfigurationValue of the desired configuration descriptor in the lower byte of wValue to select which configuration to enable.

Standard Interface Requests

    The specification currently defines five Standard Interface requests which are detailed in the table below. Interestingly enough, only two requests do anything intelligible.

1000 0001b GET_STATUS (0x00) Zero Interface Two Interface Status
0000 0001b CLEAR_FEATURE (0x01) Feature Selector Interface Zero None
0000 0001b SET_FEATURE (0x03) Feature Selector Interface Zero None
1000 0001b GET_INTERFACE (0x0A) Zero Interface One Alternate Interface
0000 0001b SET_INTERFACE (0x11) Alternative Setting Interface Zero None

  • wIndex is normally used to specify the referring interface for requests directed at the interface. Its format is shown below.

    Reserved Interface Number

  • Get Status is used to return the status of the interface. Such a request to the interface should return two bytes of 0x00, 0x00. (Both bytes are reserved for future use)

  • Clear Feature and Set Feature requests can be used to set boolean features. When the designated recipient is the interface, the current USB Specification Revision 2 specifies no interface features.

  • Get Interface and Set Interface set the Alternative Interface setting which is described in more detail under the Interface Descriptor.

Standard Endpoint Requests

    Standard Endpoint requests come in the four varieties listed below.

    1000 0010b GET_STATUS (0x00) Zero Endpoint Two Endpoint Status
    0000 0010b CLEAR_FEATURE (0x01) Feature Selector Endpoint Zero None
    0000 0010b SET_FEATURE (0x03) Feature Selector Endpoint Zero None
    1000 0010b SYNCH_FRAME (0x12) Zero Endpoint Two FrameNumber

    • The wIndex field is normally used to specify the referring endpoint and direction for requests directed to an endpoint. Its format is shown below.

      Reserved Dir Reserved Endpoint Number

    • Get Status returns two bytes indicating the status (Halted/Stalled) of a endpoint. The format of the two bytes returned is illustrated below.

      Reserved Halt

    • Clear Feature and Set Feature are used to set Endpoint Features. The standard currently defines one endpoint feature selector, ENDPOINT_HALT (0x00) which allows the host to stall and clear an endpoint. Only endpoints other than the default endpoint are recommended to have this functionality.

    • A Synch Frame request is used to report an endpoint synchronisation frame.