USB/IP 协议¶
架构¶
USB/IP 协议遵循服务器/客户端架构。服务器导出 USB 设备，客户端导入它们。导出 USB 设备的设备驱动程序在客户端机器上运行。
客户端可以请求导出 USB 设备的列表。为了获取列表，客户端打开与服务器的 TCP/IP 连接，并在 TCP/IP 连接之上发送 OP_REQ_DEVLIST 数据包（因此实际的 OP_REQ_DEVLIST 可能在底层传输层中以一个或多个片段发送）。服务器发回 OP_REP_DEVLIST 数据包，其中列出了导出的 USB 设备。最后，TCP/IP 连接关闭。
virtual host controller usb host
"client" "server"
(imports USB devices) (exports USB devices)
| |
| OP_REQ_DEVLIST |
| ----------------------------------------------> |
| |
| OP_REP_DEVLIST |
| <---------------------------------------------- |
| |
一旦客户端知道导出 USB 设备的列表，它就可以决定使用其中一个。首先，客户端打开与服务器的 TCP/IP 连接并发送 OP_REQ_IMPORT 数据包。服务器回复 OP_REP_IMPORT。如果导入成功，则 TCP/IP 连接保持打开状态，并将用于在客户端和服务器之间传输 URB 流量。客户端可以发送两种类型的数据包：USBIP_CMD_SUBMIT 以提交 URB，以及 USBIP_CMD_UNLINK 以取消链接先前提交的 URB。服务器的答案可能是 USBIP_RET_SUBMIT 和 USBIP_RET_UNLINK 分别。
virtual host controller usb host
"client" "server"
(imports USB devices) (exports USB devices)
| |
| OP_REQ_IMPORT |
| ----------------------------------------------> |
| |
| OP_REP_IMPORT |
| <---------------------------------------------- |
| |
| |
| USBIP_CMD_SUBMIT(seqnum = n) |
| ----------------------------------------------> |
| |
| USBIP_RET_SUBMIT(seqnum = n) |
| <---------------------------------------------- |
| . |
| : |
| |
| USBIP_CMD_SUBMIT(seqnum = m) |
| ----------------------------------------------> |
| |
| USBIP_CMD_SUBMIT(seqnum = m+1) |
| ----------------------------------------------> |
| |
| USBIP_CMD_SUBMIT(seqnum = m+2) |
| ----------------------------------------------> |
| |
| USBIP_RET_SUBMIT(seqnum = m) |
| <---------------------------------------------- |
| |
| USBIP_CMD_SUBMIT(seqnum = m+3) |
| ----------------------------------------------> |
| |
| USBIP_RET_SUBMIT(seqnum = m+1) |
| <---------------------------------------------- |
| |
| USBIP_CMD_SUBMIT(seqnum = m+4) |
| ----------------------------------------------> |
| |
| USBIP_RET_SUBMIT(seqnum = m+2) |
| <---------------------------------------------- |
| . |
| : |
对于 UNLINK，请注意，在成功执行 USBIP_RET_UNLINK 后，取消链接的 URB 提交将没有相应的 USBIP_RET_SUBMIT（这在 drivers/usb/usbip/stub_rx.c 的函数 stub_recv_cmd_unlink 中进行了解释）。
virtual host controller usb host
"client" "server"
(imports USB devices) (exports USB devices)
| |
| USBIP_CMD_SUBMIT(seqnum = p) |
| ----------------------------------------------> |
| |
| USBIP_CMD_UNLINK |
| (seqnum = p+1, unlink_seqnum = p) |
| ----------------------------------------------> |
| |
| USBIP_RET_UNLINK |
| (seqnum = p+1, status = -ECONNRESET) |
| <---------------------------------------------- |
| |
| Note: No USBIP_RET_SUBMIT(seqnum = p) |
| <--X---X---X---X---X---X---X---X---X---X---X--- |
| . |
| : |
| |
| USBIP_CMD_SUBMIT(seqnum = q) |
| ----------------------------------------------> |
| |
| USBIP_RET_SUBMIT(seqnum = q) |
| <---------------------------------------------- |
| |
| USBIP_CMD_UNLINK |
| (seqnum = q+1, unlink_seqnum = q) |
| ----------------------------------------------> |
| |
| USBIP_RET_UNLINK |
| (seqnum = q+1, status = 0) |
| <---------------------------------------------- |
| |
字段采用网络（大端）字节顺序，这意味着最高有效字节 (MSB) 存储在最低地址。
协议版本¶
已记录的 USBIP 版本为 v1.1.1。此版本在消息头中的二进制表示形式为 0x0111。
这在 tools/usb/usbip/configure.ac 中定义。
消息格式¶
- OP_REQ_DEVLIST
检索导出 USB 设备的列表。
偏移量 |
长度 |
值 |
描述 |
|---|---|---|---|
0 |
2 |
USBIP 版本 |
|
2 |
2 |
0x8005 |
命令代码：检索导出 USB 设备的列表。 |
4 |
4 |
0x00000000 |
状态：未使用，应设置为 0 |
- OP_REP_DEVLIST
回复导出 USB 设备的列表。
偏移量 |
长度 |
值 |
描述 |
|---|---|---|---|
0 |
2 |
USBIP 版本 |
|
2 |
2 |
0x0005 |
回复代码：导出 USB 设备的列表。 |
4 |
4 |
0x00000000 |
状态：0 表示 OK |
8 |
4 |
n |
导出设备的数量：0 表示没有导出设备。 |
0x0C |
从现在开始，将描述导出的 n 个设备（如果存在）。如果没有导出设备，则消息以之前的“导出设备数量”字段结束。 |
||
256 |
path：在导出 USB 设备的宿主机上设备的路径，以零字节结尾的字符串，例如“/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2”。未使用的字节应填充零字节。 |
||
0x10C |
32 |
busid：导出设备的总线 ID，以零字节结尾的字符串，例如“3-2”。未使用的字节应填充零字节。 |
|
0x12C |
4 |
busnum |
|
0x130 |
4 |
devnum |
|
0x134 |
4 |
speed |
|
0x138 |
2 |
idVendor |
|
0x13A |
2 |
idProduct |
|
0x13C |
2 |
bcdDevice |
|
0x13E |
1 |
bDeviceClass |
|
0x13F |
1 |
bDeviceSubClass |
|
0x140 |
1 |
bDeviceProtocol |
|
0x141 |
1 |
bConfigurationValue |
|
0x142 |
1 |
bNumConfigurations |
|
0x143 |
1 |
bNumInterfaces |
|
0x144 |
m_0 |
从现在开始，每个接口都将被描述，总共 bNumInterfaces 次，包含以下 4 个字段 |
|
1 |
bInterfaceClass |
||
0x145 |
1 |
bInterfaceSubClass |
|
0x146 |
1 |
bInterfaceProtocol |
|
0x147 |
1 |
对齐的填充字节，应设置为零 |
|
0xC + i*0x138 + m_(i-1)*4 |
第二个导出的 USB 设备从 i=1 开始，包含 path 字段。 |
- OP_REQ_IMPORT
请求导入（连接）远程 USB 设备。
偏移量 |
长度 |
值 |
描述 |
|---|---|---|---|
0 |
2 |
USBIP 版本 |
|
2 |
2 |
0x8003 |
命令代码：导入远程 USB 设备。 |
4 |
4 |
0x00000000 |
状态：未使用，应设置为 0 |
8 |
32 |
busid：远程主机上导出设备的 busid。可能的值取自消息字段 OP_REP_DEVLIST.busid。以零结尾的字符串，未使用的字节应填充零。 |
- OP_REP_IMPORT
回复导入（连接）远程 USB 设备。
偏移量 |
长度 |
值 |
描述 |
|---|---|---|---|
0 |
2 |
USBIP 版本 |
|
2 |
2 |
0x0003 |
回复代码：回复导入。 |
4 |
4 |
0x00000000 |
状态
|
8 |
从现在开始，将是导入设备的详细信息，如果之前的状态字段为 OK (0)，否则回复以状态字段结束。 |
||
256 |
path：在导出 USB 设备的宿主机上设备的路径，以零字节结尾的字符串，例如“/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2”。未使用的字节应填充零字节。 |
||
0x108 |
32 |
busid：导出设备的总线 ID，以零字节结尾的字符串，例如“3-2”。未使用的字节应填充零字节。 |
|
0x128 |
4 |
busnum |
|
0x12C |
4 |
devnum |
|
0x130 |
4 |
speed |
|
0x134 |
2 |
idVendor |
|
0x136 |
2 |
idProduct |
|
0x138 |
2 |
bcdDevice |
|
0x13A |
1 |
bDeviceClass |
|
0x13B |
1 |
bDeviceSubClass |
|
0x13C |
1 |
bDeviceProtocol |
|
0x13D |
1 |
bConfigurationValue |
|
0x13E |
1 |
bNumConfigurations |
|
0x13F |
1 |
bNumInterfaces |
以下四个命令有一个通用的基本标头，称为“usbip_header_basic”，并且它们的标头，称为“usbip_header”（在 transfer_buffer 有效负载之前），具有相同的长度，因此需要填充。
usbip_header_basic
偏移量 |
长度 |
描述 |
|---|---|---|
0 |
4 |
command |
4 |
4 |
seqnum：标识请求和相应响应的序列号；每次连接递增 |
8 |
4 |
devid：唯一指定远程 USB 设备，而不是 busnum 和 devnum；对于客户端（请求），此值为 ((busnum << 16) | devnum)；对于服务器（响应），应设置为 0 |
0xC |
4 |
direction
仅由客户端使用，对于服务器，此值应为 0 |
0x10 |
4 |
ep：端点号仅由客户端使用，对于服务器，此值应为 0；对于 UNLINK，此值应为 0 |
- USBIP_CMD_SUBMIT
提交 URB
偏移量 |
长度 |
描述 |
|---|---|---|
0 |
20 |
usbip_header_basic，“command”应为 0x00000001 |
0x14 |
4 |
transfer_flags：可能的值取决于 USBIP_URB transfer_flags。请参阅 include/uapi/linux/usbip.h 和 USB 请求块 (URB)。请参阅 drivers/usb/usbip/ usbip_common.c 中的 usbip_pack_cmd_submit() 和 tweak_transfer_flags()。 |
0x18 |
4 |
transfer_buffer_length：使用 URB transfer_buffer_length |
0x1C |
4 |
start_frame：使用 URB start_frame；ISO 传输的初始帧；如果不是 ISO 传输，则应设置为 0 |
0x20 |
4 |
number_of_packets：ISO 数据包的数量；如果不是 ISO 传输，则应设置为 0xffffffff |
0x24 |
4 |
interval：服务器端主机控制器上请求的最大时间 |
0x28 |
8 |
setup：USB 设置的数据字节，如果未使用，则填充零。 |
0x30 |
n |
transfer_buffer。如果 direction 为 USBIP_DIR_OUT，则 n 等于 transfer_buffer_length；否则 n 等于 0。对于 ISO 传输，每个 ISO 数据包之间的填充不会传输。 |
0x30+n |
m |
iso_packet_descriptor |
- USBIP_RET_SUBMIT
提交 URB 的回复
偏移量 |
长度 |
描述 |
|---|---|---|
0 |
20 |
usbip_header_basic，“command”应为 0x00000003 |
0x14 |
4 |
status：零表示成功的 URB 事务，否则会发生某种错误。 |
0x18 |
4 |
actual_length：URB 数据字节数；使用 URB actual_length |
0x1C |
4 |
start_frame：使用 URB start_frame；ISO 传输的初始帧；如果不是 ISO 传输，则应设置为 0 |
0x20 |
4 |
number_of_packets：ISO 数据包的数量；如果不是 ISO 传输，则应设置为 0xffffffff |
0x24 |
4 |
error_count |
0x28 |
8 |
padding，应设置为 0 |
0x30 |
n |
transfer_buffer。如果 direction 为 USBIP_DIR_IN，则 n 等于 actual_length；否则 n 等于 0。对于 ISO 传输，每个 ISO 数据包之间的填充不会传输。 |
0x30+n |
m |
iso_packet_descriptor |
- USBIP_CMD_UNLINK
取消链接 URB
偏移量 |
长度 |
描述 |
|---|---|---|
0 |
20 |
usbip_header_basic，“command”应为 0x00000002 |
0x14 |
4 |
unlink_seqnum，要取消链接的 SUBMIT 请求的序列号 |
0x18 |
24 |
padding，应设置为 0 |
- USBIP_RET_UNLINK
URB 取消链接的回复
偏移量 |
长度 |
描述 |
|---|---|---|
0 |
20 |
usbip_header_basic，“command”应为 0x00000004 |
0x14 |
4 |
status：这与 USBIP_RET_SUBMIT 的状态类似（共享相同的内存偏移量）。当 UNLINK 成功时，status 为 -ECONNRESET；当 USBIP_CMD_UNLINK 在 USBIP_RET_SUBMIT 之后时，status 为 0 |
0x18 |
24 |
padding，应设置为 0 |
示例¶
以下数据是从 Human Interface Devices (HID) 有效负载的线路中捕获的
CmdIntrIN: 00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000
CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000
ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
RetIntrIn: 00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000