The porting flow covers the macos-27.3-26C5035r profile from profile selection to the porting record: the macOS profile page lists the profile contents, host inputs, board.toml override, Data seed, build commands, driver adaptations and boot checkpoints, and the steps, arm64e, packaging, records, bring-up, building, requirements and reference pages point to it. The iPadOS instructions are unchanged. Porting pages link porting pages for driver topics: Develop a driver and Brightness interface are porting pages, and component names in porting pages are plain text. English and Chinese pages.
7.0 KiB
触控、按键与键盘适配
先完成显示几何参数和中断/DMA 配置。 记录触控芯片、固件、矩阵尺寸、物理方向、总线连接、复位/中断引脚及 OS HID ABI。
实现后按驱动接入步骤连接初始化调用、归档配方和 OS ABI, 再执行本页对应的硬件验证。
源码与接口
以下链接固定到已核对的源码版本。使用所选 SoC、组件和 OS 版本核对接口; 链接的设备源码提供板级集成示例。
| 实现部分 | 源码 | 阅读与实现内容 |
|---|---|---|
| 总线与传感器 | GeniSpi.h, NvtProtocol.h | nvt_bus、芯片识别、固件下载和帧读取 |
| 触点处理 | NvtTouchCore.c | 所支持传感器的矩阵处理与触点跟踪 |
| 板级集成 | TouchBoard.h, TouchProbe.cpp | 电源/复位、传输回调、中断处理与坐标 |
| 键盘壳 | Wn8030.h, KeyboardProbe.cpp, KeyboardCover.cpp | 控制器固件加载、帧编解码、插拔与霍尔门控、键盘与触控板共用的 HID 设备 |
| OS 报告 | NativeHidInput.cpp, ButtonProbe.cpp | IOHIDDevice、报告描述符、一致的触点快照和按键事件 |
1. 选择传输与传感器协议
阅读 QcomGeniSpi、
ShengNovatekTouch 和 ShengHidInput。
不同传感器需要实现其识别、固件和报告协议。复用 Novatek 协议但更换总线控制器时,
实现 nvt_bus 所需的传输与延时回调。
实现 nvt_bus.xfer 时保持整次全双工传输期间片选有效,按 NvtProtocol.h 提供调用方拥有的缓冲区和延时回调。
按顺序调用 nvt_identify、nvt_fw_parse、nvt_download_firmware、nvt_read_frame。
每步检查返回码;固件下载失败时保存阶段、CRC 和 SRAM 回读诊断,再处理下一次重试。
将解码后的触点快照交给 HID 层,发布时保持坐标、ID 和触点数量来自同一帧。
2. 适配板级路径
- 根据目标 DTS 和时钟/引脚定义设置控制器窗口、总线模式/速率、GPIO、中断和 SMMU stream。
TouchBoard.h提供板级数据布局参考。 - 实现电源/复位控制,确认引擎固件、引脚和时钟。
- 按目标 SMMU context 设置 DMA 寻址和缓存维护。
- 读取芯片 ID,再加载固件并确认返回的几何参数。
- 解码完整帧,将坐标变换到显示方向。
- 检查稳定接触 ID、多点、边缘行为和抬起事件。
Novatek 处理核心使用 40 × 60 矩阵。修改固件或处理核心时核对几何尺寸和边界。
固件提取由设备的 scripts/gen-touch-firmware.py 与私有文件清单管理。
参考探针参数 touch=1、2、3、4 分别选择资源检查、时钟/引脚、控制器识别和固件/扫描。
先适配该阶段使用的硬件参数,再启用相应阶段。
预期结果: 得到显示坐标系中的一致接触帧,包含抬起事件。
HID 层通过序列计数器读取 native_touch_*;替换生产方时保留快照一致性。
3. 发布 HID 报告
使用选定 kernelcache 确认 IOHIDFamily 方法和对象布局。 参考归档配方使用预链接候选内核与 ABI 记录,见构建输入。 按传感器适配报告描述符、逻辑坐标范围和接触数量上限。
在完整组件列表选择传感器、传输和 HID 组件。参考显示配方链接传感器与总线对象,
HID 配方绑定 OS 接口;touch-hid=1 启用触控发布路径。在目标构建树检查:
rg -n 'TouchProbe|GeniSpi|NvtProtocol|NvtTouchCore|NvtFirmware' scripts/build-gop-legacy-display.py
rg -n 'native_touch_|ReportDescriptor' drivers/ShengHidInput/NativeHidInput.cpp
预期结果: OS 收到各接触点正确的按下、移动和抬起报告,UI 手势与面板方向一致。
4. 适配实体按键
参考源码索引中的 ButtonProbe.cpp 实现中断采样和 HID 按键事件。
映射目标 GPIO 或 PMIC 输入、极性、所有权、中断路由和应答操作。
仅访问当前执行环境拥有的 PMIC 外设。SPMI 控制器变化时适配 BootResetCore.h 辅助接口。
将按下/释放状态接入 HID consumer 报告。参考实现使用 report 2 的 Power、Volume Increment
和 Volume Decrement 位,参数 buttons=1 启用该路径。
预期结果: 每次按下和释放产生正确报告,包括长按和同时按键,中断活动保持有界。
5. 适配键盘壳
控制器挂在 I2C 上的键盘壳以一个 IOHIDDevice 接入系统。同一服务满足以下条件时,
iPadOS 的 SmartCoverServiceFilter 生成触控板手势:
- 具备 Keyboard(1/6)、Touch Pad(0x0d/5)和 Finger(0x0d/0x22)用法对。 只有 Application 和 Physical 集合计入,因此每个手指是 Physical 集合。
- Transport 不含
test。 - X、Y 物理范围以厘米为单位(unit 0x11)。事件驱动只把该单位换算为
SurfaceDimensions。
Keyboard Power(键盘页,usage 0x66)同时作为输入和特性元素时设置 KeyboardEnabled;
键盘翻到背面或合上时报 0,系统显示软键盘。
按 HID 约定核对触控板 Y 方向,并把 Touch Valid 为 0 的按下触点报为抬起: 该手掌是一帧最后一个子事件时,过滤器会使 backboardd 中止。
sheng 参考实现通过 boot ROM 加载 WN8030 RAM 固件,每次中断读取一帧 68 字节,
并用霍尔传感器门控输入。参数 keyboard=1 启用该路径。
预期结果: 打字、Caps Lock、指针与滚动手势正常;翻到背面或合上时输入关闭;拔下后设备移除。
下一步
按构建指南重建,分别记录触控、按键与键盘结果,再进入 GPU 适配。
arm64e 的公开源码构建方法及当前链接、运行时限制见公开源码驱动构建。历史 iOS 17 真机结果不代表该路径已通过验证。