USB/IP protocol

PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! 28 Jun 2011

The USB/IP protocol follows a server/client architecture. The server exports the USB devices and the clients imports them. The device driver for the exported USB device runs on the client machine.

The client may ask for the list of the exported USB devices. To get the list the client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent in one or more pieces at the low level transport layer). The server sends back the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the TCP/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 one of them. First the client opens a TCP/IP connection towards the server and sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the import was successful the TCP/IP connection remains open and will be used to transfer the URB traffic between the client and the server. The client may send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the server 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 significant byte (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 USB devices.
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 exported devices.
0x0C     From now on the exported n devices are described, if any. If no devices are exported the message ends with the previous “number of exported devices” field.
  256   path: Path of the device on the host exporting the USB 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 zero bytes.
0x10C 32   busid: Bus ID of the exported device, string closed with zero byte, e.g. “3-2”. The unused bytes 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, all together bNumInterfaces times, with the the 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=1 with 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 the remote host. The possible values are taken from the message field OP_REP_DEVLIST.busid. A string closed with zero, the unused bytes shall 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:

  • 0 for OK
  • 1 for error
8     From now on comes the details of the imported device, 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 the USB 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 zero bytes.
0x108 32   busid: Bus ID of the exported device, string closed with zero byte, e.g. “3-2”. The unused bytes 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:

  • 0: USBIP_DIR_OUT
  • 1: USBIP_DIR_IN
0x10 4   ep: endpoint number, possible values are: 0…15
0x14 4   transfer_flags: possible values depend on the URB transfer type, see below
0x18 4   transfer_buffer_length
0x1C 4   start_frame: specify the selected frame to transmit an ISO frame, ignored if URB_ISO_ASAP is specified at transfer_flags
0x20 4   number_of_packets: number of ISO packets
0x24 4   interval: maximum time for the request on the server-side host controller
0x28 8   setup: data bytes for USB setup, filled with zeros if not used
0x30     URB data. For ISO transfers the padding between each 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:

  • 0: USBIP_DIR_OUT
  • 1: USBIP_DIR_IN
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 actually selected frame for transmit.
0x20 4   number_of_packets
0x24 4   error_count
0x28 8   setup: data bytes for USB setup, filled with zeros if not used
0x30 n   URB data bytes. For ISO transfers the padding between 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:

FIXME:
is this so?
8 4   devid
0xC 4  

direction:

  • 0: USBIP_DIR_OUT
  • 1: USBIP_DIR_IN
0x10 4   ep: endpoint number: zero
0x14 4   seqnum: the URB sequence number given previously at USBIP_CMD_SUBMIT.seqnum field
0x30 n   URB data bytes. For ISO transfers the padding between 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:

  • 0: USBIP_DIR_OUT
  • 1: USBIP_DIR_IN
0x10 4   ep: endpoint number
0x14 4  

status: This is the value contained in the urb->status in the URB completition handler.

FIXME:
a better explanation needed.
0x30 n   URB data bytes. For ISO transfers the padding between each ISO packets is not transmitted.