Documentation/usb/usbip_protocol.txt

   1 PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
   2 28 Jun 2011
   3
   4 The USB/IP protocol follows a server/client architecture. The server exports the
   5 USB devices and the clients imports them. The device driver for the exported
   6 USB device runs on the client machine.
   7
   8 The client may ask for the list of the exported USB devices. To get the list the
   9 client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
  10 packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
  11 in one or more pieces at the low level transport layer). The server sends back
  12 the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
  13 TCP/IP connection is closed.
  14
  15  virtual host controller                                 usb host
  16       "client"                                           "server"
  17   (imports USB devices)                             (exports USB devices)
  18           |                                                 |
  19           |                  OP_REQ_DEVLIST                 |
  20           | ----------------------------------------------> |
  21           |                                                 |
  22           |                  OP_REP_DEVLIST                 |
  23           | <---------------------------------------------- |
  24           |                                                 |
  25
  26 Once the client knows the list of exported USB devices it may decide to use one
  27 of them. First the client opens a TCP/IP connection towards the server and
  28 sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
  29 import was successful the TCP/IP connection remains open and will be used
  30 to transfer the URB traffic between the client and the server. The client may
  31 send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
  32 USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
  33 server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
  34
  35  virtual host controller                                 usb host
  36       "client"                                           "server"
  37   (imports USB devices)                             (exports USB devices)
  38           |                                                 |
  39           |                  OP_REQ_IMPORT                  |
  40           | ----------------------------------------------> |
  41           |                                                 |
  42           |                  OP_REP_IMPORT                  |
  43           | <---------------------------------------------- |
  44           |                                                 |
  45           |                                                 |
  46           |            USBIP_CMD_SUBMIT(seqnum = n)         |
  47           | ----------------------------------------------> |
  48           |                                                 |
  49           |            USBIP_RET_SUBMIT(seqnum = n)         |
  50           | <---------------------------------------------- |
  51           |                        .                        |
  52           |                        :                        |
  53           |                                                 |
  54           |            USBIP_CMD_SUBMIT(seqnum = m)         |
  55           | ----------------------------------------------> |
  56           |                                                 |
  57           |            USBIP_CMD_SUBMIT(seqnum = m+1)       |
  58           | ----------------------------------------------> |
  59           |                                                 |
  60           |            USBIP_CMD_SUBMIT(seqnum = m+2)       |
  61           | ----------------------------------------------> |
  62           |                                                 |
  63           |            USBIP_RET_SUBMIT(seqnum = m)         |
  64           | <---------------------------------------------- |
  65           |                                                 |
  66           |            USBIP_CMD_SUBMIT(seqnum = m+3)       |
  67           | ----------------------------------------------> |
  68           |                                                 |
  69           |            USBIP_RET_SUBMIT(seqnum = m+1)       |
  70           | <---------------------------------------------- |
  71           |                                                 |
  72           |            USBIP_CMD_SUBMIT(seqnum = m+4)       |
  73           | ----------------------------------------------> |
  74           |                                                 |
  75           |            USBIP_RET_SUBMIT(seqnum = m+2)       |
  76           | <---------------------------------------------- |
  77           |                        .                        |
  78           |                        :                        |
  79           |                                                 |
  80           |               USBIP_CMD_UNLINK                  |
  81           | ----------------------------------------------> |
  82           |                                                 |
  83           |               USBIP_RET_UNLINK                  |
  84           | <---------------------------------------------- |
  85           |                                                 |
  86
  87 The fields are in network (big endian) byte order meaning that the most significant
  88 byte (MSB) is stored at the lowest address.
  89
  90
  91 OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
  92
  93  Offset    | Length | Value      | Description
  94 -----------+--------+------------+---------------------------------------------------
  95  0         | 2      | 0x0100     | Binary-coded decimal USBIP version number: v1.0.0
  96 -----------+--------+------------+---------------------------------------------------
  97  2         | 2      | 0x8005     | Command code: Retrieve the list of exported USB
  98            |        |            |   devices.
  99 -----------+--------+------------+---------------------------------------------------
 100  4         | 4      | 0x00000000 | Status: unused, shall be set to 0
 101
 102 OP_REP_DEVLIST: Reply with the list of exported USB devices.
 103
 104  Offset    | Length | Value      | Description
 105 -----------+--------+------------+---------------------------------------------------
 106  0         | 2      | 0x0100     | Binary-coded decimal USBIP version number: v1.0.0.
 107 -----------+--------+------------+---------------------------------------------------
 108  2         | 2      | 0x0005     | Reply code: The list of exported USB devices.
 109 -----------+--------+------------+---------------------------------------------------
 110  4         | 4      | 0x00000000 | Status: 0 for OK
 111 -----------+--------+------------+---------------------------------------------------
 112  8         | 4      | n          | Number of exported devices: 0 means no exported
 113            |        |            |   devices.
 114 -----------+--------+------------+---------------------------------------------------
 115  0x0C      |        |            | From now on the exported n devices are described,
 116            |        |            |   if any. If no devices are exported the message
 117            |        |            |   ends with the previous "number of exported
 118            |        |            |   devices" field.
 119 -----------+--------+------------+---------------------------------------------------
 120            | 256    |            | path: Path of the device on the host exporting the
 121            |        |            |   USB device, string closed with zero byte, e.g.
 122            |        |            |   "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
 123            |        |            |   The unused bytes shall be filled with zero
 124            |        |            |   bytes.
 125 -----------+--------+------------+---------------------------------------------------
 126  0x10C     | 32     |            | busid: Bus ID of the exported device, string
 127            |        |            |   closed with zero byte, e.g. "3-2". The unused
 128            |        |            |   bytes shall be filled with zero bytes.
 129 -----------+--------+------------+---------------------------------------------------
 130  0x12C     | 4      |            | busnum
 131 -----------+--------+------------+---------------------------------------------------
 132  0x130     | 4      |            | devnum
 133 -----------+--------+------------+---------------------------------------------------
 134  0x134     | 4      |            | speed
 135 -----------+--------+------------+---------------------------------------------------
 136  0x138     | 2      |            | idVendor
 137 -----------+--------+------------+---------------------------------------------------
 138  0x13A     | 2      |            | idProduct
 139 -----------+--------+------------+---------------------------------------------------
 140  0x13C     | 2      |            | bcdDevice
 141 -----------+--------+------------+---------------------------------------------------
 142  0x13E     | 1      |            | bDeviceClass
 143 -----------+--------+------------+---------------------------------------------------
 144  0x13F     | 1      |            | bDeviceSubClass
 145 -----------+--------+------------+---------------------------------------------------
 146  0x140     | 1      |            | bDeviceProtocol
 147 -----------+--------+------------+---------------------------------------------------
 148  0x141     | 1      |            | bConfigurationValue
 149 -----------+--------+------------+---------------------------------------------------
 150  0x142     | 1      |            | bNumConfigurations
 151 -----------+--------+------------+---------------------------------------------------
 152  0x143     | 1      |            | bNumInterfaces
 153 -----------+--------+------------+---------------------------------------------------
 154  0x144     |        | m_0        | From now on each interface is described, all
 155            |        |            |   together bNumInterfaces times, with the
 156            |        |            |   the following 4 fields:
 157 -----------+--------+------------+---------------------------------------------------
 158            | 1      |            | bInterfaceClass
 159 -----------+--------+------------+---------------------------------------------------
 160  0x145     | 1      |            | bInterfaceSubClass
 161 -----------+--------+------------+---------------------------------------------------
 162  0x146     | 1      |            | bInterfaceProtocol
 163 -----------+--------+------------+---------------------------------------------------
 164  0x147     | 1      |            | padding byte for alignment, shall be set to zero
 165 -----------+--------+------------+---------------------------------------------------
 166  0xC +     |        |            | The second exported USB device starts at i=1
 167  i*0x138 + |        |            | with the busid field.
 168  m_(i-1)*4 |        |            |
 169
 170 OP_REQ_IMPORT: Request to import (attach) a remote USB device.
 171
 172  Offset    | Length | Value      | Description
 173 -----------+--------+------------+---------------------------------------------------
 174  0         | 2      | 0x0100     | Binary-coded decimal USBIP version number: v1.0.0
 175 -----------+--------+------------+---------------------------------------------------
 176  2         | 2      | 0x8003     | Command code: import a remote USB device.
 177 -----------+--------+------------+---------------------------------------------------
 178  4         | 4      | 0x00000000 | Status: unused, shall be set to 0
 179 -----------+--------+------------+---------------------------------------------------
 180  8         | 32     |            | busid: the busid of the exported device on the
 181            |        |            |   remote host. The possible values are taken
 182            |        |            |   from the message field OP_REP_DEVLIST.busid.
 183            |        |            |   A string closed with zero, the unused bytes
 184            |        |            |   shall be filled with zeros.
 185 -----------+--------+------------+---------------------------------------------------
 186
 187 OP_REP_IMPORT: Reply to import (attach) a remote USB device.
 188
 189  Offset    | Length | Value      | Description
 190 -----------+--------+------------+---------------------------------------------------
 191  0         | 2      | 0x0100     | Binary-coded decimal USBIP version number: v1.0.0
 192 -----------+--------+------------+---------------------------------------------------
 193  2         | 2      | 0x0003     | Reply code: Reply to import.
 194 -----------+--------+------------+---------------------------------------------------
 195  4         | 4      | 0x00000000 | Status: 0 for OK
 196            |        |            |         1 for error
 197 -----------+--------+------------+---------------------------------------------------
 198  8         |        |            | From now on comes the details of the imported
 199            |        |            |   device, if the previous status field was OK (0),
 200            |        |            |   otherwise the reply ends with the status field.
 201 -----------+--------+------------+---------------------------------------------------
 202            | 256    |            | path: Path of the device on the host exporting the
 203            |        |            |   USB device, string closed with zero byte, e.g.
 204            |        |            |   "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
 205            |        |            |   The unused bytes shall be filled with zero
 206            |        |            |   bytes.
 207 -----------+--------+------------+---------------------------------------------------
 208  0x108     | 32     |            | busid: Bus ID of the exported device, string
 209            |        |            |   closed with zero byte, e.g. "3-2". The unused
 210            |        |            |   bytes shall be filled with zero bytes.
 211 -----------+--------+------------+---------------------------------------------------
 212  0x128     | 4      |            | busnum
 213 -----------+--------+------------+---------------------------------------------------
 214  0x12C     | 4      |            | devnum
 215 -----------+--------+------------+---------------------------------------------------
 216  0x130     | 4      |            | speed
 217 -----------+--------+------------+---------------------------------------------------
 218  0x134     | 2      |            | idVendor
 219 -----------+--------+------------+---------------------------------------------------
 220  0x136     | 2      |            | idProduct
 221 -----------+--------+------------+---------------------------------------------------
 222  0x138     | 2      |            | bcdDevice
 223 -----------+--------+------------+---------------------------------------------------
 224  0x139     | 1      |            | bDeviceClass
 225 -----------+--------+------------+---------------------------------------------------
 226  0x13A     | 1      |            | bDeviceSubClass
 227 -----------+--------+------------+---------------------------------------------------
 228  0x13B     | 1      |            | bDeviceProtocol
 229 -----------+--------+------------+---------------------------------------------------
 230  0x13C     | 1      |            | bConfigurationValue
 231 -----------+--------+------------+---------------------------------------------------
 232  0x13D     | 1      |            | bNumConfigurations
 233 -----------+--------+------------+---------------------------------------------------
 234  0x13E     | 1      |            | bNumInterfaces
 235
 236 USBIP_CMD_SUBMIT: Submit an URB
 237
 238  Offset    | Length | Value      | Description
 239 -----------+--------+------------+---------------------------------------------------
 240  0         | 4      | 0x00000001 | command: Submit an URB
 241 -----------+--------+------------+---------------------------------------------------
 242  4         | 4      |            | seqnum: the sequence number of the URB to submit
 243 -----------+--------+------------+---------------------------------------------------
 244  8         | 4      |            | devid
 245 -----------+--------+------------+---------------------------------------------------
 246  0xC       | 4      |            | direction: 0: USBIP_DIR_OUT
 247            |        |            |            1: USBIP_DIR_IN
 248 -----------+--------+------------+---------------------------------------------------
 249  0x10      | 4      |            | ep: endpoint number, possible values are: 0...15
 250 -----------+--------+------------+---------------------------------------------------
 251  0x14      | 4      |            | transfer_flags: possible values depend on the
 252            |        |            |   URB transfer type, see below
 253 -----------+--------+------------+---------------------------------------------------
 254  0x18      | 4      |            | transfer_buffer_length
 255 -----------+--------+------------+---------------------------------------------------
 256  0x1C      | 4      |            | start_frame: specify the selected frame to
 257            |        |            |   transmit an ISO frame, ignored if URB_ISO_ASAP
 258            |        |            |   is specified at transfer_flags
 259 -----------+--------+------------+---------------------------------------------------
 260  0x20      | 4      |            | number_of_packets: number of ISO packets
 261 -----------+--------+------------+---------------------------------------------------
 262  0x24      | 4      |            | interval: maximum time for the request on the
 263            |        |            |   server-side host controller
 264 -----------+--------+------------+---------------------------------------------------
 265  0x28      | 8      |            | setup: data bytes for USB setup, filled with
 266            |        |            |   zeros if not used
 267 -----------+--------+------------+---------------------------------------------------
 268  0x30      |        |            | URB data. For ISO transfers the padding between
 269            |        |            |   each ISO packets is not transmitted.
 270
 271
 272   Allowed transfer_flags  | value      | control | interrupt | bulk     | isochronous
 273  -------------------------+------------+---------+-----------+----------+-------------
 274   URB_SHORT_NOT_OK        | 0x00000001 | only in | only in   | only in  | no
 275   URB_ISO_ASAP            | 0x00000002 | no      | no        | no       | yes
 276   URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes     | yes       | yes      | yes
 277   URB_ZERO_PACKET         | 0x00000040 | no      | no        | only out | no
 278   URB_NO_INTERRUPT        | 0x00000080 | yes     | yes       | yes      | yes
 279   URB_FREE_BUFFER         | 0x00000100 | yes     | yes       | yes      | yes
 280   URB_DIR_MASK            | 0x00000200 | yes     | yes       | yes      | yes
 281
 282
 283 USBIP_RET_SUBMIT: Reply for submitting an URB
 284
 285  Offset    | Length | Value      | Description
 286 -----------+--------+------------+---------------------------------------------------
 287  0         | 4      | 0x00000003 | command
 288 -----------+--------+------------+---------------------------------------------------
 289  4         | 4      |            | seqnum: URB sequence number
 290 -----------+--------+------------+---------------------------------------------------
 291  8         | 4      |            | devid
 292 -----------+--------+------------+---------------------------------------------------
 293  0xC       | 4      |            | direction: 0: USBIP_DIR_OUT
 294            |        |            |            1: USBIP_DIR_IN
 295 -----------+--------+------------+---------------------------------------------------
 296  0x10      | 4      |            | ep: endpoint number
 297 -----------+--------+------------+---------------------------------------------------
 298  0x14      | 4      |            | status: zero for successful URB transaction,
 299            |        |            |   otherwise some kind of error happened.
 300 -----------+--------+------------+---------------------------------------------------
 301  0x18      | 4      | n          | actual_length: number of URB data bytes
 302 -----------+--------+------------+---------------------------------------------------
 303  0x1C      | 4      |            | start_frame: for an ISO frame the actually
 304            |        |            |   selected frame for transmit.
 305 -----------+--------+------------+---------------------------------------------------
 306  0x20      | 4      |            | number_of_packets
 307 -----------+--------+------------+---------------------------------------------------
 308  0x24      | 4      |            | error_count
 309 -----------+--------+------------+---------------------------------------------------
 310  0x28      | 8      |            | setup: data bytes for USB setup, filled with
 311            |        |            |   zeros if not used
 312 -----------+--------+------------+---------------------------------------------------
 313  0x30      | n      |            | URB data bytes. For ISO transfers the padding
 314            |        |            |   between each ISO packets is not transmitted.
 315
 316 USBIP_CMD_UNLINK: Unlink an URB
 317
 318  Offset    | Length | Value      | Description
 319 -----------+--------+------------+---------------------------------------------------
 320  0         | 4      | 0x00000002 | command: URB unlink command
 321 -----------+--------+------------+---------------------------------------------------
 322  4         | 4      |            | seqnum: URB sequence number to unlink: FIXME: is this so?
 323 -----------+--------+------------+---------------------------------------------------
 324  8         | 4      |            | devid
 325 -----------+--------+------------+---------------------------------------------------
 326  0xC       | 4      |            | direction: 0: USBIP_DIR_OUT
 327            |        |            |            1: USBIP_DIR_IN
 328 -----------+--------+------------+---------------------------------------------------
 329  0x10      | 4      |            | ep: endpoint number: zero
 330 -----------+--------+------------+---------------------------------------------------
 331  0x14      | 4      |            | seqnum: the URB sequence number given previously
 332            |        |            |   at USBIP_CMD_SUBMIT.seqnum field
 333 -----------+--------+------------+---------------------------------------------------
 334  0x30      | n      |            | URB data bytes. For ISO transfers the padding
 335            |        |            |   between each ISO packets is not transmitted.
 336
 337 USBIP_RET_UNLINK: Reply for URB unlink
 338
 339  Offset    | Length | Value      | Description
 340 -----------+--------+------------+---------------------------------------------------
 341  0         | 4      | 0x00000004 | command: reply for the URB unlink command
 342 -----------+--------+------------+---------------------------------------------------
 343  4         | 4      |            | seqnum: the unlinked URB sequence number
 344 -----------+--------+------------+---------------------------------------------------
 345  8         | 4      |            | devid
 346 -----------+--------+------------+---------------------------------------------------
 347  0xC       | 4      |            | direction: 0: USBIP_DIR_OUT
 348            |        |            |            1: USBIP_DIR_IN
 349 -----------+--------+------------+---------------------------------------------------
 350  0x10      | 4      |            | ep: endpoint number
 351 -----------+--------+------------+---------------------------------------------------
 352  0x14      | 4      |            | status: This is the value contained in the
 353            |        |            |   urb->status in the URB completition handler.
 354            |        |            |   FIXME: a better explanation needed.
 355 -----------+--------+------------+---------------------------------------------------
 356  0x30      | n      |            | URB data bytes. For ISO transfers the padding
 357            |        |            |   between each ISO packets is not transmitted.