# FreeBSD 13 中的人机接口设备 (HID) 支持 * 原文链接：[Human Interface Device (HID) Support in FreeBSD 13](https://freebsdfoundation.org/wp-content/uploads/2021/08/Human-Interface-Device-HID-Support-in-FreeBSD-13.pdf) * 作者：**VLADIMIR KONDRATYEV** HID 类主要由人类用来控制计算机系统操作的设备组成。HID 类设备的典型例子包括键盘、指点设备（如标准鼠标设备、轨迹球和游戏杆）。HID 类的采用主要是为了简化此类设备的安装过程。 在 HID 出现之前，设备通常遵循严格定义的协议。所有硬件设计的改进要么导致现有协议中的数据使用过载，要么需要创建自定义设备驱动程序并将新协议推广给开发人员。与此不同，所有由 HID 定义的设备都提供自描述包，这些包可以包含任何数量的数据类型和格式。关键思想是关于 HID 设备的信息存储在其 ROM（只读存储器）的段中。这些段被称为描述符。计算机上的单个 HID 驱动程序解析这些描述符，并实现数据与应用功能的动态关联，这促进了创新和开发的快速进展，并且带来了人机接口设备的广泛多样化。 在不同类型的描述符中，有一个是任何 HID 设备必须具备的，无论其物理传输方式如何。它被称为 HID 报告描述符。报告描述符规定了设备生成的每一块数据以及该数据所测量的内容。以下是一个 3 按钮鼠标（带滚轮和倾斜功能）的报告描述符示例： ```c 0x05, 0x01, // 使用页（通用桌面） 0x09, 0x02, // 使用（鼠标） 0xa1, 0x01, // 集合（应用） 0x09, 0x01, // 使用（指针） 0xa1, 0x00, // 集合（物理） 0x05, 0x09, // 使用页（按钮） 0x19, 0x01, // 使用最小值（1） 0x29, 0x03, // 使用最大值（3） 0x15, 0x00, // 逻辑最小值（0） 0x25, 0x01, // 逻辑最大值（1） 0x95, 0x03, // 报告计数（3） 0x75, 0x01, // 报告大小（1） 0x81, 0x02, // 输入（数据、变量、绝对值） 0x95, 0x05, // 报告计数（5） 0x81, 0x03, // 输入（常量、变量、绝对值） 0x05, 0x01, // 使用页（通用桌面） 0x09, 0x30, // 使用（X 轴） 0x09, 0x31, // 使用（Y 轴） 0x09, 0x38, // 使用（滚轮） 0x15, 0x81, // 逻辑最小值（-127） 0x25, 0x7f, // 逻辑最大值（127） 0x75, 0x08, // 报告大小（8） 0x95, 0x03, // 报告计数（3） 0x81, 0x06, // 输入（数据、变量、相对值） 0x05, 0x0c, // 使用页（消费类设备） 0x0a, 0x38, 0x02, // 使用（AC 平移） 0x95, 0x01, // 报告计数（1） 0x81, 0x06, // 输入（数据、变量、相对值） 0xc0, // 结束集合 0xc0, // 结束集合 ``` **清单 1. 解码的 3 按钮鼠标报告描述符，带有滚轮和倾斜轴** HID 支持的最初导入来自 NetBSD，始于 1998 年，并与 USB 堆栈一起进行。它包括一个报告描述符解析器和基于此的 3 个驱动程序：ukbd(4)、ums(4) 和 uhid(4)。一个用户空间版本的报告描述符解析器，即 libusbhid(3)，在 2000 年后期被导入。它成为了蓝牙堆栈中 HID 支持的基础，bthidd(8)，并于 2004 年提交。虽然这样的驱动组合主要适用于桌面需求，但它并不适合笔记本电脑和手持设备。微软发布了 HID-over-I2C 规范，几乎所有的笔记本生产商（苹果是主要的例外）都采用了该规范。触摸设备获得了大量市场份额，许多复杂设备也应运而生，这些设备将两个或更多简单设备的功能结合在一起，例如带有鼠标的键盘，或者触摸屏与手写板的结合等。所有这些都促使 HID 子系统的修订。 ## HID 子系统架构 新的 HID 子系统被设计为总线。任何传输总线都可以提供 HID 设备并将其注册到 HID 核心。然后，HID 总线在其上加载通用设备驱动程序。传输驱动程序负责原始数据的传输和设备的设置/管理。HID 核心包含报告解析的辅助例程，并负责自动发现报告描述符中描述的每个顶级集合的子设备。通用设备驱动程序负责报告解释和用户空间 API。设备的具体情况和特性由 hidquirk 处理，原始访问则由 hidraw 驱动程序处理。hidmap 是 HID 项目到 evdev 事件转换器。通用的 HID 功能被移出 USB-HID，进入一个新的子系统，位于 dev/hid 目录下，并成为一个独立的内核模块。这是 Open/NetBSD 在 5 年前所做的。 ![](https://github.com/user-attachments/assets/111ce55e-c060-4d43-993a-bca0cb689798) **HID 子系统架构** ## HID 传输驱动程序 传输总线通常为传输驱动程序提供热插拔检测或设备枚举的 KPI。传输驱动程序利用这些信息来查找任何合适的 HID 设备。它们分配 HID 设备资源并附加 hidbus。hidbus 永远不会知道哪些传输驱动程序可用，也不关心这个问题。它只关心子设备。 传输驱动程序实现了一个抽象的 HID 传输接口，通过设备树提供对 HID 功能和能力的独立访问。基于 kobj 的 HID 接口可以在 sys/dev/hid/hid\_if.m 中找到。一旦 hidbus 子设备被附加，HID 核心使用总线方法与设备通信。目前，FreeBSD 内核支持 USB 和 I2C 驱动程序。 ### hidbus hidbus 是一款驱动程序，提供对多个 HID 驱动程序附加到单个 HID 传输后端的支持。这个功能从一开始就存在于 Net/OpenBSD（uhidev 和 ihidev 驱动程序中），但从未移植到 FreeBSD。与 Net/OpenBSD 不同，我们不是仅仅使用报告编号来区分报告源，而是遵循微软的方式，使用一个顶级集合（TLC）使用来确定报告所属的功能。 TLC 是一个功能组，它面向特定软件消费者（或消费者类型）的功能。操作系统使用与此集合关联的 Usage，将设备与其控制应用程序或驱动程序关联起来。常见的例子有键盘或鼠标。一个带有集成指点设备的键盘可能包含两个不同的应用集合。HID 设备描述每个 TLC 的用途，以便 HID 功能的消费者识别他们可能感兴趣的 TLC。hidbus 为报告描述符中描述的每个 TLC 生成一个子设备，并添加 PnP 字符串以允许 devd/devmatch 检测适当的驱动程序。在运行时，hidbus 将传输驱动程序生成的数据广播到所有子设备。 ```c 0x05, 0x01, // 使用页面（通用桌面控制） 0x09, 0x06, // 使用（键盘） 0xA1, 0x01, // 集合（应用程序） 0x05, 0x07, // 使用页面（键盘/键盘输入） 0x85, 0x01, // 报告 ID（1） 0x19, 0xE0, // 使用最小值（0xE0） 0x29, 0xE7, // 使用最大值（0xE7） 0x15, 0x00, // 逻辑最小值（0） 0x25, 0x01, // 逻辑最大值（1） 0x75, 0x01, // 报告大小（1） 0x95, 0x08, // 报告计数（8） 0x81, 0x02, // 输入（数据，可变，绝对） 0x95, 0x01, // 报告计数（1） 0x75, 0x08, // 报告大小（8） 0x81, 0x01, // 输入（常量，数组，绝对） 0x95, 0x06, // 报告计数（6） 0x75, 0x08, // 报告大小（8） 0x15, 0x00, // 逻辑最小值（0） 0x26, 0xA4, 0x00, // 逻辑最大值（164） 0x05, 0x07, // 使用页面（键盘/键盘输入） 0x19, 0x00, // 使用最小值（0x00） 0x29, 0xA4, // 使用最大值（0xA4） 0x81, 0x00, // 输入（数据，数组，绝对） 0xC0, // 结束集合 0x05, 0x01, // 使用页面（通用桌面） 0x09, 0x02, // 使用（鼠标） 0xa1, 0x01, // 集合（应用程序） 0x09, 0x01, // 使用（指针） 0xa1, 0x00, // 集合（物理） 0x85, 0x02, // 报告 ID（2） 0x05, 0x09, // 使用页面（按钮） 0x19, 0x01, // 使用最小值（1） 0x29, 0x03, // 使用最大值（3） 0x15, 0x00, // 逻辑最小值（0） 0x25, 0x01, // 逻辑最大值（1） 0x95, 0x03, // 报告计数（3） 0x75, 0x01, // 报告大小（1） 0x81, 0x02, // 输入（数据，可变，绝对） 0x95, 0x05, // 报告计数（5） 0x81, 0x03, // 输入（常量，可变，绝对） 0x05, 0x01, // 使用页面（通用桌面） 0x09, 0x30, // 使用（X） 0x09, 0x31, // 使用（Y） 0x15, 0x81, // 逻辑最小值（-127） 0x25, 0x7f, // 逻辑最大值（127） 0x75, 0x08, // 报告大小（8） 0x95, 0x02, // 报告计数（2） 0x81, 0x06, // 输入（数据，可变，相对） 0xc0, // 结束集合 0xc0, // 结束集合 ``` **清单 2.** 集成鼠标的键盘的 HID 报告描述符，包含 2 个 TLC。 ### hidmap hidmap 是一个通用的 HID 项值到 evdev 事件转换引擎，它使得通过定义转换表以声明性方式编写 HID 驱动程序成为可能。创建它的动机是因为现有的 USB-HID 驱动程序由于以下因素而变得庞大： * USB 传输处理 * 字符设备支持代码 * 协议转换例程，例如 HID 到 sysmouse 或 HID 到 AT 键盘集 1 * 报告解析器中的长链条 hid\_locate() 和 hid\_get\_data() p.1 通过传输抽象层得以消除。 为了解决 p.2 对传统支持的问题，鼠标接口被移除。我们使用内置于 evdev 的字符设备处理程序。 为了减少 p.3 和 p.4 所需的代码量，创建了 hidmap。它基于 HID 和 evdev 是密切相关的事实，我们可以直接将许多 HID 用法映射到 evdev 事件。Listing 3 展示了一个将 Listing 1 中的鼠标报告的 HID 用法映射到 evdev 事件的示例。 ```c HID Usage 映射到 evdev 事件 --------- ------------------ 0x05, 0x09, // 使用页 (按钮) 0x19, 0x01, // 使用最小值 (1) BTN_LEFT (BTN_MOUSE+0) 0x29, 0x08, // 使用最大值 (3) BTN_RIGHT (BTN_MOUSE+1) 0x95, 0x08, // 报告计数 (3) BTN_MIDDLE (BTN_MOUSE+2) 0x81, 0x02, // 输入 (数据，变量，绝对值) 0x05, 0x01, // 使用页 (通用桌面) 0x09, 0x30, // 使用 (X) REL_X 0x09, 0x31, // 使用 (Y) REL_Y 0x09, 0x38, // 使用 (滚轮) REL_WHEEL 0x95, 0x03, // 报告计数 (3) 0x81, 0x06, // 输入 (数据，变量，相对值) 0x05, 0x0c, // 使用页 (消费设备) 0x0a, 0x38, 0x02, // 使用 (AC 平移) REL_HWHEEL 0x95, 0x01, // 报告计数 (1) 0x81, 0x06, // 输入 (数据，变量，相对值) ``` **清单 3.** HID 使用映射到 evdev 事件的鼠标报告（来自 Listing 1）。 借助 hidmap，针对这种设备的鼠标驱动程序只需几行代码即可实现。参见 Listing 4。 ```c /* my_mouse 的 HID 使用映射到 evdev 事件 */ static const struct hidmap_item my_mouse_map[] = { { HIDMAP_REL( HUP_GENERIC_DESKTOP, HUG_X, REL_X ) }, { HIDMAP_REL( HUP_GENERIC_DESKTOP, HUG_Y, REL_Y ) }, { HIDMAP_REL( HUP_GENERIC_DESKTOP, HUG_WHEEL, REL_WHEEL ) }, { HIDMAP_REL( HUP_CONSUMER, HUC_AC_PAN, REL_HWHEEL ) }, { HIDMAP_KEY_RANGE( HUP_BUTTON, 1, 3, BTN_MOUSE )}, }; /* 匹配这些条目将加载 my_mouse */ static const struct hid_device_id my_mouse_devs[] = { { HID_TLC( HUP_GENERIC_DESKTOP, HUG_MOUSE ) }, }; static int my_mouse_probe( device_t dev ) { return(HIDMAP_PROBE( device_get_softc( dev ), dev, my_mouse_devs, my_mouse_map, “ My mouse ” ) ); } static int my_mouse_attach( device_t dev ) { return(hidmap_attach( device_get_softc( dev ) ) ); } static int my_mouse_detach( device_t dev ) { return(hidmap_detach( device_get_softc( dev ) ) ); } ``` **清单 4.** 基于 hidmap 的鼠标驱动示例（来自列表 1）。 例如，真正的 FreeBSD 鼠标驱动已从传统的 ums(4) 中的 \~1200 行代码减少到基于新 HID KPI 的 \~330 行代码。此外，它增加了 ums(4) 中缺失的 I2C 和绝对坐标支持，以及用于解决 FreeBSD 在 x86 上缺少 GPIO 中断支持所带来的问题的漂移抑制代码。这种简化使得作者和 Greg V 能够创建一系列基于 hidmap 的驱动程序，这些驱动程序捆绑在 FreeBSD 13+ 中，包括： * hms - HID 鼠标驱动 * cons - 消费者页面，亦称为多媒体键驱动 * hsctrl - 系统控制页面（电源/休眠键）驱动 * hpen - 通用 / 与 MS Windows 兼容的 HID 手写板驱动 * hgame - 游戏控制器和摇杆驱动 * xb360gp - Xbox360 兼容游戏控制器驱动 * ps4dshock - 索尼 DualShock 4 游戏手柄驱动 还有一些不是基于 hidmap 的驱动程序，如 hkbd(4) 和 hmt(4)。它们是现有 USB-HID 驱动程序（如 ukbd(4) 和 wmt(4)）移植到新基础设施上的结果。它们为 I2C 键盘和 I2C 多点触控触摸板/触摸屏提供支持。 ### 其他模块 HID 子系统包含另外两个可选加载的模块： hidraw(4) - 提供对 HID 设备的原始访问的驱动程序，类似于 uhid(4)。与 uhid(4) 不同，它允许访问已被其他驱动程序占用的设备，并支持 uhid 和 Linux hidraw 接口。 Hidquirk(4) - 主要从现有 USB-HID 驱动程序复制的怪癖模块。 ## 结论与后续工作 FreeBSD 的 HID 子系统仍在开发中，但已被许多人使用。最近的工作增加了对广泛使用的硬件的支持，例如 I2C 触摸板和触摸屏、USB 键盘上的多媒体键、许多虚拟机中使用的绝对鼠标等。这改善了我们在一些领域的用户体验，特别是我们在其他操作系统（包括其他 BSD 系统）中落后的地方。但仍有许多任务留在待办事项列表中，例如： * 实现 usrhid，一个用户空间的传输驱动程序，可以为连接到用户空间控制总线的每个设备创建内核 hid 设备。现有的 Linux uhid 协议可以作为起点。它定义了一个 API，用于从内核到用户空间以及反向提供 I/O 事件。 * 将 bthidd(8) 转换为使用 usrhid，从而整合内核和用户空间之间的 HID 支持。 * 完成 evdev-aware 的 WIP moused [https://github.com/wulf7/moused，并用它替换我们内核和基础系统中的](https://github.com/wulf7/moused%EF%BC%8C%E5%B9%B6%E7%94%A8%E5%AE%83%E6%9B%BF%E6%8D%A2%E6%88%91%E4%BB%AC%E5%86%85%E6%A0%B8%E5%92%8C%E5%9F%BA%E7%A1%80%E7%B3%BB%E7%BB%9F%E4%B8%AD%E7%9A%84) moused(8)。这是必要的，因为新的 hms 和 hmt 驱动程序不支持我们的传统 sys/mouse.h 接口。 * 默认启用 usbhid(4)，并开始弃用 ums(4)、ukbd(4) 以及其他旧版 USB-HID 驱动程序，同时弃用内核和基础系统中的所有 mouse(4)/sysmouse(4) 内容。 *** **VLADIMIR KONDRATYEV** 是一名前 FreeBSD 系统管理员，目前是一名核心银行系统专家。自 2017 年以来，他一直是 FreeBSD 的提交者，并且已使用 FreeBSD 桌面系统近 20 年。在业余时间，他努力改善桌面体验，主要为输入设备驱动程序做贡献。