深入解析：RK3568 USB Gadget驱动框架，如何同时模拟多个HID设备（键盘+鼠标）

RK3568 USB Gadget驱动深度实践：多HID设备模拟的技术内幕

当我们需要在一块嵌入式开发板上实现键盘和鼠标的模拟功能时，RK3568的USB Gadget驱动框架提供了完美的解决方案。本文将带你深入Linux内核的USB子系统，解析如何通过ConfigFS配置同时模拟多个HID设备的完整技术路径。

1. USB Gadget框架基础架构

USB Gadget是Linux内核中实现USB设备功能的子系统，它允许嵌入式设备作为USB从设备（如键盘、鼠标、存储设备等）连接到主机。RK3568平台上的实现基于Linux标准USB Gadget框架，但针对Rockchip芯片做了特定优化。

在架构层面，USB Gadget子系统包含几个关键组件：

• UDC驱动（USB Device Controller）：负责底层硬件通信
• Composite驱动：管理多个功能组合
• Function驱动：实现具体设备功能（如HID、Mass Storage等）

对于RK3568开发板，我们需要特别关注的是f_hid.c这个内核模块，它实现了HID（Human Interface Device）功能的核心逻辑。通过分析其源码，我们可以发现几个关键数据结构：

struct f_hidg { struct usb_function function; struct usb_ep *in_ep; struct usb_ep *out_ep; unsigned char *report_desc; unsigned short report_length; /* ...其他字段... */ };

这个结构体保存了HID设备的关键信息，包括端点配置和报告描述符。理解这些底层数据结构对于后续的多设备配置至关重要。

2. ConfigFS配置实战

Linux内核从3.11版本开始引入了USB Gadget ConfigFS接口，它通过虚拟文件系统的方式提供了动态配置USB设备的能力。相比传统的静态编译配置，ConfigFS具有以下优势：

2.1 基础环境准备

首先确保内核已启用相关配置选项。对于RK3568平台，需要在rockchip_linux_defconfig中添加：

CONFIG_USB_CONFIGFS=y CONFIG_USB_CONFIGFS_F_HID=y CONFIG_USB_LIBCOMPOSITE=y

编译并烧录内核后，通过以下命令初始化ConfigFS环境：

mount -t configfs none /sys/kernel/config mkdir -p /sys/kernel/config/usb_gadget/g1 cd /sys/kernel/config/usb_gadget/g1

2.2 多HID设备配置步骤

创建两个HID设备（键盘和鼠标）的具体操作流程：

1. 创建设备基本信息：

   echo 0x1d6b > idVendor # Linux Foundation echo 0x0104 > idProduct # Multifunction Composite Gadget echo 0x0100 > bcdDevice # Version 1.0.0 mkdir -p strings/0x409 echo "12345678" > strings/0x409/serialnumber echo "Rockchip" > strings/0x409/manufacturer echo "RK3568 HID Gadget" > strings/0x409/product

2. 配置HID功能：

   mkdir -p functions/hid.usb0 # 键盘 mkdir -p functions/hid.usb1 # 鼠标 # 键盘配置 echo 1 > functions/hid.usb0/protocol # 键盘协议 echo 1 > functions/hid.usb0/subclass # Boot接口子类 echo 8 > functions/hid.usb0/report_length echo -ne "\x05\x01\x09\x06\xa1\x01...\xc0" > functions/hid.usb0/report_desc # 鼠标配置 echo 2 > functions/hid.usb1/protocol # 鼠标协议 echo 1 > functions/hid.usb1/subclass echo 3 > functions/hid.usb1/report_length echo -ne "\x05\x01\x09\x02\xa1\x01...\xc0" > functions/hid.usb1/report_desc

3. 绑定配置并启用：

   mkdir -p configs/c.1 ln -s functions/hid.usb0 configs/c.1 ln -s functions/hid.usb1 configs/c.1 echo "$(ls /sys/class/udc)" > UDC

注意：完整的HID报告描述符较长，实际使用时需要参考HID规范填写完整。键盘通常需要约60字节的描述符，鼠标需要约40字节。

3. HID报告描述符解析

HID报告描述符是定义设备功能的核心数据结构，它使用特定的二进制格式描述设备的能力和数据格式。理解描述符的生成原理是开发复杂HID设备的关键。

3.1 描述符结构解析

一个典型的键盘报告描述符包含以下主要部分：

05 01 // Usage Page (Generic Desktop) 09 06 // Usage (Keyboard) A1 01 // Collection (Application) 05 07 // Usage Page (Key Codes) 19 E0 // Usage Minimum (224) 29 E7 // Usage Maximum (231) 15 00 // Logical Minimum (0) 25 01 // Logical Maximum (1) 75 01 // Report Size (1) 95 08 // Report Count (8) 81 02 // Input (Data,Var,Abs) ... // 其他字段 C0 // End Collection

鼠标报告描述符的关键区别在于：

• Usage Page通常为0x01（Generic Desktop）
• Usage为0x02（Mouse）
• 包含相对坐标数据而非按键状态

3.2 描述符生成工具

手动编写二进制描述符容易出错，推荐使用以下工具辅助生成：

1. hidrd：开源HID描述符转换工具

   # 将文本描述符转换为二进制 hidrd-convert -i nat -o hex keyboard.hid

2. 在线HID描述符生成器：如usb.org提供的官方工具

3. Python生成脚本示例：

   def gen_keyboard_desc(): desc = [ 0x05, 0x01, # Usage Page (Generic Desktop) 0x09, 0x06, # Usage (Keyboard) # ...其他字段... ] return bytes(desc)

4. 内核驱动机制深度分析

当我们在同一个USB控制器上绑定多个HID功能时，内核通过以下机制实现资源管理和数据路由：

4.1 多实例支持架构

f_hid.c驱动通过以下关键函数实现多实例支持：

static int hidg_bind(struct usb_configuration *c, struct usb_function *f) { struct f_hidg *hidg = func_to_hidg(f); struct usb_ep *ep; /* 分配端点 */ ep = usb_ep_autoconfig(c->cdev->gadget, &hidg_fs_in_ep_desc); if (!ep) return -ENODEV; hidg->in_ep = ep; /* 设置HID描述符 */ hidg->report_desc = kzalloc(hidg->report_length, GFP_KERNEL); memcpy(hidg->report_desc, hidg->report_desc_alloc, hidg->report_length); /* ...其他初始化... */ }

每个HID实例都会独立分配资源和端点，确保数据隔离。内核通过usb_function结构体中的链表管理多个功能实例。

4.2 数据流路径

当用户空间向/dev/hidgX写入数据时，内核中的数据流向如下：

1. 用户调用write()系统调用
2. 内核通过f_hid.c中的hidg_write()处理
3. 数据被放入对应端点的请求队列
4. USB控制器驱动通过DMA传输数据到主机

graph TD A[用户空间] -->|write| B(/dev/hidg0) B --> C[f_hid.ko] C --> D[USB请求队列] D --> E[UDC驱动] E --> F[USB物理层]

注意：实际实现中，RK3568的USB控制器会处理端点复用和带宽分配，开发者无需关心底层细节。

5. 高级应用与调试技巧

掌握了基础配置后，我们可以进一步优化HID设备的实现方式，并解决常见的开发问题。

5.1 性能优化策略

在多HID设备场景下，需要考虑以下性能因素：

• 端点分配策略：高速端点优先分配给高频率设备（如鼠标）
• 报告频率优化：调整bInterval参数平衡响应速度和CPU负载
• DMA缓冲区大小：根据报告长度适当调整

可以通过以下命令查看当前USB带宽使用情况：

cat /sys/kernel/debug/usb/udc/<udc_name>/bandwidth

5.2 常见问题排查

问题1：主机无法识别设备

解决方案：

1. 检查dmesg输出中的USB枚举日志
2. 确认描述符格式符合规范
3. 使用USB分析仪捕获通信数据

问题2：输入延迟明显

解决方案：

1. 提高HID报告频率

   echo 1 > functions/hid.usb0/bInterval

2. 检查系统负载，避免CPU过载
3. 优化用户空间程序，减少系统调用开销

问题3：多设备同时使用时数据混乱

解决方案：

1. 确保每个HID实例使用独立的report_id
2. 检查端点分配是否冲突
3. 验证用户空间程序是否正确区分设备节点

6. 实际项目集成

在类似PiKVM这样的实际项目中，RK3568的USB Gadget功能通常需要与其他子系统协同工作。以下是一个典型的集成方案：

1. 视频采集：通过MIPI CSI接口获取视频流
2. 网络传输：使用以太网或WiFi传输视频和控制数据
3. USB模拟：实现键盘和鼠标的HID功能
4. 电源管理：优化功耗以适应长时间运行

配置示例（部分）：

#!/bin/bash # 初始化USB Gadget modprobe libcomposite mount -t configfs none /sys/kernel/config # 设置HID设备 setup_hid() { local name=$1 type=$2 mkdir -p /sys/kernel/config/usb_gadget/g1/functions/hid.$name case $type in keyboard) config_keyboard $name ;; mouse) config_mouse $name ;; esac } # 启动服务 start_service() { udevadm settle -t 5 || : echo "$(ls /sys/class/udc)" > /sys/kernel/config/usb_gadget/g1/UDC systemctl start kvmd }

在实际使用中，我们发现RK3568的USB控制器对多HID设备的支持非常稳定，即使在高速鼠标报告（125Hz）和键盘同时工作时也能保持可靠的性能。不过需要注意，当同时启用USB3.0功能时，可能需要调整DMA缓冲区配置以避免带宽冲突。