]> git.ipfire.org Git - thirdparty/kernel/stable.git/blame - Documentation/usb/usbip_protocol.txt
projects / thirdparty / kernel / stable.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 110
[thirdparty/kernel/stable.git] / Documentation / usb / usbip_protocol.txt
CommitLineData
d80b5005
MCC		 1===============
2USB/IP protocol
3===============
4
c8742cf0
MN		 5PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
628 Jun 2011
7
8The USB/IP protocol follows a server/client architecture. The server exports the
9USB devices and the clients imports them. The device driver for the exported
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
13client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
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
33of them. First the client opens a TCP/IP connection towards the server and
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 | : |
87 | |
88 | USBIP_CMD_UNLINK |
89 | ----------------------------------------------> |
90 | |
91 | USBIP_RET_UNLINK |
92 | <---------------------------------------------- |
93 | |
94
95The fields are in network (big endian) byte order meaning that the most significant
96byte (MSB) is stored at the lowest address.
97
98
d80b5005
MCC		 99OP_REQ_DEVLIST:
100 Retrieve the list of exported USB devices.
c8742cf0 101
d80b5005
MCC		 102+-----------+--------+------------+---------------------------------------------------+
103| Offset | Length | Value | Description |
104+===========+========+============+===================================================+
105| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 |
106+-----------+--------+------------+---------------------------------------------------+
107| 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB |
108| | | | devices. |
109+-----------+--------+------------+---------------------------------------------------+
110| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
111+-----------+--------+------------+---------------------------------------------------+
c8742cf0 112
d80b5005
MCC		 113OP_REP_DEVLIST:
114 Reply with the list of exported USB devices.
c8742cf0 115
d80b5005
MCC		 116+-----------+--------+------------+---------------------------------------------------+
117| Offset | Length | Value | Description |
118+===========+========+============+===================================================+
119| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.|
120+-----------+--------+------------+---------------------------------------------------+
121| 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. |
122+-----------+--------+------------+---------------------------------------------------+
123| 4 | 4 | 0x00000000 | Status: 0 for OK |
124+-----------+--------+------------+---------------------------------------------------+
125| 8 | 4 | n | Number of exported devices: 0 means no exported |
126| | | | devices. |
127+-----------+--------+------------+---------------------------------------------------+
128| 0x0C | | | From now on the exported n devices are described, |
129| | | | if any. If no devices are exported the message |
130| | | | ends with the previous "number of exported |
131| | | | devices" field. |
132+-----------+--------+------------+---------------------------------------------------+
133| | 256 | | path: Path of the device on the host exporting the|
134| | | | USB device, string closed with zero byte, e.g. |
135| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" |
136| | | | The unused bytes shall be filled with zero |
137| | | | bytes. |
138+-----------+--------+------------+---------------------------------------------------+
139| 0x10C | 32 | | busid: Bus ID of the exported device, string |
140| | | | closed with zero byte, e.g. "3-2". The unused |
141| | | | bytes shall be filled with zero bytes. |
142+-----------+--------+------------+---------------------------------------------------+
143| 0x12C | 4 | | busnum |
144+-----------+--------+------------+---------------------------------------------------+
145| 0x130 | 4 | | devnum |
146+-----------+--------+------------+---------------------------------------------------+
147| 0x134 | 4 | | speed |
148+-----------+--------+------------+---------------------------------------------------+
149| 0x138 | 2 | | idVendor |
150+-----------+--------+------------+---------------------------------------------------+
151| 0x13A | 2 | | idProduct |
152+-----------+--------+------------+---------------------------------------------------+
153| 0x13C | 2 | | bcdDevice |
154+-----------+--------+------------+---------------------------------------------------+
155| 0x13E | 1 | | bDeviceClass |
156+-----------+--------+------------+---------------------------------------------------+
157| 0x13F | 1 | | bDeviceSubClass |
158+-----------+--------+------------+---------------------------------------------------+
159| 0x140 | 1 | | bDeviceProtocol |
160+-----------+--------+------------+---------------------------------------------------+
161| 0x141 | 1 | | bConfigurationValue |
162+-----------+--------+------------+---------------------------------------------------+
163| 0x142 | 1 | | bNumConfigurations |
164+-----------+--------+------------+---------------------------------------------------+
165| 0x143 | 1 | | bNumInterfaces |
166+-----------+--------+------------+---------------------------------------------------+
167| 0x144 | | m_0 | From now on each interface is described, all |
168| | | | together bNumInterfaces times, with the |
169| | | | the following 4 fields: |
170+-----------+--------+------------+---------------------------------------------------+
171| | 1 | | bInterfaceClass |
172+-----------+--------+------------+---------------------------------------------------+
173| 0x145 | 1 | | bInterfaceSubClass |
174+-----------+--------+------------+---------------------------------------------------+
175| 0x146 | 1 | | bInterfaceProtocol |
176+-----------+--------+------------+---------------------------------------------------+
177| 0x147 | 1 | | padding byte for alignment, shall be set to zero |
178+-----------+--------+------------+---------------------------------------------------+
179| 0xC + | | | The second exported USB device starts at i=1 |
180| i*0x138 + | | | with the busid field. |
181| m_(i-1)*4 | | | |
182+-----------+--------+------------+---------------------------------------------------+
c8742cf0 183
d80b5005
MCC		 184OP_REQ_IMPORT:
185 Request to import (attach) a remote USB device.
c8742cf0 186
d80b5005
MCC		 187+-----------+--------+------------+---------------------------------------------------+
188| Offset | Length | Value | Description |
189+===========+========+============+===================================================+
190| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 |
191+-----------+--------+------------+---------------------------------------------------+
192| 2 | 2 | 0x8003 | Command code: import a remote USB device. |
193+-----------+--------+------------+---------------------------------------------------+
194| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 |
195+-----------+--------+------------+---------------------------------------------------+
196| 8 | 32 | | busid: the busid of the exported device on the |
197| | | | remote host. The possible values are taken |
198| | | | from the message field OP_REP_DEVLIST.busid. |
199| | | | A string closed with zero, the unused bytes |
200| | | | shall be filled with zeros. |
201+-----------+--------+------------+---------------------------------------------------+
c8742cf0 202
d80b5005
MCC		 203OP_REP_IMPORT:
204 Reply to import (attach) a remote USB device.
c8742cf0 205
d80b5005
MCC		 206+-----------+--------+------------+---------------------------------------------------+
207| Offset | Length | Value | Description |
208+===========+========+============+===================================================+
209| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 |
210+-----------+--------+------------+---------------------------------------------------+
211| 2 | 2 | 0x0003 | Reply code: Reply to import. |
212+-----------+--------+------------+---------------------------------------------------+
213| 4 | 4 | 0x00000000 | Status: |
214| | | | |
215| | | | - 0 for OK |
216| | | | - 1 for error |
217+-----------+--------+------------+---------------------------------------------------+
218| 8 | | | From now on comes the details of the imported |
219| | | | device, if the previous status field was OK (0), |
220| | | | otherwise the reply ends with the status field. |
221+-----------+--------+------------+---------------------------------------------------+
222| | 256 | | path: Path of the device on the host exporting the|
223| | | | USB device, string closed with zero byte, e.g. |
224| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" |
225| | | | The unused bytes shall be filled with zero |
226| | | | bytes. |
227+-----------+--------+------------+---------------------------------------------------+
228| 0x108 | 32 | | busid: Bus ID of the exported device, string |
229| | | | closed with zero byte, e.g. "3-2". The unused |
230| | | | bytes shall be filled with zero bytes. |
231+-----------+--------+------------+---------------------------------------------------+
232| 0x128 | 4 | | busnum |
233+-----------+--------+------------+---------------------------------------------------+
234| 0x12C | 4 | | devnum |
235+-----------+--------+------------+---------------------------------------------------+
236| 0x130 | 4 | | speed |
237+-----------+--------+------------+---------------------------------------------------+
238| 0x134 | 2 | | idVendor |
239+-----------+--------+------------+---------------------------------------------------+
240| 0x136 | 2 | | idProduct |
241+-----------+--------+------------+---------------------------------------------------+
242| 0x138 | 2 | | bcdDevice |
243+-----------+--------+------------+---------------------------------------------------+
244| 0x139 | 1 | | bDeviceClass |
245+-----------+--------+------------+---------------------------------------------------+
246| 0x13A | 1 | | bDeviceSubClass |
247+-----------+--------+------------+---------------------------------------------------+
248| 0x13B | 1 | | bDeviceProtocol |
249+-----------+--------+------------+---------------------------------------------------+
250| 0x13C | 1 | | bConfigurationValue |
251+-----------+--------+------------+---------------------------------------------------+
252| 0x13D | 1 | | bNumConfigurations |
253+-----------+--------+------------+---------------------------------------------------+
254| 0x13E | 1 | | bNumInterfaces |
255+-----------+--------+------------+---------------------------------------------------+
c8742cf0 256
d80b5005
MCC		 257USBIP_CMD_SUBMIT:
258 Submit an URB
c8742cf0 259
d80b5005
MCC		 260+-----------+--------+------------+---------------------------------------------------+
261| Offset | Length | Value | Description |
262+===========+========+============+===================================================+
263| 0 | 4 | 0x00000001 | command: Submit an URB |
264+-----------+--------+------------+---------------------------------------------------+
265| 4 | 4 | | seqnum: the sequence number of the URB to submit |
266+-----------+--------+------------+---------------------------------------------------+
267| 8 | 4 | | devid |
268+-----------+--------+------------+---------------------------------------------------+
269| 0xC | 4 | | direction: |
270| | | | |
271| | | | - 0: USBIP_DIR_OUT |
272| | | | - 1: USBIP_DIR_IN |
273+-----------+--------+------------+---------------------------------------------------+
274| 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 |
275+-----------+--------+------------+---------------------------------------------------+
276| 0x14 | 4 | | transfer_flags: possible values depend on the |
277| | | | URB transfer type, see below |
278+-----------+--------+------------+---------------------------------------------------+
279| 0x18 | 4 | | transfer_buffer_length |
280+-----------+--------+------------+---------------------------------------------------+
281| 0x1C | 4 | | start_frame: specify the selected frame to |
282| | | | transmit an ISO frame, ignored if URB_ISO_ASAP |
283| | | | is specified at transfer_flags |
284+-----------+--------+------------+---------------------------------------------------+
285| 0x20 | 4 | | number_of_packets: number of ISO packets |
286+-----------+--------+------------+---------------------------------------------------+
287| 0x24 | 4 | | interval: maximum time for the request on the |
288| | | | server-side host controller |
289+-----------+--------+------------+---------------------------------------------------+
290| 0x28 | 8 | | setup: data bytes for USB setup, filled with |
291| | | | zeros if not used |
292+-----------+--------+------------+---------------------------------------------------+
293| 0x30 | | | URB data. For ISO transfers the padding between |
294| | | | each ISO packets is not transmitted. |
295+-----------+--------+------------+---------------------------------------------------+
c8742cf0
MN		 296
297
d80b5005
MCC		 298 +-------------------------+------------+---------+-----------+----------+-------------+
299 | Allowed transfer_flags | value | control | interrupt | bulk | isochronous |
300 +=========================+============+=========+===========+==========+=============+
301 | URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no |
302 +-------------------------+------------+---------+-----------+----------+-------------+
303 | URB_ISO_ASAP | 0x00000002 | no | no | no | yes |
304 +-------------------------+------------+---------+-----------+----------+-------------+
305 | URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes |
306 +-------------------------+------------+---------+-----------+----------+-------------+
307 | URB_ZERO_PACKET | 0x00000040 | no | no | only out | no |
308 +-------------------------+------------+---------+-----------+----------+-------------+
309 | URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes |
310 +-------------------------+------------+---------+-----------+----------+-------------+
311 | URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes |
312 +-------------------------+------------+---------+-----------+----------+-------------+
313 | URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes |
314 +-------------------------+------------+---------+-----------+----------+-------------+
c8742cf0
MN		 315
316
d80b5005
MCC		 317USBIP_RET_SUBMIT:
318 Reply for submitting an URB
c8742cf0 319
d80b5005
MCC		 320+-----------+--------+------------+---------------------------------------------------+
321| Offset | Length | Value | Description |
322+===========+========+============+===================================================+
323| 0 | 4 | 0x00000003 | command |
324+-----------+--------+------------+---------------------------------------------------+
325| 4 | 4 | | seqnum: URB sequence number |
326+-----------+--------+------------+---------------------------------------------------+
327| 8 | 4 | | devid |
328+-----------+--------+------------+---------------------------------------------------+
329| 0xC | 4 | | direction: |
330| | | | |
331| | | | - 0: USBIP_DIR_OUT |
332| | | | - 1: USBIP_DIR_IN |
333+-----------+--------+------------+---------------------------------------------------+
334| 0x10 | 4 | | ep: endpoint number |
335+-----------+--------+------------+---------------------------------------------------+
336| 0x14 | 4 | | status: zero for successful URB transaction, |
337| | | | otherwise some kind of error happened. |
338+-----------+--------+------------+---------------------------------------------------+
339| 0x18 | 4 | n | actual_length: number of URB data bytes |
340+-----------+--------+------------+---------------------------------------------------+
341| 0x1C | 4 | | start_frame: for an ISO frame the actually |
342| | | | selected frame for transmit. |
343+-----------+--------+------------+---------------------------------------------------+
344| 0x20 | 4 | | number_of_packets |
345+-----------+--------+------------+---------------------------------------------------+
346| 0x24 | 4 | | error_count |
347+-----------+--------+------------+---------------------------------------------------+
348| 0x28 | 8 | | setup: data bytes for USB setup, filled with |
349| | | | zeros if not used |
350+-----------+--------+------------+---------------------------------------------------+
351| 0x30 | n | | URB data bytes. For ISO transfers the padding |
352| | | | between each ISO packets is not transmitted. |
353+-----------+--------+------------+---------------------------------------------------+
c8742cf0 354
d80b5005
MCC		 355USBIP_CMD_UNLINK:
356 Unlink an URB
c8742cf0 357
d80b5005
MCC		 358+-----------+--------+------------+---------------------------------------------------+
359| Offset | Length | Value | Description |
360+===========+========+============+===================================================+
361| 0 | 4 | 0x00000002 | command: URB unlink command |
362+-----------+--------+------------+---------------------------------------------------+
363| 4 | 4 | | seqnum: URB sequence number to unlink: |
364| | | | |
365| | | | FIXME: |
366| | | | is this so? |
367+-----------+--------+------------+---------------------------------------------------+
368| 8 | 4 | | devid |
369+-----------+--------+------------+---------------------------------------------------+
370| 0xC | 4 | | direction: |
371| | | | |
372| | | | - 0: USBIP_DIR_OUT |
373| | | | - 1: USBIP_DIR_IN |
374+-----------+--------+------------+---------------------------------------------------+
375| 0x10 | 4 | | ep: endpoint number: zero |
376+-----------+--------+------------+---------------------------------------------------+
377| 0x14 | 4 | | seqnum: the URB sequence number given previously |
378| | | | at USBIP_CMD_SUBMIT.seqnum field |
379+-----------+--------+------------+---------------------------------------------------+
380| 0x30 | n | | URB data bytes. For ISO transfers the padding |
381| | | | between each ISO packets is not transmitted. |
382+-----------+--------+------------+---------------------------------------------------+
c8742cf0 383
d80b5005
MCC		 384USBIP_RET_UNLINK:
385 Reply for URB unlink
c8742cf0 386
d80b5005
MCC		 387+-----------+--------+------------+---------------------------------------------------+
388| Offset | Length | Value | Description |
389+===========+========+============+===================================================+
390| 0 | 4 | 0x00000004 | command: reply for the URB unlink command |
391+-----------+--------+------------+---------------------------------------------------+
392| 4 | 4 | | seqnum: the unlinked URB sequence number |
393+-----------+--------+------------+---------------------------------------------------+
394| 8 | 4 | | devid |
395+-----------+--------+------------+---------------------------------------------------+
396| 0xC | 4 | | direction: |
397| | | | |
398| | | | - 0: USBIP_DIR_OUT |
399| | | | - 1: USBIP_DIR_IN |
400+-----------+--------+------------+---------------------------------------------------+
401| 0x10 | 4 | | ep: endpoint number |
402+-----------+--------+------------+---------------------------------------------------+
403| 0x14 | 4 | | status: This is the value contained in the |
404| | | | urb->status in the URB completition handler. |
405| | | | |
406| | | | FIXME: |
407| | | | a better explanation needed. |
408+-----------+--------+------------+---------------------------------------------------+
409| 0x30 | n | | URB data bytes. For ISO transfers the padding |
410| | | | between each ISO packets is not transmitted. |
411+-----------+--------+------------+---------------------------------------------------+
Mirror https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git