USB/IP protocol¶
PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!28 Jun 2011
The USB/IP protocol follows a server/client architecture. The server exports theUSB devices and the clients imports them. The device driver for the exportedUSB device runs on the client machine.
The client may ask for the list of the exported USB devices. To get the list theclient opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLISTpacket on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sentin one or more pieces at the low level transport layer). The server sends backthe OP_REP_DEVLIST packet which lists the exported USB devices. Finally theTCP/IP connection is closed.
virtual host controller usb host "client" "server" (imports USB devices) (exports USB devices) | | | OP_REQ_DEVLIST | | ----------------------------------------------> | | | | OP_REP_DEVLIST | | <---------------------------------------------- | | |
Once the client knows the list of exported USB devices it may decide to use oneof them. First the client opens a TCP/IP connection towards the server andsends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If theimport was successful the TCP/IP connection remains open and will be usedto transfer the URB traffic between the client and the server. The client maysend two types of packets: the USBIP_CMD_SUBMIT to submit an URB, andUSBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of theserver may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
virtual host controller usb host "client" "server" (imports USB devices) (exports USB devices) | | | OP_REQ_IMPORT | | ----------------------------------------------> | | | | OP_REP_IMPORT | | <---------------------------------------------- | | | | | | USBIP_CMD_SUBMIT(seqnum = n) | | ----------------------------------------------> | | | | USBIP_RET_SUBMIT(seqnum = n) | | <---------------------------------------------- | | . | | : | | | | USBIP_CMD_SUBMIT(seqnum = m) | | ----------------------------------------------> | | | | USBIP_CMD_SUBMIT(seqnum = m+1) | | ----------------------------------------------> | | | | USBIP_CMD_SUBMIT(seqnum = m+2) | | ----------------------------------------------> | | | | USBIP_RET_SUBMIT(seqnum = m) | | <---------------------------------------------- | | | | USBIP_CMD_SUBMIT(seqnum = m+3) | | ----------------------------------------------> | | | | USBIP_RET_SUBMIT(seqnum = m+1) | | <---------------------------------------------- | | | | USBIP_CMD_SUBMIT(seqnum = m+4) | | ----------------------------------------------> | | | | USBIP_RET_SUBMIT(seqnum = m+2) | | <---------------------------------------------- | | . | | : | | | | USBIP_CMD_UNLINK | | ----------------------------------------------> | | | | USBIP_RET_UNLINK | | <---------------------------------------------- | | |
The fields are in network (big endian) byte order meaning that the most significantbyte (MSB) is stored at the lowest address.
- OP_REQ_DEVLIST:
- Retrieve the list of exported USB devices.
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 |
| 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USBdevices. |
| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
- OP_REP_DEVLIST:
- Reply with the list of exported USB devices.
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0. |
| 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. |
| 4 | 4 | 0x00000000 | Status: 0 for OK |
| 8 | 4 | n | Number of exported devices: 0 means no exporteddevices. |
| 0x0C | From now on the exported n devices are described,if any. If no devices are exported the messageends with the previous “number of exporteddevices” field. | ||
| 256 | path: Path of the device on the host exporting theUSB device, string closed with zero byte, e.g.“/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2”The unused bytes shall be filled with zerobytes. | ||
| 0x10C | 32 | busid: Bus ID of the exported device, stringclosed with zero byte, e.g. “3-2”. The unusedbytes shall be filled with zero bytes. | |
| 0x12C | 4 | busnum | |
| 0x130 | 4 | devnum | |
| 0x134 | 4 | speed | |
| 0x138 | 2 | idVendor | |
| 0x13A | 2 | idProduct | |
| 0x13C | 2 | bcdDevice | |
| 0x13E | 1 | bDeviceClass | |
| 0x13F | 1 | bDeviceSubClass | |
| 0x140 | 1 | bDeviceProtocol | |
| 0x141 | 1 | bConfigurationValue | |
| 0x142 | 1 | bNumConfigurations | |
| 0x143 | 1 | bNumInterfaces | |
| 0x144 | m_0 | From now on each interface is described, alltogether bNumInterfaces times, with thethe following 4 fields: | |
| 1 | bInterfaceClass | ||
| 0x145 | 1 | bInterfaceSubClass | |
| 0x146 | 1 | bInterfaceProtocol | |
| 0x147 | 1 | padding byte for alignment, shall be set to zero | |
| 0xC +i*0x138 +m_(i-1)*4 | The second exported USB device starts at i=1with the busid field. |
- OP_REQ_IMPORT:
- Request to import (attach) a remote USB device.
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 |
| 2 | 2 | 0x8003 | Command code: import a remote USB device. |
| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
| 8 | 32 | busid: the busid of the exported device on theremote host. The possible values are takenfrom the message field OP_REP_DEVLIST.busid.A string closed with zero, the unused bytesshall be filled with zeros. |
- OP_REP_IMPORT:
- Reply to import (attach) a remote USB device.
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 |
| 2 | 2 | 0x0003 | Reply code: Reply to import. |
| 4 | 4 | 0x00000000 | Status:
|
| 8 | From now on comes the details of the importeddevice, if the previous status field was OK (0),otherwise the reply ends with the status field. | ||
| 256 | path: Path of the device on the host exporting theUSB device, string closed with zero byte, e.g.“/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2”The unused bytes shall be filled with zerobytes. | ||
| 0x108 | 32 | busid: Bus ID of the exported device, stringclosed with zero byte, e.g. “3-2”. The unusedbytes shall be filled with zero bytes. | |
| 0x128 | 4 | busnum | |
| 0x12C | 4 | devnum | |
| 0x130 | 4 | speed | |
| 0x134 | 2 | idVendor | |
| 0x136 | 2 | idProduct | |
| 0x138 | 2 | bcdDevice | |
| 0x139 | 1 | bDeviceClass | |
| 0x13A | 1 | bDeviceSubClass | |
| 0x13B | 1 | bDeviceProtocol | |
| 0x13C | 1 | bConfigurationValue | |
| 0x13D | 1 | bNumConfigurations | |
| 0x13E | 1 | bNumInterfaces |
- USBIP_CMD_SUBMIT:
- Submit an URB
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 4 | 0x00000001 | command: Submit an URB |
| 4 | 4 | seqnum: the sequence number of the URB to submit | |
| 8 | 4 | devid | |
| 0xC | 4 | direction:
| |
| 0x10 | 4 | ep: endpoint number, possible values are: 0…15 | |
| 0x14 | 4 | transfer_flags: possible values depend on theURB transfer type, see below | |
| 0x18 | 4 | transfer_buffer_length | |
| 0x1C | 4 | start_frame: specify the selected frame totransmit an ISO frame, ignored if URB_ISO_ASAPis specified at transfer_flags | |
| 0x20 | 4 | number_of_packets: number of ISO packets | |
| 0x24 | 4 | interval: maximum time for the request on theserver-side host controller | |
| 0x28 | 8 | setup: data bytes for USB setup, filled withzeros if not used | |
| 0x30 | URB data. For ISO transfers the padding betweeneach ISO packets is not transmitted. |
Allowed transfer_flags value control interrupt bulk isochronous URB_SHORT_NOT_OK 0x00000001 only in only in only in no URB_ISO_ASAP 0x00000002 no no no yes URB_NO_TRANSFER_DMA_MAP 0x00000004 yes yes yes yes URB_ZERO_PACKET 0x00000040 no no only out no URB_NO_INTERRUPT 0x00000080 yes yes yes yes URB_FREE_BUFFER 0x00000100 yes yes yes yes URB_DIR_MASK 0x00000200 yes yes yes yes
- USBIP_RET_SUBMIT:
- Reply for submitting an URB
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 4 | 0x00000003 | command |
| 4 | 4 | seqnum: URB sequence number | |
| 8 | 4 | devid | |
| 0xC | 4 | direction:
| |
| 0x10 | 4 | ep: endpoint number | |
| 0x14 | 4 | status: zero for successful URB transaction,otherwise some kind of error happened. | |
| 0x18 | 4 | n | actual_length: number of URB data bytes |
| 0x1C | 4 | start_frame: for an ISO frame the actuallyselected frame for transmit. | |
| 0x20 | 4 | number_of_packets | |
| 0x24 | 4 | error_count | |
| 0x28 | 8 | setup: data bytes for USB setup, filled withzeros if not used | |
| 0x30 | n | URB data bytes. For ISO transfers the paddingbetween each ISO packets is not transmitted. |
- USBIP_CMD_UNLINK:
- Unlink an URB
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 4 | 0x00000002 | command: URB unlink command |
| 4 | 4 | seqnum: URB sequence number to unlink:
| |
| 8 | 4 | devid | |
| 0xC | 4 | direction:
| |
| 0x10 | 4 | ep: endpoint number: zero | |
| 0x14 | 4 | seqnum: the URB sequence number given previouslyat USBIP_CMD_SUBMIT.seqnum field | |
| 0x30 | n | URB data bytes. For ISO transfers the paddingbetween each ISO packets is not transmitted. |
- USBIP_RET_UNLINK:
- Reply for URB unlink
| Offset | Length | Value | Description |
|---|---|---|---|
| 0 | 4 | 0x00000004 | command: reply for the URB unlink command |
| 4 | 4 | seqnum: the unlinked URB sequence number | |
| 8 | 4 | devid | |
| 0xC | 4 | direction:
| |
| 0x10 | 4 | ep: endpoint number | |
| 0x14 | 4 | status: This is the value contained in theurb->status in the URB completition handler.
| |
| 0x30 | n | URB data bytes. For ISO transfers the paddingbetween each ISO packets is not transmitted. |