9.2 USB Control Transfers

9.2 USB Control Transfers
	Chapter 9. USB Transfers

9.2.1 USB Control Transfers Overview

9.2.1.1 Control Data Exchange

USB control exchange is used to determine device identification and configuration requirements and to configure a device, and can also be used for other device-specific purposes, including control of other pipes on the device.
Control exchange takes place via a control pipe, mainly the default Pipe 0, which always exists. The control transfer consists of a setup stage (in which a setup packet is sent from the host to the device), an optional data stage and a status stage.

9.2.1.2 More About the Control Transfer

The control transaction always begins with a setup stage. The setup stage is followed by zero or more control data transactions (data stage) that carry the specific information for the requested operation, and finally a status transaction completes the control transfer by returning the status to the host.

During the setup stage, an 8-byte setup packet is used to transmit information to the control endpoint of the device. The setup packet's format is defined by the USB specification.

A control transfer can be a read transaction or a write transaction. In a read transaction the setup packet indicates the characteristics and amount of data to be read from the device. In a write transaction the setup packet contains the command sent (written) to the device and the number of control data bytes that will be sent to the device in the data stage.

Refer to Figure 9.2 (taken from the USB specification) for a sequence of read and write transactions.
'(in)' indicates data flow from the device to the host.
'(out)' indicates data flow from the host to the device.

Figure 9.2 USB Read and Write

9.2.1.3 The Setup Packet

The setup packets (combined with the control data stage and the status stage) are used to configure and send commands to the device. Chapter 9 of the USB specification defines standard device requests. USB requests such as these are sent from the host to the device, using setup packets. The USB device is required to respond properly to these requests. In addition, each vendor may define device-specific setup packets to perform device-specific operations. The standard setup packets (standard USB device requests) are detailed below. The vendor's device-specific setup packets are detailed in the vendor's data book for each USB device.

9.2.1.4 USB Setup Packet Format

The table below shows the format of the USB setup packet. For more information, please refer to the USB specification at http://www.usb.org.

Byte	Field	Description
0	bmRequest Type	Bit 7: Request direction (0=Host to device – Out, 1=Device to host – In). Bits 5-6: Request type (0=standard, 1=class, 2=vendor, 3=reserved). Bits 0-4: Recipient (0=device, 1=interface, 2=endpoint,3=other).
1	bRequest	The actual request (see the Standard Device Request Codes table [9.2.1.5].
2	wValueL	A word-size value that varies according to the request. For example, in the `CLEAR_FEATURE` request the value is used to select the feature, in the `GET_DESCRIPTOR` request the value indicates the descriptor type and in the `SET_ADDRESS` request the value contains the device address.
3	wValueH	The upper byte of the `Value` word.
4	wIndexL	A word-size value that varies according to the request. The index is generally used to specify an endpoint or an interface.
5	wIndexH	The upper byte of the `Index` word.
6	wLengthL	A word-size value that indicates the number of bytes to be transferred if there is a data stage.
7	wLengthH	The upper byte of the `Length` word.

9.2.1.5 Standard Device Request Codes

The table below shows the standard device request codes.

bRequest	Value
GET_STATUS	0
CLEAR_FEATURE	1
Reserved for future use	2
SET_FEATURE	3
Reserved for future use	4
SET_ADDRESS	5
GET_DESCRIPTOR	6
SET_DESCRIPTOR	7
GET_CONFIGURATION	8
SET_CONFIGURATION	9
GET_INTERFACE	10
SET_INTERFACE	11
SYNCH_FRAME	12

9.2.1.6 Setup Packet Example

This example of a standard USB device request illustrates the setup packet format and its fields. The setup packet is in Hex format.

The following setup packet is for a control read transaction that retrieves the device descriptor from the USB device. The device descriptor includes information such as USB standard revision, vendor ID and product ID.

GET_DESCRIPTOR (Device) Setup Packet

Setup packet meaning:

Byte	Field	Value	Description
0	BmRequest Type	80	8h=1000b bit 7=1 -> direction of data is from device to host. 0h=0000b bits 0..1=00 -> the recipient is the device.
1	bRequest	06	The Request is GET_DESCRIPTOR.
2	wValueL	00
3	wValueH	01	The descriptor type is device (values defined in USB spec).
4	wIndexL	00	The index is not relevant in this setup packet since there is only one device descriptor.
5	wIndexH	00
6	wLengthL	12	Length of the data to be retrieved: 18(12h) bytes (this is the length of the device descriptor).
7	wLengthH	00

In response, the device sends the device descriptor data. A device descriptor of Cypress EZ-USB Integrated Circuit is provided as an example:

Byte No.	0	1	2	3	4	5	6	7	8	9	10
Content	12	01	00	01	ff	ff	ff	40	47	05	80

Byte No.	11	12	13	14	15	16	17
Content	00	01	00	00	00	00	01

As defined in the USB specification, byte 0 indicates the length of the descriptor, bytes 2-3 contain the USB specification release number, byte 7 is the maximum packet size for endpoint 00, bytes 8-9 are the Vendor ID, bytes 10-11 are the Product ID, etc.

9.2.2 Performing Control Transfers with WinDriver

WinDriver allows you to easily send and receive control transfers on Pipe00, while using DriverWizard to test your device. You can either use the API generated by DriverWizard [5] for your hardware, or directly call the WinDriver WDU_Transfer() [B.4.8.1] function from within your application.

9.2.2.1 Control Transfers with DriverWizard

Choose Pipe 0x0 and click the Read / Write button.
You can either enter a custom setup packet, or use a standard USB request.
- For a custom request: enter the required setup packet fields. For a write transaction that includes a data stage, enter the data in the Write to pipe data (Hex) field. Click Read From Pipe or Write To Pipe according to the required transaction (see Figure 9.3).
  Figure 9.3 Custom Request
- For a standard USB request: select a USB request from the requests list, which includes requests such as GET_DESCRIPTOR CONFIGURATION, GET_DESCRIPTOR DEVICE, GET_STATUS DEVICE, etc. (see Figure 9.4). The description of the selected request will be displayed in the Request Description box on the right hand of the dialogue window.
  Figure 9.4 Requests List
The results of the transfer, such as the data that was read or a relevant error, are displayed in Driver Wizard's Log window.
Figure 9.5 below shows the contents of the Log window after a successful GET_DESCRIPTOR DEVICE request.
Figure 9.5 USB Request Log

9.2.2.2 Control Transfers with WinDriver API

To perform a read or write transaction on the control pipe, you can either use the API generated by DriverWizard for your hardware, or directly call the WinDriver WDU_Transfer() [B.4.8.1] function from within your application.

Fill the setup packet in the BYTE SetupPacket[8] array and call these functions to send setup packets on Pipe00 and to retrieve control and status data from the device.

The following sample demonstrates how to fill the SetupPacket[8] variable with a GET_DESCRIPTOR setup packet:

setupPacket[0] = 0x80;   /* BmRequstType */
    setupPacket[1] = 0x6;    /* bRequest  [0x6 == GET_DESCRIPTOR] */
    setupPacket[2] = 0;      /* wValue */
    setupPacket[3] = 0x1;    /* wValue [Descriptor Type: 0x1 == DEVICE] */
    setupPacket[4] = 0;      /* wIndex */
    setupPacket[5] = 0;      /* wIndex */
    setupPacket[6] = 0x12;   /* wLength  [Size for the returned buffer] */
    setupPacket[7] = 0;      /* wLength */

The following sample demonstrates how to send a setup packet to the control pipe (a GET instruction; the device will return the information requested in the pBuffer variable):
```
WDU_TransferDefaultPipe(hDev, TRUE, 0, pBuffer, dwSize, 
       bytes_transferred, &setupPacket[0], 10000);
```

The following sample demonstrates how to send a setup packet to the control pipe (a SET instruction):

WDU_TransferDefaultPipe(hDev, FALSE, 0, NULL, 0,
        bytes_transferred, &setupPacket[0], 10000);

For further information regarding WDU_TransferDefaultPipe(), refer to section B.4.8.3. For further information regarding WDU_Transfer(), refer to section B.4.8.1.