📚 课程目录第4章内核配置与编译

4. 内核配置与编译：内核 USB Gadget 相关选项

USB Gadget 功能的实现高度依赖 Linux 内核的编译配置。错误的配置会导致 Gadget 功能无法编译进内核、模块加载失败，或在枚举阶段直接返回空设备描述符。本节将详细解析与 USB Gadget 相关的内核选项，并说明模块编译与内置的差异及操作步骤。

4.1 核心 Kconfig 选项解析

USB Gadget 子系统在内核源码树中位于 drivers/usb/gadget/ 目录。以下表格列出了最关键的配置选项及其作用：

配置宏	位置	功能描述	故障关联
`CONFIG_USB_GADGET`	Device Drivers → USB support → USB Gadget Support	USB Gadget 框架总开关。必须开启才能使用任何 Gadget 功能。	未开启时，内核无任何 Gadget 相关代码，枚举完全失败。
`CONFIG_USB_CONFIGFS`	USB Gadget Support → USB Gadget Drivers → USB Gadget Functions accessible through configfs	启用基于 configfs 的 Gadget 配置接口。允许在用户空间动态组合 UDC、Function 和配置。	未开启时，无法通过 `/sys/kernel/config/usb_gadget/` 创建 Gadget 实例。
`CONFIG_USB_U_SERIAL`	USB Gadget Support → USB Gadget Drivers → Serial Gadget	提供串口（ACM）功能的 Gadget 驱动。	未编译时，`g_serial.ko` 或 configfs 中的 `acm` 功能无法加载。
`CONFIG_USB_ETH`	USB Gadget Support → USB Gadget Drivers → Ethernet Gadget	提供 RNDIS/ECM 网络功能的 Gadget 驱动。	未编译时，USB 网络适配器无法被主机识别。
`CONFIG_USB_GADGET_STORAGE_NUM_BUFFERS`	USB Gadget Support → Number of storage gadget buffers	控制 Mass Storage Gadget 使用的缓冲区数量，影响传输性能。	值过小可能导致大文件传输超时或枚举后挂载失败。

排查要点： 在故障排查时，首先检查 /boot/config-$(uname -r) 或 /proc/config.gz 中 CONFIG_USB_GADGET 和 CONFIG_USB_CONFIGFS 是否为 y 或 m。若为 n，则必须重新编译内核。

4.2 模块编译（m）与内置（y）的选择策略

每个 Gadget 相关选项都可以选择编译为模块（m）或直接内置进内核（y）。两种方式各有优劣，直接影响故障排查的复杂度。

内置（y）：驱动随内核启动而加载，无需依赖根文件系统。适用于根文件系统位于非易失性存储（如 eMMC、NAND）且需要早期 USB 功能的场景。缺点是内核体积增大，且无法在运行时卸载。
模块（m）：驱动以 .ko 文件形式存在，可在系统启动后按需加载。适用于调试阶段，可以灵活地卸载、重载驱动以测试不同配置。缺点是模块文件必须存放在可访问的文件系统中，若根文件系统未挂载，则无法加载。

以下表格总结了两种方式的适用场景与故障风险：

编译方式	优点	缺点	典型故障场景
内置（y）	启动即用，不依赖文件系统	无法卸载，调试不便	内置了错误的 UDC 驱动导致系统启动时 USB 控制器初始化失败
模块（m）	灵活加载/卸载，便于调试	依赖文件系统，模块可能缺失	`modprobe g_ether` 失败，提示 `FATAL: Module not found`

常见陷阱： 在嵌入式系统中，如果根文件系统是 initramfs 且空间有限，将 Gadget 驱动编译为模块可能导致模块文件未被包含进 initramfs，从而在系统启动后无法加载。此时应优先考虑内置（y）或手动将模块添加到 initramfs 中。

4.3 编译与安装步骤

以下是在标准 Linux 内核源码树中配置并编译 USB Gadget 驱动的完整流程：

进入内核源码目录：
```
cd /path/to/linux-source
```

加载现有配置（通常使用当前系统的配置作为基础）：

zcat /proc/config.gz > .config
# 或
cp /boot/config-$(uname -r) .config

启动菜单配置：
```
make menuconfig
```

导航并启用选项：

Device Drivers  --->
  [*] USB support  --->
    <*>   USB Gadget Support  --->
      <*>   USB Gadget Functions accessible through configfs
      <M>   Ethernet Gadget (with CDC Ethernet support)
      <M>   Serial Gadget (with CDC ACM support)

使用 <*> 表示内置，<M> 表示模块。

保存并退出：选择 Save 并退出 menuconfig。
编译内核与模块：
```
make -j$(nproc)
make modules_install
```
安装新内核（可选，若仅测试模块可跳过）：
```
make install
```
更新引导加载程序（如 GRUB）：
```
update-grub
```

  调试建议： 在开发阶段，建议将 CONFIG_USB_GADGET 和 CONFIG_USB_CONFIGFS 编译为内置（y），而将具体的 Function 驱动（如 g_ether、g_serial）编译为模块（m）。这样既能保证 Gadget 框架在启动时可用，又能灵活切换不同的功能进行测试。

4.4 内核配置与 Gadget 驱动加载流程

下图展示了从内核配置到 Gadget 驱动加载的完整流程，以及配置错误可能导致的故障点：

4.5 验证配置是否生效

编译并重启后，可以通过以下命令验证 USB Gadget 相关配置是否已正确加载：

# 检查内核是否支持 configfs
mount | grep configfs
# 输出示例：configfs on /sys/kernel/config type configfs (rw,relatime)

# 检查 Gadget 框架是否可用
ls /sys/kernel/config/usb_gadget/
# 若目录存在且为空，说明框架已就绪

# 检查 UDC 控制器是否被识别
ls /sys/class/udc/
# 输出示例：musb-hdrc.0.auto

# 检查已加载的 Gadget 模块
lsmod | grep g_
# 输出示例：g_ether              28672  0

快速诊断： 如果 /sys/kernel/config/usb_gadget/ 目录不存在，说明 CONFIG_USB_CONFIGFS 未编译或未加载。如果 /sys/class/udc/ 为空，说明 UDC 驱动未正确绑定到硬件，此时即使 Gadget 配置正确也无法进行枚举。