如何在Android Shell中通过ConfigFS配置USB Gadget

阿华AIGC实验室

2026-5-15

Android USB Gadget 多功能组合配置指南（HID+RNDIS+MASS_STORAGE）

我之前也碰到过类似的Android USB Gadget多功能组合失效的问题，结合实际调试经验和内核文档，给你梳理几个可行的解决方向：

一、先排查内核层面的功能支持

首先得确认你的设备内核是否同时支持这三个功能的组合，以及对应的驱动是否编译：

执行以下命令查看内核配置（如果你的设备支持/proc/config.gz）：
```
zcat /proc/config.gz | grep CONFIG_USB_GADGET_
```
确保CONFIG_USB_GADGET_HID、CONFIG_USB_GADGET_ETH（对应RNDIS/ECM）、CONFIG_USB_GADGET_MASS_STORAGE都被设为y（编译进内核）或m（模块加载）。如果某一项缺失，那你的内核不支持该功能，需要重新编译内核添加。

二、使用sysfs配置多功能组合的正确步骤

你之前用sysfs的思路是对的，但可能忽略了一些细节，比如功能顺序、存储设备绑定：

先禁用当前USB Gadget：

echo 0 > /sys/class/android_usb/android0/enable

清空原有功能并设置目标组合：
注意：部分设备对功能顺序敏感，建议先加HID，再加网络功能（RNDIS/ECM），最后加MASS_STORAGE。另外，有些设备用rndis而非ecm，可以两种都试试：

echo "" > /sys/class/android_usb/android0/functions
# 尝试HID+RNDIS+MASS_STORAGE
echo hid,rndis,mass_storage > /sys/class/android_usb/android0/functions
# 如果RNDIS不行，换ECM试试
# echo hid,ecm,mass_storage > /sys/class/android_usb/android0/functions

绑定MASS_STORAGE的存储分区（如果需要该功能）：
替换/dev/block/mmcblk0p1为你实际的存储分区路径（可以通过ls /dev/block/查看）：
```
echo /dev/block/mmcblk0p1 > /sys/class/android_usb/android0/f_mass_storage/lun0/file
```
重新启用USB Gadget：
```
echo 1 > /sys/class/android_usb/android0/enable
```
如果还是失败，查看内核日志dmesg | grep usb，有没有类似endpoint allocation failed的错误——这通常是USB控制器端点数量不足导致的，属于硬件限制，可能无法解决。

三、解决configfs挂载后为空且只读的问题

configfs是更灵活的USB Gadget配置方式，但Android设备默认可能没正确挂载：

先确认内核支持configfs：
```
cat /proc/filesystems | grep configfs
```
如果没有输出，说明你的内核不支持configfs，只能用sysfs方式。

正确挂载configfs：
挂载时要确保是读写模式：

# 先卸载原有只读挂载（如果存在）
umount /config 2>/dev/null
# 重新挂载为读写
mount -t configfs -o rw configfs /config

使用configfs创建多功能Gadget（完整示例）：

# 创建Gadget目录
mkdir -p /config/usb_gadget/my_multi_gadget
cd /config/usb_gadget/my_multi_gadget

# 设置厂商和产品ID（替换为你的设备实际ID）
echo 0x18D1 > idVendor  # Google的Vendor ID，可替换为自己的
echo 0x4EE7 > idProduct # 示例Product ID

# 添加字符串描述符
mkdir -p strings/0x409
echo "My Device" > strings/0x409/manufacturer
echo "Multi-Function USB Gadget" > strings/0x409/product
echo "1234567890" > strings/0x409/serialnumber

# 创建配置项
mkdir -p configs/c.1/strings/0x409
echo "Full Function Mode" > configs/c.1/strings/0x409/configuration
echo 500 > configs/c.1/MaxPower # 最大电流500mA

# 配置HID功能（以键盘为例）
mkdir functions/hid.usb0
echo 1 > functions/hid.usb0/protocol    # 键盘协议
echo 1 > functions/hid.usb0/subclass    # 引导子类
echo 8 > functions/hid.usb0/report_length # 报告长度
# 写入HID报告描述符（键盘）
echo -ne \\x05\\x01\\x09\\x06\\xA1\\x01\\x05\\x07\\x19\\xE0\\x29\\xE7\\x15\\x00\\x25\\x01\\x75\\x01\\x95\\x08\\x81\\x02\\x95\\x01\\x75\\x08\\x81\\x03\\x95\\x05\\x75\\x01\\x05\\x08\\x19\\x01\\x29\\x05\\x91\\x02\\x95\\x01\\x75\\x03\\x91\\x03\\x95\\x06\\x75\\x08\\x15\\x00\\x25\\x65\\x05\\x07\\x19\\x00\\x29\\x65\\x81\\x00\\xC0 > functions/hid.usb0/report_desc

# 配置ECM网络功能
mkdir functions/ecm.usb0
# 设置MAC地址（可选，可自定义）
echo "00:11:22:33:44:55" > functions/ecm.usb0/host_addr
echo "00:11:22:33:44:56" > functions/ecm.usb0/dev_addr

# 配置MASS_STORAGE功能
mkdir functions/mass_storage.usb0
echo 1 > functions/mass_storage.usb0/lun.0/removable
echo /dev/block/mmcblk0p1 > functions/mass_storage.usb0/lun.0/file # 替换为你的存储分区

# 将功能绑定到配置项
ln -s functions/hid.usb0 configs/c.1/
ln -s functions/ecm.usb0 configs/c.1/
ln -s functions/mass_storage.usb0 configs/c.1/

# 绑定到USB控制器（先查看可用控制器）
UDC_NODE=$(ls /sys/class/udc/)
echo $UDC_NODE > UDC

执行完后，Windows应该能识别到这三个功能。如果失败，同样查看dmesg的USB相关日志排查。

四、为什么HID+RNDIS组合会失效？

常见原因有两个：

硬件端点限制：部分低端手机的USB控制器端点数量有限，HID（通常需要2个端点）+ RNDIS（通常需要4个端点）的总端点数超过了控制器的上限，导致内核无法分配资源。
内核驱动兼容性：Android默认的USB Gadget驱动可能没有对某些功能组合做充分测试，比如HID和RNDIS的驱动可能存在资源冲突。这种情况下可以尝试升级内核，或者查看内核源码是否有相关补丁。