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. 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.
Each request starts with a 8 byte long Setup Packet which has the following format :
bmRequestType[1] bRequest[1] wValue[2] wIndex[2] wLength[2]
bmRequestType :
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
The bmRequestType field will determine the direction of the request,
type of request and designated recipient.
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.
The bRequest field determines the request being made.
Standard requests are common to all USB device's
Class requests are common to classes of drivers
And last of all are the vendor defined requests.
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.
The wLength is used the specify the number of bytes to
be transferred should there be a data phase.
The 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.
bmRequestType bRequest bRequest wValue wIndex wLength Data -------------------------------------------------------------------------------------------- 1000 0000b GET_STATUS (0x00) Zero Zero Two Device Status 0000 0000b CLEAR_FEATURE (0x01) Feature Zero Zero None Selector 0000 0000b SET_FEATURE (0x03) Feature Zero Zero None Selector -------------------------------------------------------------------------------------------- 0000 0000b SET_ADDRESS (0x05) Device Address Zero Zero None 1000 0000b GET_DESCRIPTOR (0x06) Descriptor Zero or Descriptor Descriptor Type & Index Lang ID Length 0000 0000b SET_DESCRIPTOR (0x07) Descriptor Zero or Descriptor Descriptor Type & Index Lang ID Length 1000 0000b GET_CONFIGURATION (0x08) Zero Zero 1 Conf Value 0000 0000b SET_CONFIGURATION (0x09) ConfValue Zero Zero None
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.
bmRequestType bRequest bRequest wValue wIndex wLength Data -------------------------------------------------------------------------------------------- 1000 0001b GET_STATUS (0x00) Zero Interface Two Interface Status 0000 0001b CLEAR_FEATURE (0x01) Feature Interface Zero None Selector 0000 0001b SET_FEATURE (0x03) Feature Interface Zero None Selector -------------------------------------------------------------------------------------------- 1000 0001b GET_INTERFACE (0x0A) Zero Interface One Alternate Interface 0000 0001b SET_INTERFACE (0x11) Alternative Interface Zero None Setting
Standard Endpoint Requests
--------------------------------------------------------------------------------------------
Standard Endpoint requests come in the four varieties listed below .
bmRequestType bRequest bRequest wValue wIndex wLength Data -------------------------------------------------------------------------------------------- 1000 0010b GET_STATUS (0x00) Zero Endpoint Two Endpoint Status 0000 0010b CLEAR_FEATURE (0x01) Feature Endpoint Zero None Selector 0000 0010b SET_FEATURE (0x03) Feature Endpoint Zero None Selector -------------------------------------------------------------------------------------------- 1000 0010b SYNCH_FRAME (0x12) Zero Endpoint Two FrameNumber
The Get Status request
--------------------------------------------------------------------------------------------
The Get Status request directed at the device will
return two bytes during the data stage with the following format
D0 : Self Powered : 0 - bus powered, 1 - self powered
D1 : Remote Wakeup : SetFeature and ClearFeature
: feature selector of DEVICE_REMOTE_WAKEUP (0x01)
D15-D2 : Reserved
The Get Status request directed at the interface will
return two bytes of 0x00, 0x00. (Both bytes are reserved for future use)
The Get Status request directed at the endpoint will
returns two bytes indicating the status (Halted/Stalled) of a endpoint
D0 : Halted/Stalled
D15-D1 : Reserved
The Clear Feature and Set Feature requests
--------------------------------------------------------------------------------------------
The Clear Feature and Set Feature requests directed at the device can
be used to set boolean features, 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.
The Clear Feature and Set Feature requests directed at the interface can
be used to set boolean features,
the current USB Specification Revision 2 specifies no interface features.
The Clear Feature and Set Feature requests directed at the endpoint can
be used to set boolean features, the only two feature selectors available are
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.
The Set Address requests : Device Only
--------------------------------------------------------------------------------------------
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.
The Set Descriptor/Get Descriptor requests : Device Only
--------------------------------------------------------------------------------------------
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.
Endpoint Descriptors cannot be accessed directly by a GetDescriptor/SetDescriptor Request.
Interface Descriptors cannot be accessed directly by a GetDescriptor/SetDescriptor Request.
String Descriptors include a Language ID in wIndex to allow for multiple language support.
The Get Configuration/Set Configuration requests : Device Only
--------------------------------------------------------------------------------------------
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.
The Get Interface and Set Interface requests : Interface Only
--------------------------------------------------------------------------------------------
Get Interface and Set Interface set the Alternative Interface setting
which is described in more detail under the Interface Descriptor.
The Synch Frame request : Endpoint Only
--------------------------------------------------------------------------------------------
A Synch Frame request is used to report an endpoint synchronisation frame.
