Chapter 4 116 /KETQUQHV15&GUETKRVQTU Microsoft OS descriptors enable storing Windows-specific information. Placing the information in descriptors means the information is available on attach- ment instead of requiring users to provide the information on separate media. The Microsoft OS string descriptor has an index of EEh and contains an embedded signature. Windows XP SP1 and later request this string descriptor from a device on first attachment. A device that doesn’t support the descriptor should return STALL. On retrieving a Microsoft OS string descriptor, Win- dows may request one or more Microsoft OS feature descriptors. The extended compat ID feature descriptor contains Microsoft-defined IDs that can help Windows locate a driver for device functions that don’t have Windows-pro- vided drivers. The extended properties feature descriptor can provide text, icons, and other device-specific properties. 7RFCVKPI&GUETKRVQTUVQ75$ To update descriptors for a USB 1.x device to USB 2.0, all except some devices that have isochronous endpoints require just one change: in the device descrip- tor, bcdUSB must be 0200h or greater. As Chapter 3 explained, a USB 2.0 device’s default interface(s) must request no isochronous bandwidth, so an interface that wants to do isochronous transfers must have at least one alternate interface setting, and the alternate interface descriptor will have at least one subordinate endpoint descriptor. Table 4-14: The device capability descriptor can provide information that is specific to a technology or another aspect of a device or its function. 1HHUGV FGEKOCN (KGNF 5K\G D[VGU &GUETKRVKQP 0 bLength 1 Descriptor length in bytes (varies). 1 bDescriptorType 1 DEVICE CAPABILITY (10h) 2 bDevCapabilityType 1 01h = Wireless USB 02h = USB 2.0 EXTENSION 03h = SUPERSPEED_USB 04h = CONTAINER ID 00h, 05h–FFH (reserved) 3 Capability-Dependent varies Capability-specific data and format. 117 %QPVTQN6TCPUHGTU 5VTWEVWTGF4GSWGUVUHQT %TKVKECN&CVC Of USB’s four transfer types, control transfers have the most complex structure. They’re also the only transfer type with functions defined by the USB specifica- tion. This chapter looks in greater detail at control transfers and the standard requests defined in the specification. 'NGOGPVUQHC%QPVTQN6TCPUHGT Control transfers enable the host and a device to exchange information about the device’s capabilities and other class-specific or vendor-specific information. As Chapter 3 explained, a control transfer consists of a Setup stage, a Data stage (optional for some transfers), and a Status stage. Each stage consists of one or more transactions. Chapter 5 118 The descriptions below apply to USB 2.0 transfers. SuperSpeed transfers exchange the same information but use USB 3.0’s packet structures and proto- cols as described in Chapter 3. 5GVWR5VCIG The Setup stage consists of a Setup transaction, which identifies the transfer as a control transfer and transmits the request and other information that the device needs to complete the request. Devices must return ACK for every Setup transaction received without error. An endpoint that is in the middle of another control transfer must abandon that transfer and acknowledge the new Setup transaction. 6QMGP2CEMGV Purpose: identifies the receiver and identifies the transaction as a Setup transac- tion. Sent by: the host. PID: SETUP Additional contents: the device and endpoint addresses. &CVC2CEMGV Purpose: transmits the request and related information. Sent by: the host. PID: DATA0 Additional contents: eight bytes in five fields: bmRequestType specifies the direction of data flow, the type of request, and the recipient. Bit 7 (Direction) names the direction of data flow for data in the Data stage. Host to device (OUT) or no Data stage is zero; device to host (IN) is 1. Bits 6 5 (Request Type) specify whether the request is one of USB’s standard requests (00), a request defined for a specific USB class (01), or a request defined by a vendor-specific driver for use with a particular product or products (10). Bits 4 0 (Recipient) define whether the request is directed to the device (00000) or to a specific interface (00001), endpoint (00010), or other element (00011) in the device. Control Transfers: Structured Requests for Critical Data 119 bRequest identifies the request. wValue can pass request-specific information to the device. Each request can define the meaning of these two bytes in its own way. For example, in a Set Address request, wValue contains the device’s address. wIndex can pass request-specific information to the device. A typical use is to pass an index or offset such as an interface or endpoint number, but each request can define the meaning of these two bytes in any way. When passing an endpoint index, bits 3 0 specify the endpoint number, and bit 7 = 0 for a Con- trol or OUT endpoint or 1 for an IN endpoint. When passing an interface index, bits 7 0 are the interface number. All undefined bits are zero. wLength is two bytes that contain the number of data bytes in the Data stage that follows. For a host-to-device transfer, wLength is the exact number of bytes the host intends to transfer. For a device-to-host transfer, wLength is a maxi- mum, and the device may return this many bytes or fewer. If the field is zero, the transfer has no Data stage. *CPFUJCMG2CEMGV Purpose: transmits the device’s acknowledgement. Sent by: the device. PID: ACK. Additional contents: none. The handshake packet consists of the PID alone. Comments: If the device detects an error in the received Setup or Data packet, the device returns no handshake. The device’s hardware typically handles the error checking and sending of the ACK with no firmware support needed. &CVC5VCIG The Data stage, when present, consists of one or more IN or OUT transac- tions. A Data stage with IN transactions sends data to the host. An example is the Get Descriptor request, where the device sends a requested descriptor to the host. A Data stage with OUT transactions sends data to the device. An example is the HID-class request Set Report, where the host sends a report to a device. If wLength in the Setup transaction equals 0000h, the transfer has no Data stage. For example, in the Set Configuration request, the host passes a configuration value to the device in the wValue field of the Setup stage’s data packet, so the transaction has no need for a Data stage. Chapter 5 120 If all of the data can’t fit in one packet, the stage uses multiple transactions. In the device descriptor, bMaxPacketSize0 specifies the maximum number of data bytes per packet. The transactions in the Data stage are all in the same direc- tion. When the Data stage is present but there is no data to transfer, the data packet is a ZLP. The host uses split transactions in the Data stage when the device is low or full speed and a hub between the device and host connects upstream at high speed. The host may use the PING protocol when the device is high speed, the Data stage uses OUT transactions, and the stage has more than one data transaction. Each IN or OUT transaction in the Data stage contains token, data, and hand- shake packets. 6QMGP2CEMGV Purpose: identifies the receiver and identifies the transaction as an IN or OUT transaction. Sent by: the host. PID: If the request requires the device to send data to the host, the PID is IN. If the request requires the host to send data to the device, the PID is OUT. Additional contents: the device and endpoint addresses. &CVC2CEMGV Purpose: transfers all or a portion of the data specified in the wLength field of the Setup transaction’s data packet. Sent by: the device if the token packet’s PID is IN or the host if the token packet’s PID is OUT. PID: The first packet is DATA1. Any additional packets in the Data stage alter- nate DATA0/DATA1. Additional contents: The host sends data or a ZLP. A device may send data, a ZLP, STALL (unsupported request or halted endpoint), or NAK. *CPFUJCMG2CEMGV Purpose: the data packet’s receiver returns status information. Sent by: the receiver of the Data stage’s data packet. If the token packet’s PID is IN, the host sends the handshake packet. If the token packet’s PID is OUT, the device sends the handshake packet. Control Transfers: Structured Requests for Critical Data 121 PID: A device may return ACK (data received without error), NAK (endpoint busy), or STALL (unsupported request or halted endpoint). A high-speed device that is receiving multiple data packets may return NYET to indicate that the current transaction’s data was accepted but the endpoint isn’t yet ready for another data packet. A host can return only ACK. Additional contents: none. The handshake packet consists of the PID alone. Comments: If the receiver detected an error in the token or data packet, the receiver returns no handshake packet. 5VCVWU5VCIG The Status stage completes the transfer. In some cases (such as after receiving the first packet of a device descriptor during enumeration), the host may begin the Status stage before the Data stage has completed, and the device must detect the token packet of the Status stage, abandon the Data stage, and complete the Status stage. 6QMGP2CEMGV Purpose: identifies the receiver and indicates the direction of the Status stage’s data packet. Sent by: the host. PID: the opposite of the direction of the previous transaction’s data packet. If the Data stage’s PID was OUT or if there was no Data stage, the Status stage’s PID is IN. If the Data stage’s PID was IN, the Status stage’s PID is OUT. Additional contents: the device and endpoint addresses. &CVC2CEMGV Purpose: enables the receiver of the Data stage’s data to indicate the status of the transfer. Sent by: the device if the Status stage’s token packet’s PID is IN or the host if the Status stage’s token packet’s PID is OUT. PID: DATA1 Additional contents: The host sends a ZLP. A device may send a ZLP (suc- cess), NAK (busy), or STALL (unsupported request or halted endpoint). Chapter 5 122 Comments: For most requests, a ZLP from the device indicates that the device has performed the requested action (if any). An exception is Set Address, where the device takes the requested action after the Status stage has completed. *CPFUJCMG2CEMGV Purpose: The sender of the Data stage’s data indicates the status of the transfer. Sent by: the receiver of the Status stage’s data packet. If the Status stage’s token packet’s PID is IN, the host sends the handshake packet; if the token packet’s PID is OUT, the device sends the data packet. PID: A device may return ACK (success), NAK (busy), or STALL (unsup- ported request or halted endpoint). The host returns ACK in response to a data packet received without error. Additional contents: none. The handshake packet consists of the PID alone. Comments: The Status stage’s handshake packet is the final transmission in the transfer. If the receiver detected an error in the token or data packet, the receiver returns no handshake packet. For any request that’s expected to take many milliseconds to carry out, the pro- tocol should define an alternate way to determine when the request has com- pleted. Doing so ensures that the host doesn’t waste a lot of time asking for an acknowledgement that will take a long time to appear. An example is the Set Port Feature(PORT_RESET) request sent to a hub. The reset signal lasts at least 10 ms. Rather than making the host wait this long for the device to com- plete the request, the hub acknowledges receiving the request when the hub first places the port in the reset state. When the reset is complete, the hub sets a bit that the host can retrieve at its leisure via a Get Port Status request. *CPFNKPI'TTQTU A device might receive a request that firmware doesn’t support. Or a device may be unable to respond because the endpoint is in the Halt condition, the firm- ware has crashed, or the device is no longer attached to the bus. A host may also decide to end a transfer early for any reason. An example of an unsupported request is one that uses a request code that the device’s firmware doesn’t know how to respond to. Or a device may support the request but other information in the Setup stage doesn’t match what the device expects or supports. On these occasions, a Request Error condition exists and the device notifies the host by sending STALL. Devices must respond to the Control Transfers: Structured Requests for Critical Data 123 Setup transaction with an ACK, so the STALL transmits in the Data or Status stage. When possible, the device should return STALL in the Data stage. On failing to get a response or on detecting an error in received data or a Halt condition at the endpoint, the host abandons the transfer. The host then tries to re-establish communications with the endpoint by sending the token packet for a new Setup transaction. If a new token packet doesn’t cause the device to recover, the host requests the device’s hub to reset the device’s port. The host may also end a transfer early by beginning the Status stage before completing all of the Data stage’s transactions. In this case, the device must respond to the Status stage in the same way as if all of the data had transferred. &GXKEG(KTOYCTG USB 2.0 device firmware typically performs the steps below to support control transfers. The implementation details vary with the device architecture and pro- gramming language. %QPVTQN9TKVG4GSWGUVUYKVJC&CVC5VCIG To complete a control write request with a Data stage, the device must detect the request in the Setup stage, accept the data in the Data stage, and send a ZLP in the Status stage. 1. Device hardware detects a received Setup packet, stores the contents of the transaction’s data packet, returns ACK, and triggers an interrupt. 2. On detecting the interrupt, the device decodes the request and ensures that endpoint zero is ready to accept data that arrives following an OUT token packet. The endpoint must also ACK a new Setup packet if the host decides to abandon the transfer and should return a ZLP in response to an IN token packet, which indicates that the host is ending the transfer early. 3. The Data stage begins when the host sends an OUT token packet to end- point zero. The endpoint stores the received data and returns ACK in the hand- shake packet. The hardware triggers an interrupt. 4. On detecting the interrupt, the device processes the received data as needed. 5. If the Data stage has additional data packets, steps 3 and 4 repeat for addi- tional OUT transactions up to the wLength value in the Setup transaction. 6. To complete the transfer, the host sends an IN token packet, the device responds with a ZLP, and the host returns ACK. Chapter 5 124 %QPVTQN9TKVG4GSWGUVUYKVJ0Q&CVC5VCIG To complete a control write request without a Data stage, the device must detect the request in the Setup stage and send a ZLP in the Status stage. 1. The hardware detects a Setup packet, stores the contents of the transaction’s data packet, returns ACK, and triggers an interrupt. 2. On detecting the interrupt, the device decodes the request, does what is needed to perform the requested action, and arms endpoint zero to respond to an IN token packet. The endpoint must also ACK a new Setup packet if the host decides to abandon the transfer. 3. To complete the transfer, the host sends an IN token packet, the device responds with a ZLP, and the host returns ACK. %QPVTQN4GCF4GSWGUVU To complete a control read request, the device must detect the request in the Setup stage, send data in the Data stage, and acknowledge a received handshake in the Status stage. 1. The hardware detects a Setup packet, stores the contents of the transaction’s data packet, returns ACK, and triggers an interrupt. 2. On detecting the interrupt, the device decodes the request and arms end- point zero to send the requested data on receiving an IN token packet. The endpoint must also ACK a new Setup packet if the host decides to abandon the transfer and must return a ZLP in response to an OUT packet if the host begins the Status stage early. 3. The Data stage begins when the host sends an IN token packet to endpoint zero. The device hardware sends the data, detects the received ACK from the host, and triggers an interrupt. 4. On detecting the interrupt, a device that has more data to send arms the end- point to send the data on receiving another IN token packet, and steps 3 and 4 repeat. 5. On receiving an OUT token packet followed by a ZLP, the endpoint returns ACK to complete the transfer. 5VCPFCTF4GSWGUVU Table 5-1 summarizes the requests defined in the USB 2.0 and USB 3.0 specifi- cations. Control Transfers: Structured Requests for Critical Data 125 Table 5-1: The USB specification defines these requests for control transfers. 4GSWGUV%QFG 4GSWGUV0COG 6CTIGV Y8CNWG Y+PFGZ &CVC5VCIG &CVC 5QWTEG Y.GPIVJ %QPVGPVU 00h Get Status device, interface, or endpoint 0000h 0000h (device), interface, or endpoint device 0002h; status 01h Clear Feature device, interface, or endpoint feature 0000h (device), interface, or endpoint none 0000h 03h Set Feature device, interface, or endpoint feature 0000h (device), interface, or endpoint none 0000h 05h Set Address device device address 0000h none 0000h 06h Get Descriptor device descriptor type and index 0000h or language ID device descriptor length (bytes); descriptor 07h Set Descriptor device descriptor type and index 0000h or language ID host descriptor length (bytes); descriptor 08h Get Configuration device 0000h 0000h device 0001h; configuration 09h Set Configuration device configuration 0000h none 0000h 0Ah Get Interface interface 0000h interface device 0001h; alternate setting 0Bh Set Interface interface interface interface none 0000h 0Ch Synch Frame endpoint 0000h endpoint device 0002h; frame number 30h Set SEL device 0000h 0000h host 0006h; exit latency values 31h Set Isochronous Delay device Delay in ns 0000h none 0000h . properties. 7RFCVKPI&GUETKRVQTUVQ75$ To update descriptors for a USB 1.x device to USB 2.0, all except some devices that have isochronous endpoints require just one change: in the device descrip- tor, bcdUSB must be 0200h or greater bDescriptorType 1 DEVICE CAPABILITY (10h) 2 bDevCapabilityType 1 01h = Wireless USB 02h = USB 2.0 EXTENSION 03h = SUPERSPEED _USB 04h = CONTAINER ID 00h, 05h–FFH (reserved) 3 Capability-Dependent varies. followed by a ZLP, the endpoint returns ACK to complete the transfer. 5VCPFCTF4GSWGUVU Table 5-1 summarizes the requests defined in the USB 2.0 and USB 3.0 specifi- cations. Control Transfers: