一文讲透 USB Gadget：让 Linux 设备变成 U 盘、串口和网卡
很多嵌入式工程师第一次接触 USB 时，默认把设备当成“插到板子上的外设”：U 盘、摄像头、鼠标、4G 模块，这些都属于 USB Host 视角。但在很多项目里，开发板本身也可以反过来变成一个 USB 设备，被电脑识别成串口、网卡、U 盘、MTP、ADB，甚至是几个功能组合起来的复合设备。
这个能力背后就是 USB Gadget。
USB Gadget 的核心价值很直接：让运行 Linux 的嵌入式设备，通过 USB Device Controller 把自己伪装成某种 USB 外设。对产品来说，它能做调试口、升级盘、产测通道、USB 网卡、文件传输；对驱动工程师来说，它连接了 USB 协议、控制器驱动、function driver、ConfigFS 和用户空间配置脚本，属于很典型的“看起来只是插根线，背后层次很多”的模块。
一、Gadget 框架总览：谁在扮演 USB 设备
理解 USB Gadget，先要把 Host 和 Device 的角色分清楚。
普通 USB 外设插到开发板上时，开发板是 Host，负责枚举别人；开发板通过 OTG 口插到电脑上，并被电脑识别成一个设备时，开发板就是 Device，负责向 Host 提供描述符和数据端点。Gadget 框架就是 Linux 在 Device 侧提供的一套软件抽象。
这套框架通常可以拆成几层：
- UDC 控制器：真实的 USB Device Controller 硬件，负责端点、传输和总线状态。
- UDC 驱动：把芯片控制器能力接入 Linux，比如 dwc2、dwc3、musb 等。
- Gadget Core：内核里的公共框架，协调 gadget driver、function 和 UDC。
- Function Driver：具体功能，比如 ACM 串口、Mass Storage、ECM/RNDIS 网卡、HID。
- ConfigFS：用户空间动态组合 gadget 的接口，很多量产项目都会用它。
很多问题会出在“角色理解错了”。比如板子插 U 盘不识别，那是 Host 侧问题；电脑插板子不识别，才是 Gadget 侧问题。再比如 OTG 口硬件支持双角色，但设备树里 dr_mode 配成了 host，那你怎么配 ConfigFS 都不会变成 USB 设备。
Gadget 的实战思路可以浓缩成一句话：硬件控制器先能跑在 device 模式，内核 function 再能加载，ConfigFS 最后把这些 function 拼成 Host 能识别的 USB 设备。
二、枚举链路与描述符：电脑到底是怎么认出你的
Gadget 能不能工作，第一道关就是枚举。Host 插上设备后，并不知道你是串口、网卡还是 U 盘，它只能先通过标准请求读取描述符，然后一步步确定设备身份。
典型枚举流程大致是这样：
- Host 读取 Device Descriptor，拿到 VID、PID、USB 版本、设备类别等信息。
- Host 读取 Configuration Descriptor，继续解析 Interface 和 Endpoint。
- Host 发送 Set Configuration，选择某个配置。
- Function Driver 开始启用端点，进入真正的数据收发。
这里最关键的是描述符。描述符不是简单的“设备名字”，而是 Host 识别设备能力的协议合同。比如 ACM 串口需要通信接口和数据接口，Mass Storage 需要 bulk in/out 端点，HID 还会带报告描述符。如果描述符和 function 实际端点对不上，Host 可能能看到设备，但驱动加载失败，或者数据传输阶段才暴露问题。
驱动调试时，不要只看“电脑有没有弹设备”。更可靠的方式是把 Host 视角和 Device 视角对起来：
●●●# Host 侧查看设备 VID、PID、配置和接口信息
lsusb -v -d 1d6b:0104
# Device 侧查看 gadget 配置目录
find /sys/kernel/config/usb_gadget/g1 -maxdepth 3 -type f
# Device 侧查看 UDC 是否已经绑定
cat /sys/kernel/config/usb_gadget/g1/UDC
如果 lsusb 能看到设备但接口不对，优先查 configs 和 functions 的链接关系。如果 UDC 为空，说明 gadget 还没真正挂到控制器上。如果 Host 连 VID/PID 都看不到，就要回头查 dr_mode、线缆、VBUS、控制器驱动和内核日志。
三、ConfigFS 组合实战：像搭积木一样拼功能
早期 gadget 常见做法是使用固定内核模块，比如 g_serial、g_mass_storage、g_ether。这种方式简单，但灵活性一般。现在很多项目更常用 ConfigFS，因为它允许用户空间动态创建 gadget、设置描述符、创建 function、组合 config，最后绑定到 UDC。
一个最小 ACM 串口 gadget 配置脚本大概长这样：
●●●#!/bin/sh
G=/sys/kernel/config/usb_gadget/g1
mkdir -p $G # 创建 gadget 根目录
echo 0x1d6b > $G/idVendor # 设置 VID，示例使用 Linux Foundation
echo 0x0104 > $G/idProduct # 设置 PID，项目中应使用自己的 ID
mkdir -p $G/strings/0x409
echo "0123456789" > $G/strings/0x409/serialnumber # 设置序列号
echo "EmbeddedBoard" > $G/strings/0x409/manufacturer # 设置厂商字符串
echo "USB ACM Gadget" > $G/strings/0x409/product # 设置产品字符串
mkdir -p $G/configs/c.1/strings/0x409
echo "ACM Config" > $G/configs/c.1/strings/0x409/configuration
echo 120 > $G/configs/c.1/MaxPower # 设置最大功耗，单位通常按 USB 规则表达
mkdir -p $G/functions/acm.usb0 # 创建 ACM 串口 function
ln -s $G/functions/acm.usb0 $G/configs/c.1/ # 把 function 加入配置
ls /sys/class/udc > $G/UDC # 绑定第一个可用 UDC，设备开始枚举
这段脚本体现了 ConfigFS 的基本模型：先建 gadget，再填字符串和配置，再建 function，再把 function 链接进 config，最后写入 UDC 节点触发连接。绑定 UDC 之前，Host 通常不会看到这个设备；绑定之后，控制器才开始响应枚举。
复合设备也是同一个思路。比如一个设备既要做调试串口，又要做 USB 网卡，还要做升级 U 盘，本质上就是创建多个 function，然后链接到同一个 config 里。不过复合设备要更谨慎：Host 操作系统对 RNDIS、ECM、MTP、ADB 的驱动支持不同，Windows、Linux、macOS 的表现也不完全一样。产线用的 Host 环境固定时，最好把 VID/PID、接口顺序、驱动匹配策略都提前验证好。
四、调试验证与落地：先确认链路，再怀疑代码
USB Gadget 的问题经常表现得很像玄学：同一根线，有的电脑能识别，有的电脑不行；脚本执行没报错，但 Host 没反应；串口能出来，网卡拿不到地址；U 盘枚举成功，但读写异常。
排查时建议按链路分层，不要一上来就改 function driver。
- 硬件层：确认 USB 口是否支持 device/OTG，VBUS 检测和 ID 管脚是否正常。
- 设备树层：确认控制器
dr_mode 是否为 peripheral 或 otg。 - 内核层：确认 UDC 驱动和对应 function driver 是否编进内核或已加载。
- ConfigFS 层：确认目录、字符串、function、config 链接和 UDC 绑定是否正确。
- Host 层：确认 Host 是否真的收到枚举，驱动是否匹配，系统日志是否有拒绝原因。
常用检查命令可以先放进自己的调试清单：
●●●# 查看当前系统有哪些可用 USB Device Controller
ls /sys/class/udc
# 查看 gadget 是否已经绑定到某个 UDC
cat /sys/kernel/config/usb_gadget/g1/UDC
# 查看 device 侧内核日志，关注枚举、端点和 function 报错
dmesg | grep -Ei "gadget|udc|dwc|configfs|usb"
# Host 侧确认是否识别到设备以及接口描述
lsusb
lsusb -t
实战中有几个坑很常见。第一，脚本重复执行时旧 gadget 没清理干净，导致 function 链接残留，新的配置看似成功但实际冲突。第二，先绑定 UDC 再创建 function，Host 可能拿到半成品描述符。第三，复合设备接口顺序变化后，Host 侧驱动缓存还在，表现为“改了没生效”。第四，OTG 口在 bootloader、kernel、用户空间之间切角色，状态没有完全释放，重新绑定 UDC 会失败。
更稳的做法是给调试脚本加上清理和重绑逻辑：先写空 UDC 解绑，再删除 config 下的 function 链接，最后重新创建并绑定。这样每次实验起点一致，日志也更容易对齐。
五、什么时候该用 USB Gadget？
USB Gadget 不是只属于调试阶段，它在产品里也很常见。
- 调试串口：不额外接 UART 转接板，电脑直接识别 ACM 口。
- U 盘升级：设备把内部分区或升级镜像暴露成 Mass Storage。
- USB 网卡：用 ECM/RNDIS 建立点对点网络，方便调试 Web UI、SSH 或产测服务。
- 产测模式：通过专用 VID/PID 和复合接口，让产测软件自动识别设备。
- 文件传输：通过 MTP、ADB 或自定义 function 做数据导入导出。
选择方案时要结合产品场景。临时调试可以用 ACM，升级场景可以用 Mass Storage，网络调试优先考虑 ECM/RNDIS，安卓生态可能会涉及 ADB/MTP。真正量产时，别只验证 Linux Host，最好把目标 Windows 版本、驱动签名、线缆质量、热插拔、休眠唤醒都测一遍。
回到驱动原理，USB Gadget 的关键不是背很多 API，而是掌握这条主线：UDC 提供硬件能力，Gadget Core 做框架协调，Function Driver 定义具体 USB 功能，ConfigFS 负责动态组合，Host 通过描述符完成识别和驱动匹配。
把这条链路吃透，很多问题就不再是“电脑不认板子”这种模糊现象，而能拆成更具体的判断：控制器有没有起来，gadget 有没有绑定，描述符是否正确，function 是否加载，Host 是否匹配到驱动，数据端点是否真的开始传输。工程调试最需要的，正是这种把现象拆回链路的能力。
10个月宝宝每天需要喝多少奶粉？
