123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411 |
- ===============
- 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 + | | | 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_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. |
- +-----------+--------+------------+---------------------------------------------------+
|