GNU Linux-libre 4.19.264-gnu1
[releases.git] / 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.