usbip_protocol.txt 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358
  1. PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
  2. 28 Jun 2011
  3. The USB/IP protocol follows a server/client architecture. The server exports the
  4. USB devices and the clients imports them. The device driver for the exported
  5. USB device runs on the client machine.
  6. The client may ask for the list of the exported USB devices. To get the list the
  7. client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
  8. packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
  9. in one or more pieces at the low level transport layer). The server sends back
  10. the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
  11. TCP/IP connection is closed.
  12. virtual host controller usb host
  13. "client" "server"
  14. (imports USB devices) (exports USB devices)
  15. | |
  16. | OP_REQ_DEVLIST |
  17. | ----------------------------------------------> |
  18. | |
  19. | OP_REP_DEVLIST |
  20. | <---------------------------------------------- |
  21. | |
  22. Once the client knows the list of exported USB devices it may decide to use one
  23. of them. First the client opens a TCP/IP connection towards the server and
  24. sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
  25. import was successful the TCP/IP connection remains open and will be used
  26. to transfer the URB traffic between the client and the server. The client may
  27. send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
  28. USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
  29. server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
  30. virtual host controller usb host
  31. "client" "server"
  32. (imports USB devices) (exports USB devices)
  33. | |
  34. | OP_REQ_IMPORT |
  35. | ----------------------------------------------> |
  36. | |
  37. | OP_REP_IMPORT |
  38. | <---------------------------------------------- |
  39. | |
  40. | |
  41. | USBIP_CMD_SUBMIT(seqnum = n) |
  42. | ----------------------------------------------> |
  43. | |
  44. | USBIP_RET_SUBMIT(seqnum = n) |
  45. | <---------------------------------------------- |
  46. | . |
  47. | : |
  48. | |
  49. | USBIP_CMD_SUBMIT(seqnum = m) |
  50. | ----------------------------------------------> |
  51. | |
  52. | USBIP_CMD_SUBMIT(seqnum = m+1) |
  53. | ----------------------------------------------> |
  54. | |
  55. | USBIP_CMD_SUBMIT(seqnum = m+2) |
  56. | ----------------------------------------------> |
  57. | |
  58. | USBIP_RET_SUBMIT(seqnum = m) |
  59. | <---------------------------------------------- |
  60. | |
  61. | USBIP_CMD_SUBMIT(seqnum = m+3) |
  62. | ----------------------------------------------> |
  63. | |
  64. | USBIP_RET_SUBMIT(seqnum = m+1) |
  65. | <---------------------------------------------- |
  66. | |
  67. | USBIP_CMD_SUBMIT(seqnum = m+4) |
  68. | ----------------------------------------------> |
  69. | |
  70. | USBIP_RET_SUBMIT(seqnum = m+2) |
  71. | <---------------------------------------------- |
  72. | . |
  73. | : |
  74. | |
  75. | USBIP_CMD_UNLINK |
  76. | ----------------------------------------------> |
  77. | |
  78. | USBIP_RET_UNLINK |
  79. | <---------------------------------------------- |
  80. | |
  81. The fields are in network (big endian) byte order meaning that the most significant
  82. byte (MSB) is stored at the lowest address.
  83. OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
  84. Offset | Length | Value | Description
  85. -----------+--------+------------+---------------------------------------------------
  86. 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
  87. -----------+--------+------------+---------------------------------------------------
  88. 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB
  89. | | | devices.
  90. -----------+--------+------------+---------------------------------------------------
  91. 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
  92. OP_REP_DEVLIST: Reply with 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 | 0x0005 | Reply code: The list of exported USB devices.
  98. -----------+--------+------------+---------------------------------------------------
  99. 4 | 4 | 0x00000000 | Status: 0 for OK
  100. -----------+--------+------------+---------------------------------------------------
  101. 8 | 4 | n | Number of exported devices: 0 means no exported
  102. | | | devices.
  103. -----------+--------+------------+---------------------------------------------------
  104. 0x0C | | | From now on the exported n devices are described,
  105. | | | if any. If no devices are exported the message
  106. | | | ends with the previous "number of exported
  107. | | | devices" field.
  108. -----------+--------+------------+---------------------------------------------------
  109. | 256 | | path: Path of the device on the host exporting the
  110. | | | USB device, string closed with zero byte, e.g.
  111. | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
  112. | | | The unused bytes shall be filled with zero
  113. | | | bytes.
  114. -----------+--------+------------+---------------------------------------------------
  115. 0x10C | 32 | | busid: Bus ID of the exported device, string
  116. | | | closed with zero byte, e.g. "3-2". The unused
  117. | | | bytes shall be filled with zero bytes.
  118. -----------+--------+------------+---------------------------------------------------
  119. 0x12C | 4 | | busnum
  120. -----------+--------+------------+---------------------------------------------------
  121. 0x130 | 4 | | devnum
  122. -----------+--------+------------+---------------------------------------------------
  123. 0x134 | 4 | | speed
  124. -----------+--------+------------+---------------------------------------------------
  125. 0x138 | 2 | | idVendor
  126. -----------+--------+------------+---------------------------------------------------
  127. 0x13A | 2 | | idProduct
  128. -----------+--------+------------+---------------------------------------------------
  129. 0x13C | 2 | | bcdDevice
  130. -----------+--------+------------+---------------------------------------------------
  131. 0x13E | 1 | | bDeviceClass
  132. -----------+--------+------------+---------------------------------------------------
  133. 0x13F | 1 | | bDeviceSubClass
  134. -----------+--------+------------+---------------------------------------------------
  135. 0x140 | 1 | | bDeviceProtocol
  136. -----------+--------+------------+---------------------------------------------------
  137. 0x141 | 1 | | bConfigurationValue
  138. -----------+--------+------------+---------------------------------------------------
  139. 0x142 | 1 | | bNumConfigurations
  140. -----------+--------+------------+---------------------------------------------------
  141. 0x143 | 1 | | bNumInterfaces
  142. -----------+--------+------------+---------------------------------------------------
  143. 0x144 | | m_0 | From now on each interface is described, all
  144. | | | together bNumInterfaces times, with the
  145. | | | the following 4 fields:
  146. -----------+--------+------------+---------------------------------------------------
  147. | 1 | | bInterfaceClass
  148. -----------+--------+------------+---------------------------------------------------
  149. 0x145 | 1 | | bInterfaceSubClass
  150. -----------+--------+------------+---------------------------------------------------
  151. 0x146 | 1 | | bInterfaceProtocol
  152. -----------+--------+------------+---------------------------------------------------
  153. 0x147 | 1 | | padding byte for alignment, shall be set to zero
  154. -----------+--------+------------+---------------------------------------------------
  155. 0xC + | | | The second exported USB device starts at i=1
  156. i*0x138 + | | | with the busid field.
  157. m_(i-1)*4 | | |
  158. OP_REQ_IMPORT: Request to import (attach) a remote USB device.
  159. Offset | Length | Value | Description
  160. -----------+--------+------------+---------------------------------------------------
  161. 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
  162. -----------+--------+------------+---------------------------------------------------
  163. 2 | 2 | 0x8003 | Command code: import a remote USB device.
  164. -----------+--------+------------+---------------------------------------------------
  165. 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
  166. -----------+--------+------------+---------------------------------------------------
  167. 8 | 32 | | busid: the busid of the exported device on the
  168. | | | remote host. The possible values are taken
  169. | | | from the message field OP_REP_DEVLIST.busid.
  170. | | | A string closed with zero, the unused bytes
  171. | | | shall be filled with zeros.
  172. -----------+--------+------------+---------------------------------------------------
  173. OP_REP_IMPORT: Reply to import (attach) a remote USB device.
  174. Offset | Length | Value | Description
  175. -----------+--------+------------+---------------------------------------------------
  176. 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
  177. -----------+--------+------------+---------------------------------------------------
  178. 2 | 2 | 0x0003 | Reply code: Reply to import.
  179. -----------+--------+------------+---------------------------------------------------
  180. 4 | 4 | 0x00000000 | Status: 0 for OK
  181. | | | 1 for error
  182. -----------+--------+------------+---------------------------------------------------
  183. 8 | | | From now on comes the details of the imported
  184. | | | device, if the previous status field was OK (0),
  185. | | | otherwise the reply ends with the status field.
  186. -----------+--------+------------+---------------------------------------------------
  187. | 256 | | path: Path of the device on the host exporting the
  188. | | | USB device, string closed with zero byte, e.g.
  189. | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
  190. | | | The unused bytes shall be filled with zero
  191. | | | bytes.
  192. -----------+--------+------------+---------------------------------------------------
  193. 0x108 | 32 | | busid: Bus ID of the exported device, string
  194. | | | closed with zero byte, e.g. "3-2". The unused
  195. | | | bytes shall be filled with zero bytes.
  196. -----------+--------+------------+---------------------------------------------------
  197. 0x128 | 4 | | busnum
  198. -----------+--------+------------+---------------------------------------------------
  199. 0x12C | 4 | | devnum
  200. -----------+--------+------------+---------------------------------------------------
  201. 0x130 | 4 | | speed
  202. -----------+--------+------------+---------------------------------------------------
  203. 0x134 | 2 | | idVendor
  204. -----------+--------+------------+---------------------------------------------------
  205. 0x136 | 2 | | idProduct
  206. -----------+--------+------------+---------------------------------------------------
  207. 0x138 | 2 | | bcdDevice
  208. -----------+--------+------------+---------------------------------------------------
  209. 0x139 | 1 | | bDeviceClass
  210. -----------+--------+------------+---------------------------------------------------
  211. 0x13A | 1 | | bDeviceSubClass
  212. -----------+--------+------------+---------------------------------------------------
  213. 0x13B | 1 | | bDeviceProtocol
  214. -----------+--------+------------+---------------------------------------------------
  215. 0x13C | 1 | | bConfigurationValue
  216. -----------+--------+------------+---------------------------------------------------
  217. 0x13D | 1 | | bNumConfigurations
  218. -----------+--------+------------+---------------------------------------------------
  219. 0x13E | 1 | | bNumInterfaces
  220. USBIP_CMD_SUBMIT: Submit an URB
  221. Offset | Length | Value | Description
  222. -----------+--------+------------+---------------------------------------------------
  223. 0 | 4 | 0x00000001 | command: Submit an URB
  224. -----------+--------+------------+---------------------------------------------------
  225. 4 | 4 | | seqnum: the sequence number of the URB to submit
  226. -----------+--------+------------+---------------------------------------------------
  227. 8 | 4 | | devid
  228. -----------+--------+------------+---------------------------------------------------
  229. 0xC | 4 | | direction: 0: USBIP_DIR_OUT
  230. | | | 1: USBIP_DIR_IN
  231. -----------+--------+------------+---------------------------------------------------
  232. 0x10 | 4 | | ep: endpoint number, possible values are: 0...15
  233. -----------+--------+------------+---------------------------------------------------
  234. 0x14 | 4 | | transfer_flags: possible values depend on the
  235. | | | URB transfer type, see below
  236. -----------+--------+------------+---------------------------------------------------
  237. 0x18 | 4 | | transfer_buffer_length
  238. -----------+--------+------------+---------------------------------------------------
  239. 0x1C | 4 | | start_frame: specify the selected frame to
  240. | | | transmit an ISO frame, ignored if URB_ISO_ASAP
  241. | | | is specified at transfer_flags
  242. -----------+--------+------------+---------------------------------------------------
  243. 0x20 | 4 | | number_of_packets: number of ISO packets
  244. -----------+--------+------------+---------------------------------------------------
  245. 0x24 | 4 | | interval: maximum time for the request on the
  246. | | | server-side host controller
  247. -----------+--------+------------+---------------------------------------------------
  248. 0x28 | 8 | | setup: data bytes for USB setup, filled with
  249. | | | zeros if not used
  250. -----------+--------+------------+---------------------------------------------------
  251. 0x30 | | | URB data. For ISO transfers the padding between
  252. | | | each ISO packets is not transmitted.
  253. Allowed transfer_flags | value | control | interrupt | bulk | isochronous
  254. -------------------------+------------+---------+-----------+----------+-------------
  255. URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no
  256. URB_ISO_ASAP | 0x00000002 | no | no | no | yes
  257. URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes
  258. URB_NO_FSBR | 0x00000020 | yes | no | no | no
  259. URB_ZERO_PACKET | 0x00000040 | no | no | only out | no
  260. URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes
  261. URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes
  262. URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes
  263. USBIP_RET_SUBMIT: Reply for submitting an URB
  264. Offset | Length | Value | Description
  265. -----------+--------+------------+---------------------------------------------------
  266. 0 | 4 | 0x00000003 | command
  267. -----------+--------+------------+---------------------------------------------------
  268. 4 | 4 | | seqnum: URB sequence number
  269. -----------+--------+------------+---------------------------------------------------
  270. 8 | 4 | | devid
  271. -----------+--------+------------+---------------------------------------------------
  272. 0xC | 4 | | direction: 0: USBIP_DIR_OUT
  273. | | | 1: USBIP_DIR_IN
  274. -----------+--------+------------+---------------------------------------------------
  275. 0x10 | 4 | | ep: endpoint number
  276. -----------+--------+------------+---------------------------------------------------
  277. 0x14 | 4 | | status: zero for successful URB transaction,
  278. | | | otherwise some kind of error happened.
  279. -----------+--------+------------+---------------------------------------------------
  280. 0x18 | 4 | n | actual_length: number of URB data bytes
  281. -----------+--------+------------+---------------------------------------------------
  282. 0x1C | 4 | | start_frame: for an ISO frame the actually
  283. | | | selected frame for transmit.
  284. -----------+--------+------------+---------------------------------------------------
  285. 0x20 | 4 | | number_of_packets
  286. -----------+--------+------------+---------------------------------------------------
  287. 0x24 | 4 | | error_count
  288. -----------+--------+------------+---------------------------------------------------
  289. 0x28 | 8 | | setup: data bytes for USB setup, filled with
  290. | | | zeros if not used
  291. -----------+--------+------------+---------------------------------------------------
  292. 0x30 | n | | URB data bytes. For ISO transfers the padding
  293. | | | between each ISO packets is not transmitted.
  294. USBIP_CMD_UNLINK: Unlink an URB
  295. Offset | Length | Value | Description
  296. -----------+--------+------------+---------------------------------------------------
  297. 0 | 4 | 0x00000002 | command: URB unlink command
  298. -----------+--------+------------+---------------------------------------------------
  299. 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so?
  300. -----------+--------+------------+---------------------------------------------------
  301. 8 | 4 | | devid
  302. -----------+--------+------------+---------------------------------------------------
  303. 0xC | 4 | | direction: 0: USBIP_DIR_OUT
  304. | | | 1: USBIP_DIR_IN
  305. -----------+--------+------------+---------------------------------------------------
  306. 0x10 | 4 | | ep: endpoint number: zero
  307. -----------+--------+------------+---------------------------------------------------
  308. 0x14 | 4 | | seqnum: the URB sequence number given previously
  309. | | | at USBIP_CMD_SUBMIT.seqnum field
  310. -----------+--------+------------+---------------------------------------------------
  311. 0x30 | n | | URB data bytes. For ISO transfers the padding
  312. | | | between each ISO packets is not transmitted.
  313. USBIP_RET_UNLINK: Reply for URB unlink
  314. Offset | Length | Value | Description
  315. -----------+--------+------------+---------------------------------------------------
  316. 0 | 4 | 0x00000004 | command: reply for the URB unlink command
  317. -----------+--------+------------+---------------------------------------------------
  318. 4 | 4 | | seqnum: the unlinked URB sequence number
  319. -----------+--------+------------+---------------------------------------------------
  320. 8 | 4 | | devid
  321. -----------+--------+------------+---------------------------------------------------
  322. 0xC | 4 | | direction: 0: USBIP_DIR_OUT
  323. | | | 1: USBIP_DIR_IN
  324. -----------+--------+------------+---------------------------------------------------
  325. 0x10 | 4 | | ep: endpoint number
  326. -----------+--------+------------+---------------------------------------------------
  327. 0x14 | 4 | | status: This is the value contained in the
  328. | | | urb->status in the URB completition handler.
  329. | | | FIXME: a better explanation needed.
  330. -----------+--------+------------+---------------------------------------------------
  331. 0x30 | n | | URB data bytes. For ISO transfers the padding
  332. | | | between each ISO packets is not transmitted.