📚 课程目录第4章环境准备与依赖检查

4. 环境准备与依赖检查

在开始使用 ConfigFS 创建 USB Gadget 设备之前，必须确保宿主机的内核、用户空间工具和运行时库均已正确配置。本章将系统性地检查三个关键层面：内核配置选项、udev 规则以及 libusb 依赖。任何一个环节缺失或错误，都会导致 Gadget 设备创建失败或无法被主机识别。

⚠️ 常见误区：很多开发者只关注内核模块是否加载，却忽略了 udev 规则和 libusb 权限问题。实际上，超过 60% 的“设备无法枚举”故障源于用户空间权限不足或设备节点权限错误。

4.1 内核配置选项

内核是 USB Gadget 功能的基石。以下两个配置选项必须在内核编译时启用（编译为模块或直接编译进内核）：

配置选项	内核路径	说明	推荐设置
`CONFIG_USB_GADGET`	Device Drivers → USB Support → USB Gadget Support	启用 USB Gadget 框架核心，提供 UDC（USB Device Controller）驱动接口	编译为模块 (m) 或编译进内核 (y)
`CONFIG_USB_CONFIGFS`	Device Drivers → USB Support → USB Gadget Support → USB Gadget Drivers → USB ConfigFS	启用 ConfigFS 文件系统接口，允许在用户空间通过文件系统动态配置 Gadget	必须编译为模块 (m)

🔍 检查方法：运行以下命令确认内核是否已启用上述选项：

# 检查 CONFIG_USB_GADGET
zcat /proc/config.gz | grep CONFIG_USB_GADGET
# 输出示例：CONFIG_USB_GADGET=m

# 检查 CONFIG_USB_CONFIGFS
zcat /proc/config.gz | grep CONFIG_USB_CONFIGFS
# 输出示例：CONFIG_USB_CONFIGFS=m

如果输出为空或显示 # CONFIG_USB_xxx is not set，则需要重新编译内核或使用预编译内核包。

💡 提示：如果使用树莓派或 BeagleBone 等开发板，官方内核通常已启用这两个选项。对于自定义嵌入式系统，务必在 menuconfig 中确认。

4.2 udev 规则

udev 负责在设备插入时动态创建设备节点并设置权限。对于 USB Gadget 设备，正确的 udev 规则可以确保用户空间程序（如 gadget-tool 或自定义脚本）有权限访问 /dev/usb/lp0、/dev/ttyACM0 等节点。

4.2.1 常见问题

权限不足：默认情况下，设备节点属于 root 用户，普通用户无法访问。
节点未创建：某些 Gadget 功能（如 ACM 串口）需要特定的内核模块加载后才能生成节点。
规则冲突：多个 udev 规则可能匹配同一设备，导致权限设置被覆盖。

4.2.2 推荐规则示例

在 /etc/udev/rules.d/ 目录下创建 99-usb-gadget.rules 文件，内容如下：

# 为 USB Gadget ACM 串口设备设置权限
SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", MODE="0666"

# 为 USB Gadget 海量存储设备设置权限
SUBSYSTEM=="block", KERNEL=="sd*[!0-9]", ATTRS{removable}=="1", MODE="0666"

# 为 USB Gadget 网络设备设置权限
SUBSYSTEM=="net", KERNEL=="usb[0-9]*", MODE="0666"

🔧 应用规则：保存文件后，执行以下命令使规则生效：

sudo udevadm control --reload-rules
sudo udevadm trigger

⚠️ 安全提示：在生产环境中，建议使用更严格的权限（如 MODE="0660" 并指定 GROUP="plugdev"），避免将设备节点设置为全局可读写。

4.3 libusb 依赖

libusb 是用户空间访问 USB 设备的跨平台库。虽然 ConfigFS 本身不直接依赖 libusb，但许多 Gadget 管理工具（如 gadget-tool、usb-gadget）以及测试工具（如 lsusb、usb-devices）都基于 libusb 实现。

4.3.1 版本要求

库名称	最低版本	推荐版本	说明
libusb-1.0	1.0.16	1.0.24+	支持 USB 3.0 及异步 I/O
libusb-compat	0.1.5	0.1.8+	兼容旧版 libusb-0.1 API

4.3.2 安装与验证

在 Debian/Ubuntu 系统上安装：

sudo apt-get install libusb-1.0-0-dev libusb-1.0-0

在 Fedora/RHEL 系统上安装：

sudo dnf install libusb1-devel libusb1

✅ 验证安装：

# 检查库文件是否存在
ls -l /usr/lib/x86_64-linux-gnu/libusb-1.0.so*

# 检查 pkg-config 配置
pkg-config --modversion libusb-1.0
# 输出示例：1.0.24

💡 提示：如果编译 Gadget 工具时提示 libusb.h: No such file or directory，说明缺少开发头文件，需要安装 libusb-1.0-0-dev 包。

4.4 综合检查清单

在继续后续章节之前，请使用以下清单逐一确认环境就绪：

检查项	命令/方法	预期结果
内核配置	`zcat /proc/config.gz \| grep CONFIG_USB_GADGET`	`CONFIG_USB_GADGET=m` 或 `=y`
ConfigFS 支持	`zcat /proc/config.gz \| grep CONFIG_USB_CONFIGFS`	`CONFIG_USB_CONFIGFS=m`
ConfigFS 挂载	`mount \| grep configfs`	`configfs on /sys/kernel/config type configfs`
udev 规则	`ls -l /etc/udev/rules.d/gadget`	规则文件存在且语法正确
libusb 版本	`pkg-config --modversion libusb-1.0`	≥ 1.0.16
UDC 驱动	`ls /sys/class/udc`	至少有一个 UDC 设备（如 `musb-hdrc.0`）

📋 快速诊断脚本：将以下命令保存为 check_gadget_env.sh，一键检查环境：

#!/bin/bash
echo "=== USB Gadget 环境检查 ==="
echo "1. 内核配置："
zgrep -E "CONFIG_USB_GADGET|CONFIG_USB_CONFIGFS" /proc/config.gz 2>/dev/null || echo "   [FAIL] 无法读取内核配置"
echo "2. ConfigFS 挂载："
mount | grep configfs || echo "   [FAIL] ConfigFS 未挂载"
echo "3. UDC 设备："
ls /sys/class/udc/ || echo "   [FAIL] 无 UDC 设备"
echo "4. libusb 版本："
pkg-config --modversion libusb-1.0 2>/dev/null || echo "   [FAIL] libusb 未安装"
echo "5. udev 规则："
ls /etc/udev/rules.d/*gadget* 2>/dev/null || echo "   [WARN] 无专用 udev 规则"