FreeBSD 13 中的人机接口设备 (HID) 支持

• 原文链接：Human Interface Device (HID) Support in FreeBSD 13

• 作者：VLADIMIR KONDRATYEV

HID 类主要由人类用来控制计算机系统操作的设备组成。HID 类设备的典型例子包括键盘、指点设备（如标准鼠标设备、轨迹球和游戏杆）。HID 类的采用主要是为了简化此类设备的安装过程。

在 HID 出现之前，设备通常遵循严格定义的协议。所有硬件设计的改进要么导致现有协议中的数据使用过载，要么需要创建自定义设备驱动程序并将新协议推广给开发人员。与此不同，所有由 HID 定义的设备都提供自描述包，这些包可以包含任何数量的数据类型和格式。关键思想是关于 HID 设备的信息存储在其 ROM（只读存储器）的段中。这些段被称为描述符。计算机上的单个 HID 驱动程序解析这些描述符，并实现数据与应用功能的动态关联，这促进了创新和开发的快速进展，并且带来了人机接口设备的广泛多样化。

在不同类型的描述符中，有一个是任何 HID 设备必须具备的，无论其物理传输方式如何。它被称为 HID 报告描述符。报告描述符规定了设备生成的每一块数据以及该数据所测量的内容。以下是一个 3 按钮鼠标（带滚轮和倾斜功能）的报告描述符示例：

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 年前所做的。

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 将传输驱动程序生成的数据广播到所有子设备。

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 事件的示例。

                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。

/* 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，并用它替换我们内核和基础系统中的 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 年。在业余时间，他努力改善桌面体验，主要为输入设备驱动程序做贡献。