aboutsummaryrefslogtreecommitdiffstats
path: root/drivers/usb/usbip/usbip_protocol.txt
diff options
context:
space:
mode:
Diffstat (limited to 'drivers/usb/usbip/usbip_protocol.txt')
-rw-r--r--drivers/usb/usbip/usbip_protocol.txt358
1 files changed, 358 insertions, 0 deletions
diff --git a/drivers/usb/usbip/usbip_protocol.txt b/drivers/usb/usbip/usbip_protocol.txt
new file mode 100644
index 000000000000..16b6fe27284c
--- /dev/null
+++ b/drivers/usb/usbip/usbip_protocol.txt
@@ -0,0 +1,358 @@
1PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
228 Jun 2011
3
4The USB/IP protocol follows a server/client architecture. The server exports the
5USB devices and the clients imports them. The device driver for the exported
6USB device runs on the client machine.
7
8The client may ask for the list of the exported USB devices. To get the list the
9client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
10packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
11in one or more pieces at the low level transport layer). The server sends back
12the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
13TCP/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
26Once the client knows the list of exported USB devices it may decide to use one
27of them. First the client opens a TCP/IP connection towards the server and
28sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
29import was successful the TCP/IP connection remains open and will be used
30to transfer the URB traffic between the client and the server. The client may
31send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
32USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
33server 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
87The fields are in network (big endian) byte order meaning that the most significant
88byte (MSB) is stored at the lowest address.
89
90
91OP_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
102OP_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
170OP_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
187OP_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
236USBIP_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_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
282
283
284USBIP_RET_SUBMIT: Reply for submitting an URB
285
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.
316
317USBIP_CMD_UNLINK: Unlink an URB
318
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.
337
338USBIP_RET_UNLINK: Reply for URB unlink
339
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.
generated by cgit v1.2.2 (git 2.25.0) at 2025-02-20 01:47:54 -0500