| blob | 16b6fe27284cc1b1184ed6eb36dcf57f5f9eb5eb |
1 PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
2 28 Jun 2011
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.
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.
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 | |
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.
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 | |
87 The fields are in network (big endian) byte order meaning that the most significant
88 byte (MSB) is stored at the lowest address.
91 OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
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
102 OP_REP_DEVLIST: Reply with the list of exported USB devices.
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 | | |
170 OP_REQ_IMPORT: Request to import (attach) a remote USB device.
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 -----------+--------+------------+---------------------------------------------------
187 OP_REP_IMPORT: Reply to import (attach) a remote USB device.
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
236 USBIP_CMD_SUBMIT: Submit an URB
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.
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_NO_FSBR | 0x00000020 | yes | no | no | no
278 URB_ZERO_PACKET | 0x00000040 | no | no | only out | no
279 URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes
280 URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes
281 URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes
284 USBIP_RET_SUBMIT: Reply for submitting an URB
286 Offset | Length | Value | Description
287 -----------+--------+------------+---------------------------------------------------
288 0 | 4 | 0x00000003 | command
289 -----------+--------+------------+---------------------------------------------------
290 4 | 4 | | seqnum: URB sequence number
291 -----------+--------+------------+---------------------------------------------------
292 8 | 4 | | devid
293 -----------+--------+------------+---------------------------------------------------
294 0xC | 4 | | direction: 0: USBIP_DIR_OUT
295 | | | 1: USBIP_DIR_IN
296 -----------+--------+------------+---------------------------------------------------
297 0x10 | 4 | | ep: endpoint number
298 -----------+--------+------------+---------------------------------------------------
299 0x14 | 4 | | status: zero for successful URB transaction,
300 | | | otherwise some kind of error happened.
301 -----------+--------+------------+---------------------------------------------------
302 0x18 | 4 | n | actual_length: number of URB data bytes
303 -----------+--------+------------+---------------------------------------------------
304 0x1C | 4 | | start_frame: for an ISO frame the actually
305 | | | selected frame for transmit.
306 -----------+--------+------------+---------------------------------------------------
307 0x20 | 4 | | number_of_packets
308 -----------+--------+------------+---------------------------------------------------
309 0x24 | 4 | | error_count
310 -----------+--------+------------+---------------------------------------------------
311 0x28 | 8 | | setup: data bytes for USB setup, filled with
312 | | | zeros if not used
313 -----------+--------+------------+---------------------------------------------------
314 0x30 | n | | URB data bytes. For ISO transfers the padding
315 | | | between each ISO packets is not transmitted.
317 USBIP_CMD_UNLINK: Unlink an URB
319 Offset | Length | Value | Description
320 -----------+--------+------------+---------------------------------------------------
321 0 | 4 | 0x00000002 | command: URB unlink command
322 -----------+--------+------------+---------------------------------------------------
323 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so?
324 -----------+--------+------------+---------------------------------------------------
325 8 | 4 | | devid
326 -----------+--------+------------+---------------------------------------------------
327 0xC | 4 | | direction: 0: USBIP_DIR_OUT
328 | | | 1: USBIP_DIR_IN
329 -----------+--------+------------+---------------------------------------------------
330 0x10 | 4 | | ep: endpoint number: zero
331 -----------+--------+------------+---------------------------------------------------
332 0x14 | 4 | | seqnum: the URB sequence number given previously
333 | | | at USBIP_CMD_SUBMIT.seqnum field
334 -----------+--------+------------+---------------------------------------------------
335 0x30 | n | | URB data bytes. For ISO transfers the padding
336 | | | between each ISO packets is not transmitted.
338 USBIP_RET_UNLINK: Reply for URB unlink
340 Offset | Length | Value | Description
341 -----------+--------+------------+---------------------------------------------------
342 0 | 4 | 0x00000004 | command: reply for the URB unlink command
343 -----------+--------+------------+---------------------------------------------------
344 4 | 4 | | seqnum: the unlinked URB sequence number
345 -----------+--------+------------+---------------------------------------------------
346 8 | 4 | | devid
347 -----------+--------+------------+---------------------------------------------------
348 0xC | 4 | | direction: 0: USBIP_DIR_OUT
349 | | | 1: USBIP_DIR_IN
350 -----------+--------+------------+---------------------------------------------------
351 0x10 | 4 | | ep: endpoint number
352 -----------+--------+------------+---------------------------------------------------
353 0x14 | 4 | | status: This is the value contained in the
354 | | | urb->status in the URB completition handler.
355 | | | FIXME: a better explanation needed.
356 -----------+--------+------------+---------------------------------------------------
357 0x30 | n | | URB data bytes. For ISO transfers the padding
358 | | | between each ISO packets is not transmitted.