]>
Commit | Line | Data |
---|---|---|
d80b5005 MCC |
1 | =============== |
2 | USB/IP protocol | |
3 | =============== | |
4 | ||
c8742cf0 MN |
5 | PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! |
6 | 28 Jun 2011 | |
7 | ||
8 | The USB/IP protocol follows a server/client architecture. The server exports the | |
9 | USB devices and the clients imports them. The device driver for the exported | |
10 | USB device runs on the client machine. | |
11 | ||
12 | The client may ask for the list of the exported USB devices. To get the list the | |
13 | client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST | |
14 | packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent | |
15 | in one or more pieces at the low level transport layer). The server sends back | |
16 | the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the | |
17 | TCP/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 | ||
32 | Once the client knows the list of exported USB devices it may decide to use one | |
33 | of them. First the client opens a TCP/IP connection towards the server and | |
34 | sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the | |
35 | import was successful the TCP/IP connection remains open and will be used | |
73e29189 | 36 | to transfer the URB traffic between the client and the server. The client may |
c8742cf0 MN |
37 | send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and |
38 | USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the | |
39 | server 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 | ||
95 | The fields are in network (big endian) byte order meaning that the most significant | |
96 | byte (MSB) is stored at the lowest address. | |
97 | ||
98 | ||
d80b5005 MCC |
99 | OP_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 |
113 | OP_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 |
184 | OP_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 |
203 | OP_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 |
257 | USBIP_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 |
317 | USBIP_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 |
355 | USBIP_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 |
384 | USBIP_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 | +-----------+--------+------------+---------------------------------------------------+ |