1. USB Gadget 概述
1.1 USB Gadget 概念
USB Gadget 是嵌入式 Linux 系统中一种特殊的 USB 设备角色。它允许嵌入式设备（如开发板、路由器、IoT 模块）通过 USB 接口模拟成标准的外设（如网卡、串口、U盘），从而与 USB Host（通常是 PC 或智能手机）进行通信。
在 Linux 内核中，USB Gadget 功能由 USB Gadget 框架 实现。该框架位于内核的 drivers/usb/gadget/ 目录下，通过 UDC（USB Device Controller） 硬件驱动与底层 USB 控制器交互，向上提供统一的 API 供各类功能驱动（Function Driver）使用。
核心要点： USB Gadget 让嵌入式设备从“USB 主设备”转变为“USB 从设备”，从而可以被 Host 端识别和管理。
1.2 Gadget 与 Host 的区别
在 USB 协议中，Host 和 Gadget 是两个完全不同的角色。Host 负责总线控制、枚举管理、供电；Gadget 则被动响应 Host 的请求，模拟外设功能。
| 对比维度 | USB Host | USB Gadget |
|---|---|---|
| 角色定位 | 总线主控（Master） | 外设从设备（Slave） |
| 典型设备 | PC、笔记本电脑、智能手机（OTG Host 模式） | 嵌入式开发板、路由器、打印机、U盘 |
| 总线控制权 | 发起所有传输事务 | 被动响应 Host 请求 |
| 供电方向 | 对外供电（VBUS） | 由 Host 供电（或自供电） |
| 枚举过程 | 发送 Get Descriptor 请求 | 返回描述符数据 |
| Linux 驱动 | USB Host 控制器驱动（EHCI/OHCI/xHCI） | UDC 驱动 + Gadget 框架 |
| 配置方式 | 无需配置，自动识别 | 需通过 ConfigFS 或 GadgetFS 配置 |
常见误区： 嵌入式设备通常同时具备 Host 和 Gadget 能力（通过 OTG 切换），但在使用 ConfigFS 创建 Gadget 时，必须确保 UDC 驱动处于 Gadget 模式，而非 Host 模式。
1.3 常见 Gadget 设备类型
Linux USB Gadget 框架支持多种功能驱动，每种驱动对应一种标准 USB 设备类。以下是在 ConfigFS 配置中最常用的几种 Gadget 类型：
| 功能类型 | 内核模块 | USB 类代码 | 典型用途 | Host 端识别为 |
|---|---|---|---|---|
| ECM（Ethernet Control Model） | usb_f_ecm.ko |
0x02（通信类） | USB 虚拟网卡，用于网络共享 | CDC Ethernet 设备 |
| ACM（Abstract Control Model） | usb_f_acm.ko |
0x02（通信类） | USB 虚拟串口，用于调试/数据透传 | CDC ACM 串口设备 |
| Mass Storage | usb_f_mass_storage.ko |
0x08（大容量存储类） | 模拟 U 盘、SD 卡读卡器 | USB 大容量存储设备 |
| RNDIS（Remote NDIS） | usb_f_rndis.ko |
0xE0（厂商特定） | Windows 网络共享（需驱动） | Remote NDIS 设备 |
| HID（Human Interface Device） | usb_f_hid.ko |
0x03（HID 类） | 模拟键盘、鼠标、游戏手柄 | USB HID 设备 |
| UAC2（USB Audio Class 2） | usb_f_uac2.ko |
0x01（音频类） | USB 麦克风/扬声器 | USB 音频设备 |
注意： 不同 Gadget 类型对 UDC 硬件的要求不同。例如，ECM 需要 UDC 支持 双方向批量端点，而 ACM 只需要一个中断端点和一个批量端点。在排查故障时，首先确认 UDC 硬件是否支持所选功能类型。
1.4 Gadget 功能组合与配置
ConfigFS 的强大之处在于支持 多功能组合。一个 USB Gadget 设备可以同时包含多个功能，例如同时提供 ECM 网卡 + ACM 串口 + Mass Storage U盘。Host 端会识别为一个复合设备，包含多个接口。
组合配置的基本流程：
- 创建 Gadget 目录（
mkdir /sys/kernel/config/usb_gadget/g1） - 设置 VID/PID 和字符串描述符
- 创建配置目录（
mkdir configs/c.1） - 创建功能目录并链接到配置（
ln -s functions/ecm.usb0 configs/c.1/） - 绑定 UDC（
echo <udc_name> > UDC）
关键概念： 每个功能在 Host 端表现为一个独立的 接口（Interface）。复合设备通过接口关联描述符（IAD）告知 Host 哪些接口属于同一个功能。
1.5 本章小结
- USB Gadget 是嵌入式设备模拟 USB 外设的机制，通过 Linux Gadget 框架实现。
- Host 与 Gadget 角色对立：Host 控制总线，Gadget 被动响应。
- 常见 Gadget 类型包括 ECM、ACM、Mass Storage、RNDIS、HID、UAC2 等，每种对应不同的 USB 设备类。
- ConfigFS 支持 多功能组合，一个物理 USB 连接可同时提供网卡、串口、U盘等多种功能。
- 理解 Gadget 架构是后续排查 ConfigFS 创建失败问题的基础。