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.