Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
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.