# 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 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 年。在业余时间，他努力改善桌面体验，主要为输入设备驱动程序做贡献。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://book.bsdcn.org/qi-kan/20210708-zhuo-mian-wu-xian-wang/hid.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.