359 lines
23 KiB
Text
359 lines
23 KiB
Text
|
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 + | | | The second exported USB device starts at i=1
|
||
|
|
i*0x138 + | | | with the busid field.
|
||
|
|
m_(i-1)*4 | | |
|
||
|
|
|
||
|
|
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_NO_FSBR | 0x00000020 | yes | no | no | no
|
||
|
|
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.
|