0001 ===============
0002 USB/IP protocol
0003 ===============
0004
0005 Architecture
0006 ============
0007
0008 The USB/IP protocol follows a server/client architecture. The server exports the
0009 USB devices and the clients import them. The device driver for the exported
0010 USB device runs on the client machine.
0011
0012 The client may ask for the list of the exported USB devices. To get the list the
0013 client opens a TCP/IP connection to the server, and sends an OP_REQ_DEVLIST
0014 packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
0015 in one or more pieces at the low level transport layer). The server sends back
0016 the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
0017 TCP/IP connection is closed.
0018
0019 ::
0020
0021 virtual host controller usb host
0022 "client" "server"
0023 (imports USB devices) (exports USB devices)
0024 | |
0025 | OP_REQ_DEVLIST |
0026 | ----------------------------------------------> |
0027 | |
0028 | OP_REP_DEVLIST |
0029 | <---------------------------------------------- |
0030 | |
0031
0032 Once the client knows the list of exported USB devices it may decide to use one
0033 of them. First the client opens a TCP/IP connection to the server and
0034 sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
0035 import was successful the TCP/IP connection remains open and will be used
0036 to transfer the URB traffic between the client and the server. The client may
0037 send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
0038 USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
0039 server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
0040
0041 ::
0042
0043 virtual host controller usb host
0044 "client" "server"
0045 (imports USB devices) (exports USB devices)
0046 | |
0047 | OP_REQ_IMPORT |
0048 | ----------------------------------------------> |
0049 | |
0050 | OP_REP_IMPORT |
0051 | <---------------------------------------------- |
0052 | |
0053 | |
0054 | USBIP_CMD_SUBMIT(seqnum = n) |
0055 | ----------------------------------------------> |
0056 | |
0057 | USBIP_RET_SUBMIT(seqnum = n) |
0058 | <---------------------------------------------- |
0059 | . |
0060 | : |
0061 | |
0062 | USBIP_CMD_SUBMIT(seqnum = m) |
0063 | ----------------------------------------------> |
0064 | |
0065 | USBIP_CMD_SUBMIT(seqnum = m+1) |
0066 | ----------------------------------------------> |
0067 | |
0068 | USBIP_CMD_SUBMIT(seqnum = m+2) |
0069 | ----------------------------------------------> |
0070 | |
0071 | USBIP_RET_SUBMIT(seqnum = m) |
0072 | <---------------------------------------------- |
0073 | |
0074 | USBIP_CMD_SUBMIT(seqnum = m+3) |
0075 | ----------------------------------------------> |
0076 | |
0077 | USBIP_RET_SUBMIT(seqnum = m+1) |
0078 | <---------------------------------------------- |
0079 | |
0080 | USBIP_CMD_SUBMIT(seqnum = m+4) |
0081 | ----------------------------------------------> |
0082 | |
0083 | USBIP_RET_SUBMIT(seqnum = m+2) |
0084 | <---------------------------------------------- |
0085 | . |
0086 | : |
0087
0088 For UNLINK, note that after a successful USBIP_RET_UNLINK, the unlinked URB
0089 submission would not have a corresponding USBIP_RET_SUBMIT (this is explained in
0090 function stub_recv_cmd_unlink of drivers/usb/usbip/stub_rx.c).
0091
0092 ::
0093
0094 virtual host controller usb host
0095 "client" "server"
0096 (imports USB devices) (exports USB devices)
0097 | |
0098 | USBIP_CMD_SUBMIT(seqnum = p) |
0099 | ----------------------------------------------> |
0100 | |
0101 | USBIP_CMD_UNLINK |
0102 | (seqnum = p+1, unlink_seqnum = p) |
0103 | ----------------------------------------------> |
0104 | |
0105 | USBIP_RET_UNLINK |
0106 | (seqnum = p+1, status = -ECONNRESET) |
0107 | <---------------------------------------------- |
0108 | |
0109 | Note: No USBIP_RET_SUBMIT(seqnum = p) |
0110 | <--X---X---X---X---X---X---X---X---X---X---X--- |
0111 | . |
0112 | : |
0113 | |
0114 | USBIP_CMD_SUBMIT(seqnum = q) |
0115 | ----------------------------------------------> |
0116 | |
0117 | USBIP_RET_SUBMIT(seqnum = q) |
0118 | <---------------------------------------------- |
0119 | |
0120 | USBIP_CMD_UNLINK |
0121 | (seqnum = q+1, unlink_seqnum = q) |
0122 | ----------------------------------------------> |
0123 | |
0124 | USBIP_RET_UNLINK |
0125 | (seqnum = q+1, status = 0) |
0126 | <---------------------------------------------- |
0127 | |
0128
0129 The fields are in network (big endian) byte order meaning that the most significant
0130 byte (MSB) is stored at the lowest address.
0131
0132 Protocol Version
0133 ================
0134
0135 The documented USBIP version is v1.1.1. The binary representation of this
0136 version in message headers is 0x0111.
0137
0138 This is defined in tools/usb/usbip/configure.ac
0139
0140 Message Format
0141 ==============
0142
0143 OP_REQ_DEVLIST:
0144 Retrieve the list of exported USB devices.
0145
0146 +-----------+--------+------------+---------------------------------------------------+
0147 | Offset | Length | Value | Description |
0148 +===========+========+============+===================================================+
0149 | 0 | 2 | | USBIP version |
0150 +-----------+--------+------------+---------------------------------------------------+
0151 | 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB |
0152 | | | | devices. |
0153 +-----------+--------+------------+---------------------------------------------------+
0154 | 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
0155 +-----------+--------+------------+---------------------------------------------------+
0156
0157 OP_REP_DEVLIST:
0158 Reply with the list of exported USB devices.
0159
0160 +-----------+--------+------------+---------------------------------------------------+
0161 | Offset | Length | Value | Description |
0162 +===========+========+============+===================================================+
0163 | 0 | 2 | | USBIP version |
0164 +-----------+--------+------------+---------------------------------------------------+
0165 | 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. |
0166 +-----------+--------+------------+---------------------------------------------------+
0167 | 4 | 4 | 0x00000000 | Status: 0 for OK |
0168 +-----------+--------+------------+---------------------------------------------------+
0169 | 8 | 4 | n | Number of exported devices: 0 means no exported |
0170 | | | | devices. |
0171 +-----------+--------+------------+---------------------------------------------------+
0172 | 0x0C | | | From now on the exported n devices are described, |
0173 | | | | if any. If no devices are exported the message |
0174 | | | | ends with the previous "number of exported |
0175 | | | | devices" field. |
0176 +-----------+--------+------------+---------------------------------------------------+
0177 | | 256 | | path: Path of the device on the host exporting the|
0178 | | | | USB device, string closed with zero byte, e.g. |
0179 | | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" |
0180 | | | | The unused bytes shall be filled with zero |
0181 | | | | bytes. |
0182 +-----------+--------+------------+---------------------------------------------------+
0183 | 0x10C | 32 | | busid: Bus ID of the exported device, string |
0184 | | | | closed with zero byte, e.g. "3-2". The unused |
0185 | | | | bytes shall be filled with zero bytes. |
0186 +-----------+--------+------------+---------------------------------------------------+
0187 | 0x12C | 4 | | busnum |
0188 +-----------+--------+------------+---------------------------------------------------+
0189 | 0x130 | 4 | | devnum |
0190 +-----------+--------+------------+---------------------------------------------------+
0191 | 0x134 | 4 | | speed |
0192 +-----------+--------+------------+---------------------------------------------------+
0193 | 0x138 | 2 | | idVendor |
0194 +-----------+--------+------------+---------------------------------------------------+
0195 | 0x13A | 2 | | idProduct |
0196 +-----------+--------+------------+---------------------------------------------------+
0197 | 0x13C | 2 | | bcdDevice |
0198 +-----------+--------+------------+---------------------------------------------------+
0199 | 0x13E | 1 | | bDeviceClass |
0200 +-----------+--------+------------+---------------------------------------------------+
0201 | 0x13F | 1 | | bDeviceSubClass |
0202 +-----------+--------+------------+---------------------------------------------------+
0203 | 0x140 | 1 | | bDeviceProtocol |
0204 +-----------+--------+------------+---------------------------------------------------+
0205 | 0x141 | 1 | | bConfigurationValue |
0206 +-----------+--------+------------+---------------------------------------------------+
0207 | 0x142 | 1 | | bNumConfigurations |
0208 +-----------+--------+------------+---------------------------------------------------+
0209 | 0x143 | 1 | | bNumInterfaces |
0210 +-----------+--------+------------+---------------------------------------------------+
0211 | 0x144 | | m_0 | From now on each interface is described, all |
0212 | | | | together bNumInterfaces times, with the following |
0213 | | | | 4 fields: |
0214 +-----------+--------+------------+---------------------------------------------------+
0215 | | 1 | | bInterfaceClass |
0216 +-----------+--------+------------+---------------------------------------------------+
0217 | 0x145 | 1 | | bInterfaceSubClass |
0218 +-----------+--------+------------+---------------------------------------------------+
0219 | 0x146 | 1 | | bInterfaceProtocol |
0220 +-----------+--------+------------+---------------------------------------------------+
0221 | 0x147 | 1 | | padding byte for alignment, shall be set to zero |
0222 +-----------+--------+------------+---------------------------------------------------+
0223 | 0xC + | | | The second exported USB device starts at i=1 |
0224 | i*0x138 + | | | with the path field. |
0225 | m_(i-1)*4 | | | |
0226 +-----------+--------+------------+---------------------------------------------------+
0227
0228 OP_REQ_IMPORT:
0229 Request to import (attach) a remote USB device.
0230
0231 +-----------+--------+------------+---------------------------------------------------+
0232 | Offset | Length | Value | Description |
0233 +===========+========+============+===================================================+
0234 | 0 | 2 | | USBIP version |
0235 +-----------+--------+------------+---------------------------------------------------+
0236 | 2 | 2 | 0x8003 | Command code: import a remote USB device. |
0237 +-----------+--------+------------+---------------------------------------------------+
0238 | 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
0239 +-----------+--------+------------+---------------------------------------------------+
0240 | 8 | 32 | | busid: the busid of the exported device on the |
0241 | | | | remote host. The possible values are taken |
0242 | | | | from the message field OP_REP_DEVLIST.busid. |
0243 | | | | A string closed with zero, the unused bytes |
0244 | | | | shall be filled with zeros. |
0245 +-----------+--------+------------+---------------------------------------------------+
0246
0247 OP_REP_IMPORT:
0248 Reply to import (attach) a remote USB device.
0249
0250 +-----------+--------+------------+---------------------------------------------------+
0251 | Offset | Length | Value | Description |
0252 +===========+========+============+===================================================+
0253 | 0 | 2 | | USBIP version |
0254 +-----------+--------+------------+---------------------------------------------------+
0255 | 2 | 2 | 0x0003 | Reply code: Reply to import. |
0256 +-----------+--------+------------+---------------------------------------------------+
0257 | 4 | 4 | 0x00000000 | Status: |
0258 | | | | |
0259 | | | | - 0 for OK |
0260 | | | | - 1 for error |
0261 +-----------+--------+------------+---------------------------------------------------+
0262 | 8 | | | From now on comes the details of the imported |
0263 | | | | device, if the previous status field was OK (0), |
0264 | | | | otherwise the reply ends with the status field. |
0265 +-----------+--------+------------+---------------------------------------------------+
0266 | | 256 | | path: Path of the device on the host exporting the|
0267 | | | | USB device, string closed with zero byte, e.g. |
0268 | | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" |
0269 | | | | The unused bytes shall be filled with zero |
0270 | | | | bytes. |
0271 +-----------+--------+------------+---------------------------------------------------+
0272 | 0x108 | 32 | | busid: Bus ID of the exported device, string |
0273 | | | | closed with zero byte, e.g. "3-2". The unused |
0274 | | | | bytes shall be filled with zero bytes. |
0275 +-----------+--------+------------+---------------------------------------------------+
0276 | 0x128 | 4 | | busnum |
0277 +-----------+--------+------------+---------------------------------------------------+
0278 | 0x12C | 4 | | devnum |
0279 +-----------+--------+------------+---------------------------------------------------+
0280 | 0x130 | 4 | | speed |
0281 +-----------+--------+------------+---------------------------------------------------+
0282 | 0x134 | 2 | | idVendor |
0283 +-----------+--------+------------+---------------------------------------------------+
0284 | 0x136 | 2 | | idProduct |
0285 +-----------+--------+------------+---------------------------------------------------+
0286 | 0x138 | 2 | | bcdDevice |
0287 +-----------+--------+------------+---------------------------------------------------+
0288 | 0x139 | 1 | | bDeviceClass |
0289 +-----------+--------+------------+---------------------------------------------------+
0290 | 0x13A | 1 | | bDeviceSubClass |
0291 +-----------+--------+------------+---------------------------------------------------+
0292 | 0x13B | 1 | | bDeviceProtocol |
0293 +-----------+--------+------------+---------------------------------------------------+
0294 | 0x13C | 1 | | bConfigurationValue |
0295 +-----------+--------+------------+---------------------------------------------------+
0296 | 0x13D | 1 | | bNumConfigurations |
0297 +-----------+--------+------------+---------------------------------------------------+
0298 | 0x13E | 1 | | bNumInterfaces |
0299 +-----------+--------+------------+---------------------------------------------------+
0300
0301 The following four commands have a common basic header called
0302 'usbip_header_basic', and their headers, called 'usbip_header' (before
0303 transfer_buffer payload), have the same length, therefore paddings are needed.
0304
0305 usbip_header_basic:
0306
0307 +-----------+--------+---------------------------------------------------+
0308 | Offset | Length | Description |
0309 +===========+========+===================================================+
0310 | 0 | 4 | command |
0311 +-----------+--------+---------------------------------------------------+
0312 | 4 | 4 | seqnum: sequential number that identifies requests|
0313 | | | and corresponding responses; |
0314 | | | incremented per connection |
0315 +-----------+--------+---------------------------------------------------+
0316 | 8 | 4 | devid: specifies a remote USB device uniquely |
0317 | | | instead of busnum and devnum; |
0318 | | | for client (request), this value is |
0319 | | | ((busnum << 16) | devnum); |
0320 | | | for server (response), this shall be set to 0 |
0321 +-----------+--------+---------------------------------------------------+
0322 | 0xC | 4 | direction: |
0323 | | | |
0324 | | | - 0: USBIP_DIR_OUT |
0325 | | | - 1: USBIP_DIR_IN |
0326 | | | |
0327 | | | only used by client, for server this shall be 0 |
0328 +-----------+--------+---------------------------------------------------+
0329 | 0x10 | 4 | ep: endpoint number |
0330 | | | only used by client, for server this shall be 0; |
0331 | | | for UNLINK, this shall be 0 |
0332 +-----------+--------+---------------------------------------------------+
0333
0334 USBIP_CMD_SUBMIT:
0335 Submit an URB
0336
0337 +-----------+--------+---------------------------------------------------+
0338 | Offset | Length | Description |
0339 +===========+========+===================================================+
0340 | 0 | 20 | usbip_header_basic, 'command' shall be 0x00000001 |
0341 +-----------+--------+---------------------------------------------------+
0342 | 0x14 | 4 | transfer_flags: possible values depend on the |
0343 | | | URB transfer_flags (refer to URB doc in |
0344 | | | Documentation/driver-api/usb/URB.rst) |
0345 | | | but with URB_NO_TRANSFER_DMA_MAP masked. Refer to |
0346 | | | function usbip_pack_cmd_submit and function |
0347 | | | tweak_transfer_flags in drivers/usb/usbip/ |
0348 | | | usbip_common.c. The following fields may also ref |
0349 | | | to function usbip_pack_cmd_submit and URB doc |
0350 +-----------+--------+---------------------------------------------------+
0351 | 0x18 | 4 | transfer_buffer_length: |
0352 | | | use URB transfer_buffer_length |
0353 +-----------+--------+---------------------------------------------------+
0354 | 0x1C | 4 | start_frame: use URB start_frame; |
0355 | | | initial frame for ISO transfer; |
0356 | | | shall be set to 0 if not ISO transfer |
0357 +-----------+--------+---------------------------------------------------+
0358 | 0x20 | 4 | number_of_packets: number of ISO packets; |
0359 | | | shall be set to 0xffffffff if not ISO transfer |
0360 +-----------+--------+---------------------------------------------------+
0361 | 0x24 | 4 | interval: maximum time for the request on the |
0362 | | | server-side host controller |
0363 +-----------+--------+---------------------------------------------------+
0364 | 0x28 | 8 | setup: data bytes for USB setup, filled with |
0365 | | | zeros if not used. |
0366 +-----------+--------+---------------------------------------------------+
0367 | 0x30 | n | transfer_buffer. |
0368 | | | If direction is USBIP_DIR_OUT then n equals |
0369 | | | transfer_buffer_length; otherwise n equals 0. |
0370 | | | For ISO transfers the padding between each ISO |
0371 | | | packets is not transmitted. |
0372 +-----------+--------+---------------------------------------------------+
0373 | 0x30+n | m | iso_packet_descriptor |
0374 +-----------+--------+---------------------------------------------------+
0375
0376 USBIP_RET_SUBMIT:
0377 Reply for submitting an URB
0378
0379 +-----------+--------+---------------------------------------------------+
0380 | Offset | Length | Description |
0381 +===========+========+===================================================+
0382 | 0 | 20 | usbip_header_basic, 'command' shall be 0x00000003 |
0383 +-----------+--------+---------------------------------------------------+
0384 | 0x14 | 4 | status: zero for successful URB transaction, |
0385 | | | otherwise some kind of error happened. |
0386 +-----------+--------+---------------------------------------------------+
0387 | 0x18 | 4 | actual_length: number of URB data bytes; |
0388 | | | use URB actual_length |
0389 +-----------+--------+---------------------------------------------------+
0390 | 0x1C | 4 | start_frame: use URB start_frame; |
0391 | | | initial frame for ISO transfer; |
0392 | | | shall be set to 0 if not ISO transfer |
0393 +-----------+--------+---------------------------------------------------+
0394 | 0x20 | 4 | number_of_packets: number of ISO packets; |
0395 | | | shall be set to 0xffffffff if not ISO transfer |
0396 +-----------+--------+---------------------------------------------------+
0397 | 0x24 | 4 | error_count |
0398 +-----------+--------+---------------------------------------------------+
0399 | 0x28 | 8 | padding, shall be set to 0 |
0400 +-----------+--------+---------------------------------------------------+
0401 | 0x30 | n | transfer_buffer. |
0402 | | | If direction is USBIP_DIR_IN then n equals |
0403 | | | actual_length; otherwise n equals 0. |
0404 | | | For ISO transfers the padding between each ISO |
0405 | | | packets is not transmitted. |
0406 +-----------+--------+---------------------------------------------------+
0407 | 0x30+n | m | iso_packet_descriptor |
0408 +-----------+--------+---------------------------------------------------+
0409
0410 USBIP_CMD_UNLINK:
0411 Unlink an URB
0412
0413 +-----------+--------+---------------------------------------------------+
0414 | Offset | Length | Description |
0415 +===========+========+===================================================+
0416 | 0 | 20 | usbip_header_basic, 'command' shall be 0x00000002 |
0417 +-----------+--------+---------------------------------------------------+
0418 | 0x14 | 4 | unlink_seqnum, of the SUBMIT request to unlink |
0419 +-----------+--------+---------------------------------------------------+
0420 | 0x18 | 24 | padding, shall be set to 0 |
0421 +-----------+--------+---------------------------------------------------+
0422
0423 USBIP_RET_UNLINK:
0424 Reply for URB unlink
0425
0426 +-----------+--------+---------------------------------------------------+
0427 | Offset | Length | Description |
0428 +===========+========+===================================================+
0429 | 0 | 20 | usbip_header_basic, 'command' shall be 0x00000004 |
0430 +-----------+--------+---------------------------------------------------+
0431 | 0x14 | 4 | status: This is similar to the status of |
0432 | | | USBIP_RET_SUBMIT (share the same memory offset). |
0433 | | | When UNLINK is successful, status is -ECONNRESET; |
0434 | | | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT |
0435 | | | status is 0 |
0436 +-----------+--------+---------------------------------------------------+
0437 | 0x18 | 24 | padding, shall be set to 0 |
0438 +-----------+--------+---------------------------------------------------+
0439
0440 EXAMPLE
0441 =======
0442
0443 The following data is captured from wire with Human Interface Devices (HID)
0444 payload
0445
0446 ::
0447
0448 CmdIntrIN: 00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000
0449 CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000
0450 ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
0451 RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
0452 RetIntrIn: 00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
0453 ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000
