About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / usbip_protocol.txt




Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.

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_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	
284	USBIP_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	
317	USBIP_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	
338	USBIP_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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.