usbmon¶
简介¶
小写名称“usbmon”指的是内核中的一个功能，用于收集 USB 总线上的 I/O 跟踪信息。此功能类似于 tcpdump(1) 或 Ethereal 等网络监控工具使用的包套接字。类似地，像 usbdump 或 USBMon（大写字母）这样的工具预计将用于检查 usbmon 生成的原始跟踪信息。
usbmon 报告外设特定驱动程序向主机控制器驱动程序 (HCD) 发出的请求。因此，如果 HCD 有缺陷，usbmon 报告的跟踪信息可能与总线事务不完全对应。这与 tcpdump 的情况相同。
目前实现了两种 API：“文本”和“二进制”。二进制 API 通过 /dev 命名空间中的字符设备提供，并且是 ABI。文本 API 自 2.6.35 版本起已被弃用，但为方便起见仍可使用。
如何使用 usbmon 收集原始文本跟踪信息¶
与包套接字不同，usbmon 有一个以文本格式提供跟踪信息的接口。这有两个用途。首先，它在更复杂的格式确定之前，作为工具的通用跟踪交换格式。其次，在没有工具的情况下，人们也可以阅读它。
要收集原始文本跟踪信息，请执行以下步骤。
1. 准备¶
挂载 debugfs（它必须在你的内核配置中启用），并加载 usbmon 模块（如果它作为模块构建）。如果 usbmon 内置于内核中，则跳过第二步。
# mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon
#
验证总线套接字是否存在
# ls /sys/kernel/debug/usb/usbmon
0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
#
现在你可以选择使用套接字 '0u'（捕获所有总线上的数据包），然后跳到步骤 #3；或者通过步骤 #2 找到你的设备使用的总线。这可以过滤掉持续通信的烦人设备。
2. 查找连接到所需设备的总线¶
运行 “cat /sys/kernel/debug/usb/devices”，并找到与设备对应的 T 行。通常通过查找供应商字符串来完成。如果你有许多类似设备，拔掉一个并比较两次 /sys/kernel/debug/usb/devices 的输出。T 行将包含总线号。
示例
T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0557 ProdID=2004 Rev= 1.00
S: Manufacturer=ATEN
S: Product=UC100KM V2.00
“Bus=03” 表示是总线 3。或者，你可以查看 “lsusb” 的输出，并从相应的行获取总线号。例如：
Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
3. 启动 ‘cat’¶
# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
监听单个总线，否则，若要监听所有总线，请键入
# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
此过程将一直读取，直到被终止。自然地，输出可以重定向到所需位置。这是首选，因为它会非常长。
4. 在 USB 总线上执行所需操作¶
在这里你可以做一些产生流量的操作：插入闪存盘、复制文件、控制网络摄像头等。
5. 杀死 cat 进程¶
通常通过键盘中断（Control-C）完成。
此时，输出文件（本例中为 /tmp/1.mon.out）可以保存、通过电子邮件发送或用文本编辑器检查。在最后一种情况下，请确保文件大小对于你喜欢的编辑器来说不会过大。
原始文本数据格式¶
目前支持两种格式：原始的“1t”格式和“1u”格式。“1t”格式在内核 2.6.21 中已弃用。“1u”格式添加了一些字段，例如 ISO 帧描述符、间隔等。它生成的行略长，但除此之外是“1t”格式的完美超集。
如果需要在程序中区分这两种格式，请查看“address”字段（见下文），其中“1u”格式添加了总线号。如果存在 2 个冒号，则是“1t”格式，否则是“1u”。
任何文本格式的数据都由事件流组成，例如 URB 提交、URB 回调、提交错误。每个事件都是一行文本，由空格分隔的单词组成。单词的数量或位置可能取决于事件类型，但有一组单词是所有类型共有的。
以下是单词列表，从左到右：
URB 标签。这用于标识 URB，通常是 URB 结构在内核中的十六进制地址，但也可以是序列号或任何其他合理的唯一字符串。
时间戳，单位为微秒，一个十进制数。时间戳的分辨率取决于可用时钟，因此它可能远低于微秒（例如，如果实现使用 jiffies）。
事件类型。此类型指的是事件的格式，而不是 URB 类型。可用类型有：S - 提交 (submission)，C - 回调 (callback)，E - 提交错误 (submission error)。
“地址”字段（以前称为“管道”）。它由四个用冒号分隔的字段组成：URB 类型和方向、总线号、设备地址、端点号。类型和方向通过两个字节编码如下：
Ci
Co
控制输入和输出
Zi
Zo
同步输入和输出
Ii
Io
中断输入和输出
Bi
Bo
批量输入和输出
总线号、设备地址和端点是十进制数字，但为了方便人类阅读，它们可能带有前导零。
URB 状态字段。它要么是一个字母，要么是几个用冒号分隔的数字：URB 状态、间隔、起始帧和错误计数。与“地址”字段不同，除了状态之外的所有字段都是可选的。间隔仅针对中断和同步 URB 打印。起始帧仅针对同步 URB 打印。错误计数仅针对同步回调事件打印。
状态字段是一个十进制数字，有时为负数，它表示 URB 的“status”字段。此字段对于提交没有意义，但无论如何都存在，以帮助脚本进行解析。当发生错误时，该字段包含错误代码。
在提交控制包的情况下，此字段包含一个 Setup 标签而不是一组数字。很容易判断 Setup 标签是否存在，因为它永远不是一个数字。因此，如果脚本在此字段中找到一组数字，它们会继续读取数据长度（同步 URB 除外）。如果它们找到其他内容，例如字母，则在读取数据长度或同步描述符之前读取设置包。
Setup 包（如果存在）由 5 个字段组成：bmRequestType、bRequest、wValue、wIndex、wLength 各一个，如 USB 2.0 规范所述。如果 Setup 标签是“s”，这些字段可以安全地解码。否则，Setup 包存在但未被捕获，并且字段包含填充物。
同步帧描述符的数量和描述符本身。如果一个同步传输事件有一组描述符，则首先打印 URB 中描述符的总数，然后每个描述符一个单词，最多总共 5 个。每个单词由 3 个冒号分隔的十进制数字组成，分别表示状态、偏移量和长度。对于提交，报告初始长度。对于回调，报告实际长度。
数据长度。对于提交，这是请求的长度。对于回调，这是实际的长度。
数据标签。usbmon 可能不总是捕获数据，即使长度不为零。数据字段仅在此标签为“=”时才存在。
数据字段以大端十六进制格式跟随。请注意，它们不是机器字，而实际上只是为了方便阅读而将字节流拆分成单词。因此，最后一个单词可能包含一到四个字节。收集到的数据长度是有限的，并且可能小于数据长度字段中报告的数据长度。在同步输入 (Zi) 完成的情况下，如果接收到的数据在缓冲区中是稀疏的，则收集到的数据长度可能大于数据长度值（因为数据长度仅计算接收到的字节，而数据字段包含整个传输缓冲区）。
示例
获取端口状态的输入控制传输
d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
向地址为 5 的存储设备发送 SCSI 命令 0x28 (READ_10) 的 31 字节批量封装的输出批量传输
dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
原始二进制格式和 API¶
API 的整体架构与上面基本相同，只是事件以二进制格式传递。每个事件都以以下结构发送（其名称是虚构的，以便我们引用它）
struct usbmon_packet {
u64 id; /* 0: URB ID - from submission to callback */
unsigned char type; /* 8: Same as text; extensible. */
unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */
unsigned char epnum; /* Endpoint number and transfer direction */
unsigned char devnum; /* Device address */
u16 busnum; /* 12: Bus number */
char flag_setup; /* 14: Same as text */
char flag_data; /* 15: Same as text; Binary zero is OK. */
s64 ts_sec; /* 16: gettimeofday */
s32 ts_usec; /* 24: gettimeofday */
int status; /* 28: */
unsigned int length; /* 32: Length of data (submitted or actual) */
unsigned int len_cap; /* 36: Delivered length */
union { /* 40: */
unsigned char setup[SETUP_LEN]; /* Only for Control S-type */
struct iso_rec { /* Only for ISO */
int error_count;
int numdesc;
} iso;
} s;
int interval; /* 48: Only for Interrupt and ISO */
int start_frame; /* 52: For ISO */
unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */
unsigned int ndesc; /* 60: Actual number of ISO descriptors */
}; /* 64 total length */
这些事件可以通过 read(2)、ioctl(2) 从字符设备接收，或者通过 mmap 访问缓冲区。但是，出于兼容性原因，read(2) 仅返回前 48 字节。
字符设备通常称为 /dev/usbmonN，其中 N 是 USB 总线号。数字零（/dev/usbmon0）是特殊的，表示“所有总线”。请注意，具体的命名策略由您的 Linux 发行版设置。
如果您手动创建 /dev/usbmon0，请确保它由 root 拥有并具有 0600 权限。否则，非特权用户将能够窥探键盘流量。
以下 ioctl 调用可用，其中 MON_IOC_MAGIC 为 0x92
MON_IOCQ_URB_LEN，定义为 _IO(MON_IOC_MAGIC, 1)
此调用返回下一个事件中的数据长度。请注意，大多数事件不包含数据，因此如果此调用返回零，并不意味着没有可用事件。
MON_IOCG_STATS，定义为 _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
参数是指向以下结构的指针
struct mon_bin_stats {
u32 queued;
u32 dropped;
};
成员“queued”指的是当前在缓冲区中排队的事件数量（而不是自上次重置以来处理的事件数量）。
成员“dropped”是自上次调用 MON_IOCG_STATS 以来丢失的事件数量。
MON_IOCT_RING_SIZE，定义为 _IO(MON_IOC_MAGIC, 4)
此调用设置缓冲区大小。参数是字节大小。大小可能会向下舍入到下一个块（或页）。如果请求的大小超出此内核的[未指定]范围，则调用将失败并返回 -EINVAL。
MON_IOCQ_RING_SIZE，定义为 _IO(MON_IOC_MAGIC, 5)
此调用返回缓冲区当前大小，单位为字节。
MON_IOCX_GET，定义为 _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) MON_IOCX_GETX，定义为 _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)
如果内核缓冲区中没有事件，这些调用将等待事件到达，然后返回第一个事件。参数是指向以下结构的指针
struct mon_get_arg {
struct usbmon_packet *hdr;
void *data;
size_t alloc; /* Length of data (can be zero) */
};
在调用之前，应填充 hdr、data 和 alloc。返回时，hdr 指向的区域包含下一个事件结构，数据缓冲区包含数据（如果有）。该事件将从内核缓冲区中移除。
MON_IOCX_GET 将 48 字节复制到 hdr 区域，MON_IOCX_GETX 复制 64 字节。
MON_IOCX_MFETCH，定义为 _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
此 ioctl 主要用于应用程序通过 mmap(2) 访问缓冲区时。其参数是指向以下结构的指针
struct mon_mfetch_arg {
uint32_t *offvec; /* Vector of events fetched */
uint32_t nfetch; /* Number of events to fetch (out: fetched) */
uint32_t nflush; /* Number of events to flush */
};
该 ioctl 分 3 个阶段操作。
首先，它从内核缓冲区中移除并丢弃最多 nflush 个事件。实际丢弃的事件数量在 nflush 中返回。
其次，它等待缓冲区中出现一个事件，除非伪设备以 O_NONBLOCK 方式打开。
第三，它提取最多 nfetch 个偏移量到 mmap 缓冲区中，并将它们存储到 offvec 中。实际事件偏移量数量存储在 nfetch 中。
MON_IOCH_MFLUSH，定义为 _IO(MON_IOC_MAGIC, 8)
此调用从内核缓冲区中移除多个事件。其参数是要移除的事件数量。如果缓冲区包含的事件少于请求的数量，则移除所有现有事件，并且不报告错误。当没有可用事件时，此方法也有效。
FIONBIO
如果需要，ioctl FIONBIO 可能会在未来实现。
除了 ioctl(2) 和 read(2) 之外，二进制 API 的特殊文件可以通过 select(2) 和 poll(2) 进行轮询。但 lseek(2) 不起作用。
二进制 API 的内核缓冲区的内存映射访问
基本思想很简单
准备时，首先获取当前大小，然后使用 mmap(2) 映射缓冲区。接着，执行一个类似于下面伪代码所示的循环
struct mon_mfetch_arg fetch;
struct usbmon_packet *hdr;
int nflush = 0;
for (;;) {
fetch.offvec = vec; // Has N 32-bit words
fetch.nfetch = N; // Or less than N
fetch.nflush = nflush;
ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too
nflush = fetch.nfetch; // This many packets to flush when done
for (i = 0; i < nflush; i++) {
hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
if (hdr->type == '@') // Filler packet
continue;
caddr_t data = &mmap_area[vec[i]] + 64;
process_packet(hdr, data);
}
}
因此，主要思想是每 N 个事件只执行一次 ioctl。
尽管缓冲区是循环的，但返回的头部和数据不会跨越缓冲区的末尾，因此上述伪代码不需要任何聚合。