projects / linux-block.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
ublk: honor IO_URING_F_NONBLOCK for handling control command
[linux-block.git] / Documentation / usb / usbip_protocol.rst
CommitLineData
d80b5005
MCC		 1===============
2USB/IP protocol
3===============
4
17af7932
HZZ		 5Architecture
6============
c8742cf0
MN		 7
8The USB/IP protocol follows a server/client architecture. The server exports the
17af7932 9USB devices and the clients import them. The device driver for the exported
c8742cf0
MN		 10USB device runs on the client machine.
11
12The client may ask for the list of the exported USB devices. To get the list the
17af7932 13client opens a TCP/IP connection to the server, and sends an OP_REQ_DEVLIST
c8742cf0
MN		 14packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
15in one or more pieces at the low level transport layer). The server sends back
16the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
17TCP/IP connection is closed.
18
d80b5005
MCC		 19::
20
c8742cf0
MN		 21 virtual host controller usb host
22 "client" "server"
23 (imports USB devices) (exports USB devices)
24 | |
25 | OP_REQ_DEVLIST |
26 | ----------------------------------------------> |
27 | |
28 | OP_REP_DEVLIST |
29 | <---------------------------------------------- |
30 | |
31
32Once the client knows the list of exported USB devices it may decide to use one
17af7932 33of them. First the client opens a TCP/IP connection to the server and
c8742cf0
MN		 34sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
35import was successful the TCP/IP connection remains open and will be used
73e29189 36to transfer the URB traffic between the client and the server. The client may
c8742cf0
MN		 37send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
38USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
39server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
40
d80b5005
MCC		 41::
42
c8742cf0
MN		 43 virtual host controller usb host
44 "client" "server"
45 (imports USB devices) (exports USB devices)
46 | |
47 | OP_REQ_IMPORT |
48 | ----------------------------------------------> |
49 | |
50 | OP_REP_IMPORT |
51 | <---------------------------------------------- |
52 | |
53 | |
54 | USBIP_CMD_SUBMIT(seqnum = n) |
55 | ----------------------------------------------> |
56 | |
57 | USBIP_RET_SUBMIT(seqnum = n) |
58 | <---------------------------------------------- |
59 | . |
60 | : |
61 | |
62 | USBIP_CMD_SUBMIT(seqnum = m) |
63 | ----------------------------------------------> |
64 | |
65 | USBIP_CMD_SUBMIT(seqnum = m+1) |
66 | ----------------------------------------------> |
67 | |
68 | USBIP_CMD_SUBMIT(seqnum = m+2) |
69 | ----------------------------------------------> |
70 | |
71 | USBIP_RET_SUBMIT(seqnum = m) |
72 | <---------------------------------------------- |
73 | |
74 | USBIP_CMD_SUBMIT(seqnum = m+3) |
75 | ----------------------------------------------> |
76 | |
77 | USBIP_RET_SUBMIT(seqnum = m+1) |
78 | <---------------------------------------------- |
79 | |
80 | USBIP_CMD_SUBMIT(seqnum = m+4) |
81 | ----------------------------------------------> |
82 | |
83 | USBIP_RET_SUBMIT(seqnum = m+2) |
84 | <---------------------------------------------- |
85 | . |
86 | : |
17af7932
HZZ		 87
88For UNLINK, note that after a successful USBIP_RET_UNLINK, the unlinked URB
89submission would not have a corresponding USBIP_RET_SUBMIT (this is explained in
90function stub_recv_cmd_unlink of drivers/usb/usbip/stub_rx.c).
91
92::
93
94 virtual host controller usb host
95 "client" "server"
96 (imports USB devices) (exports USB devices)
97 | |
98 | USBIP_CMD_SUBMIT(seqnum = p) |
99 | ----------------------------------------------> |
c8742cf0
MN		 100 | |
101 | USBIP_CMD_UNLINK |
17af7932 102 | (seqnum = p+1, unlink_seqnum = p) |
c8742cf0
MN		 103 | ----------------------------------------------> |
104 | |
105 | USBIP_RET_UNLINK |
17af7932
HZZ		 106 | (seqnum = p+1, status = -ECONNRESET) |
107 | <---------------------------------------------- |
108 | |
109 | Note: No USBIP_RET_SUBMIT(seqnum = p) |
110 | <--X---X---X---X---X---X---X---X---X---X---X--- |
111 | . |
112 | : |
113 | |
114 | USBIP_CMD_SUBMIT(seqnum = q) |
115 | ----------------------------------------------> |
116 | |
117 | USBIP_RET_SUBMIT(seqnum = q) |
118 | <---------------------------------------------- |
119 | |
120 | USBIP_CMD_UNLINK |
121 | (seqnum = q+1, unlink_seqnum = q) |
122 | ----------------------------------------------> |
123 | |
124 | USBIP_RET_UNLINK |
125 | (seqnum = q+1, status = 0) |
c8742cf0
MN		 126 | <---------------------------------------------- |
127 | |
128
129The fields are in network (big endian) byte order meaning that the most significant
130byte (MSB) is stored at the lowest address.
131
17af7932
HZZ		 132Protocol Version
133================
134
135The documented USBIP version is v1.1.1. The binary representation of this
136version in message headers is 0x0111.
137
138This is defined in tools/usb/usbip/configure.ac
139
140Message Format
141==============
c8742cf0 142
d80b5005
MCC		 143OP_REQ_DEVLIST:
144 Retrieve the list of exported USB devices.
c8742cf0 145
d80b5005
MCC		 146+-----------+--------+------------+---------------------------------------------------+
147| Offset | Length | Value | Description |
148+===========+========+============+===================================================+
17af7932 149| 0 | 2 | | USBIP version |
d80b5005
MCC		 150+-----------+--------+------------+---------------------------------------------------+
151| 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB |
152| | | | devices. |
153+-----------+--------+------------+---------------------------------------------------+
154| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
155+-----------+--------+------------+---------------------------------------------------+
c8742cf0 156
d80b5005
MCC		 157OP_REP_DEVLIST:
158 Reply with the list of exported USB devices.
c8742cf0 159
d80b5005
MCC		 160+-----------+--------+------------+---------------------------------------------------+
161| Offset | Length | Value | Description |
162+===========+========+============+===================================================+
17af7932 163| 0 | 2 | | USBIP version |
d80b5005
MCC		 164+-----------+--------+------------+---------------------------------------------------+
165| 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. |
166+-----------+--------+------------+---------------------------------------------------+
167| 4 | 4 | 0x00000000 | Status: 0 for OK |
168+-----------+--------+------------+---------------------------------------------------+
169| 8 | 4 | n | Number of exported devices: 0 means no exported |
170| | | | devices. |
171+-----------+--------+------------+---------------------------------------------------+
172| 0x0C | | | From now on the exported n devices are described, |
173| | | | if any. If no devices are exported the message |
174| | | | ends with the previous "number of exported |
175| | | | devices" field. |
176+-----------+--------+------------+---------------------------------------------------+
177| | 256 | | path: Path of the device on the host exporting the|
178| | | | USB device, string closed with zero byte, e.g. |
179| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" |
180| | | | The unused bytes shall be filled with zero |
181| | | | bytes. |
182+-----------+--------+------------+---------------------------------------------------+
183| 0x10C | 32 | | busid: Bus ID of the exported device, string |
184| | | | closed with zero byte, e.g. "3-2". The unused |
185| | | | bytes shall be filled with zero bytes. |
186+-----------+--------+------------+---------------------------------------------------+
187| 0x12C | 4 | | busnum |
188+-----------+--------+------------+---------------------------------------------------+
189| 0x130 | 4 | | devnum |
190+-----------+--------+------------+---------------------------------------------------+
191| 0x134 | 4 | | speed |
192+-----------+--------+------------+---------------------------------------------------+
193| 0x138 | 2 | | idVendor |
194+-----------+--------+------------+---------------------------------------------------+
195| 0x13A | 2 | | idProduct |
196+-----------+--------+------------+---------------------------------------------------+
197| 0x13C | 2 | | bcdDevice |
198+-----------+--------+------------+---------------------------------------------------+
199| 0x13E | 1 | | bDeviceClass |
200+-----------+--------+------------+---------------------------------------------------+
201| 0x13F | 1 | | bDeviceSubClass |
202+-----------+--------+------------+---------------------------------------------------+
203| 0x140 | 1 | | bDeviceProtocol |
204+-----------+--------+------------+---------------------------------------------------+
205| 0x141 | 1 | | bConfigurationValue |
206+-----------+--------+------------+---------------------------------------------------+
207| 0x142 | 1 | | bNumConfigurations |
208+-----------+--------+------------+---------------------------------------------------+
209| 0x143 | 1 | | bNumInterfaces |
210+-----------+--------+------------+---------------------------------------------------+
211| 0x144 | | m_0 | From now on each interface is described, all |
17af7932
HZZ		 212| | | | together bNumInterfaces times, with the following |
213| | | | 4 fields: |
d80b5005
MCC		 214+-----------+--------+------------+---------------------------------------------------+
215| | 1 | | bInterfaceClass |
216+-----------+--------+------------+---------------------------------------------------+
217| 0x145 | 1 | | bInterfaceSubClass |
218+-----------+--------+------------+---------------------------------------------------+
219| 0x146 | 1 | | bInterfaceProtocol |
220+-----------+--------+------------+---------------------------------------------------+
221| 0x147 | 1 | | padding byte for alignment, shall be set to zero |
222+-----------+--------+------------+---------------------------------------------------+
223| 0xC + | | | The second exported USB device starts at i=1 |
17af7932 224| i*0x138 + | | | with the path field. |
d80b5005
MCC		 225| m_(i-1)*4 | | | |
226+-----------+--------+------------+---------------------------------------------------+
c8742cf0 227
d80b5005
MCC		 228OP_REQ_IMPORT:
229 Request to import (attach) a remote USB device.
c8742cf0 230
d80b5005
MCC		 231+-----------+--------+------------+---------------------------------------------------+
232| Offset | Length | Value | Description |
233+===========+========+============+===================================================+
17af7932 234| 0 | 2 | | USBIP version |
d80b5005
MCC		 235+-----------+--------+------------+---------------------------------------------------+
236| 2 | 2 | 0x8003 | Command code: import a remote USB device. |
237+-----------+--------+------------+---------------------------------------------------+
238| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
239+-----------+--------+------------+---------------------------------------------------+
240| 8 | 32 | | busid: the busid of the exported device on the |
241| | | | remote host. The possible values are taken |
242| | | | from the message field OP_REP_DEVLIST.busid. |
243| | | | A string closed with zero, the unused bytes |
244| | | | shall be filled with zeros. |
245+-----------+--------+------------+---------------------------------------------------+
c8742cf0 246
d80b5005
MCC		 247OP_REP_IMPORT:
248 Reply to import (attach) a remote USB device.
c8742cf0 249
d80b5005
MCC		 250+-----------+--------+------------+---------------------------------------------------+
251| Offset | Length | Value | Description |
252+===========+========+============+===================================================+
17af7932 253| 0 | 2 | | USBIP version |
d80b5005
MCC		 254+-----------+--------+------------+---------------------------------------------------+
255| 2 | 2 | 0x0003 | Reply code: Reply to import. |
256+-----------+--------+------------+---------------------------------------------------+
257| 4 | 4 | 0x00000000 | Status: |
258| | | | |
259| | | | - 0 for OK |
260| | | | - 1 for error |
261+-----------+--------+------------+---------------------------------------------------+
262| 8 | | | From now on comes the details of the imported |
263| | | | device, if the previous status field was OK (0), |
264| | | | otherwise the reply ends with the status field. |
265+-----------+--------+------------+---------------------------------------------------+
266| | 256 | | path: Path of the device on the host exporting the|
267| | | | USB device, string closed with zero byte, e.g. |
268| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" |
269| | | | The unused bytes shall be filled with zero |
270| | | | bytes. |
271+-----------+--------+------------+---------------------------------------------------+
272| 0x108 | 32 | | busid: Bus ID of the exported device, string |
273| | | | closed with zero byte, e.g. "3-2". The unused |
274| | | | bytes shall be filled with zero bytes. |
275+-----------+--------+------------+---------------------------------------------------+
276| 0x128 | 4 | | busnum |
277+-----------+--------+------------+---------------------------------------------------+
278| 0x12C | 4 | | devnum |
279+-----------+--------+------------+---------------------------------------------------+
280| 0x130 | 4 | | speed |
281+-----------+--------+------------+---------------------------------------------------+
282| 0x134 | 2 | | idVendor |
283+-----------+--------+------------+---------------------------------------------------+
284| 0x136 | 2 | | idProduct |
285+-----------+--------+------------+---------------------------------------------------+
286| 0x138 | 2 | | bcdDevice |
287+-----------+--------+------------+---------------------------------------------------+
288| 0x139 | 1 | | bDeviceClass |
289+-----------+--------+------------+---------------------------------------------------+
290| 0x13A | 1 | | bDeviceSubClass |
291+-----------+--------+------------+---------------------------------------------------+
292| 0x13B | 1 | | bDeviceProtocol |
293+-----------+--------+------------+---------------------------------------------------+
294| 0x13C | 1 | | bConfigurationValue |
295+-----------+--------+------------+---------------------------------------------------+
296| 0x13D | 1 | | bNumConfigurations |
297+-----------+--------+------------+---------------------------------------------------+
298| 0x13E | 1 | | bNumInterfaces |
299+-----------+--------+------------+---------------------------------------------------+
c8742cf0 300
17af7932
HZZ		 301The following four commands have a common basic header called
302'usbip_header_basic', and their headers, called 'usbip_header' (before
303transfer_buffer payload), have the same length, therefore paddings are needed.
c8742cf0 304
17af7932 305usbip_header_basic:
c8742cf0 306
17af7932
HZZ		 307+-----------+--------+---------------------------------------------------+
308| Offset | Length | Description |
309+===========+========+===================================================+
310| 0 | 4 | command |
311+-----------+--------+---------------------------------------------------+
312| 4 | 4 | seqnum: sequential number that identifies requests|
313| | | and corresponding responses; |
314| | | incremented per connection |
315+-----------+--------+---------------------------------------------------+
316| 8 | 4 | devid: specifies a remote USB device uniquely |
317| | | instead of busnum and devnum; |
318| | | for client (request), this value is |
319| | | ((busnum << 16) | devnum); |
320| | | for server (response), this shall be set to 0 |
321+-----------+--------+---------------------------------------------------+
322| 0xC | 4 | direction: |
323| | | |
324| | | - 0: USBIP_DIR_OUT |
325| | | - 1: USBIP_DIR_IN |
326| | | |
327| | | only used by client, for server this shall be 0 |
328+-----------+--------+---------------------------------------------------+
329| 0x10 | 4 | ep: endpoint number |
330| | | only used by client, for server this shall be 0; |
331| | | for UNLINK, this shall be 0 |
332+-----------+--------+---------------------------------------------------+
c8742cf0 333
17af7932
HZZ		 334USBIP_CMD_SUBMIT:
335 Submit an URB
c8742cf0 336
17af7932
HZZ		 337+-----------+--------+---------------------------------------------------+
338| Offset | Length | Description |
339+===========+========+===================================================+
340| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000001 |
341+-----------+--------+---------------------------------------------------+
342| 0x14 | 4 | transfer_flags: possible values depend on the |
8f36b3b4
SK		 343| | | USBIP_URB transfer_flags. |
344| | | Refer to include/uapi/linux/usbip.h and |
345| | | Documentation/driver-api/usb/URB.rst. |
346| | | Refer to usbip_pack_cmd_submit() and |
347| | | tweak_transfer_flags() in drivers/usb/usbip/ |
348| | | usbip_common.c. |
17af7932
HZZ		 349+-----------+--------+---------------------------------------------------+
350| 0x18 | 4 | transfer_buffer_length: |
351| | | use URB transfer_buffer_length |
352+-----------+--------+---------------------------------------------------+
353| 0x1C | 4 | start_frame: use URB start_frame; |
354| | | initial frame for ISO transfer; |
355| | | shall be set to 0 if not ISO transfer |
356+-----------+--------+---------------------------------------------------+
357| 0x20 | 4 | number_of_packets: number of ISO packets; |
358| | | shall be set to 0xffffffff if not ISO transfer |
359+-----------+--------+---------------------------------------------------+
360| 0x24 | 4 | interval: maximum time for the request on the |
361| | | server-side host controller |
362+-----------+--------+---------------------------------------------------+
363| 0x28 | 8 | setup: data bytes for USB setup, filled with |
364| | | zeros if not used. |
365+-----------+--------+---------------------------------------------------+
366| 0x30 | n | transfer_buffer. |
367| | | If direction is USBIP_DIR_OUT then n equals |
368| | | transfer_buffer_length; otherwise n equals 0. |
369| | | For ISO transfers the padding between each ISO |
370| | | packets is not transmitted. |
371+-----------+--------+---------------------------------------------------+
372| 0x30+n | m | iso_packet_descriptor |
373+-----------+--------+---------------------------------------------------+
c8742cf0 374
d80b5005
MCC		 375USBIP_RET_SUBMIT:
376 Reply for submitting an URB
c8742cf0 377
17af7932
HZZ		 378+-----------+--------+---------------------------------------------------+
379| Offset | Length | Description |
380+===========+========+===================================================+
381| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000003 |
382+-----------+--------+---------------------------------------------------+
383| 0x14 | 4 | status: zero for successful URB transaction, |
384| | | otherwise some kind of error happened. |
385+-----------+--------+---------------------------------------------------+
386| 0x18 | 4 | actual_length: number of URB data bytes; |
387| | | use URB actual_length |
388+-----------+--------+---------------------------------------------------+
389| 0x1C | 4 | start_frame: use URB start_frame; |
390| | | initial frame for ISO transfer; |
391| | | shall be set to 0 if not ISO transfer |
392+-----------+--------+---------------------------------------------------+
393| 0x20 | 4 | number_of_packets: number of ISO packets; |
394| | | shall be set to 0xffffffff if not ISO transfer |
395+-----------+--------+---------------------------------------------------+
396| 0x24 | 4 | error_count |
397+-----------+--------+---------------------------------------------------+
398| 0x28 | 8 | padding, shall be set to 0 |
399+-----------+--------+---------------------------------------------------+
400| 0x30 | n | transfer_buffer. |
401| | | If direction is USBIP_DIR_IN then n equals |
402| | | actual_length; otherwise n equals 0. |
403| | | For ISO transfers the padding between each ISO |
404| | | packets is not transmitted. |
405+-----------+--------+---------------------------------------------------+
406| 0x30+n | m | iso_packet_descriptor |
407+-----------+--------+---------------------------------------------------+
c8742cf0 408
d80b5005
MCC		 409USBIP_CMD_UNLINK:
410 Unlink an URB
c8742cf0 411
17af7932
HZZ		 412+-----------+--------+---------------------------------------------------+
413| Offset | Length | Description |
414+===========+========+===================================================+
415| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000002 |
416+-----------+--------+---------------------------------------------------+
417| 0x14 | 4 | unlink_seqnum, of the SUBMIT request to unlink |
418+-----------+--------+---------------------------------------------------+
419| 0x18 | 24 | padding, shall be set to 0 |
420+-----------+--------+---------------------------------------------------+
c8742cf0 421
d80b5005
MCC		 422USBIP_RET_UNLINK:
423 Reply for URB unlink
c8742cf0 424
17af7932
HZZ		 425+-----------+--------+---------------------------------------------------+
426| Offset | Length | Description |
427+===========+========+===================================================+
428| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000004 |
429+-----------+--------+---------------------------------------------------+
430| 0x14 | 4 | status: This is similar to the status of |
431| | | USBIP_RET_SUBMIT (share the same memory offset). |
432| | | When UNLINK is successful, status is -ECONNRESET; |
433| | | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT |
434| | | status is 0 |
435+-----------+--------+---------------------------------------------------+
436| 0x18 | 24 | padding, shall be set to 0 |
437+-----------+--------+---------------------------------------------------+
438
439EXAMPLE
440=======
441
442 The following data is captured from wire with Human Interface Devices (HID)
443 payload
444
445::
446
447 CmdIntrIN: 00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000
448 CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000
449 ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
450 RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
451 RetIntrIn: 00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
452 ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000
Linux 6.x block layer and io_uring tree(s)