Files
UniXNU/docs/zh/porting/input.md
UniXNU Docs 1446f449b6 docs(porting): cover the macOS path
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.
2026-11-10 19:26:10 +08:00

7.0 KiB
Raw Permalink Blame History

触控、按键与键盘适配

先完成显示几何参数和中断/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. 适配板级路径

  1. 根据目标 DTS 和时钟/引脚定义设置控制器窗口、总线模式/速率、GPIO、中断和 SMMU stream。 TouchBoard.h 提供板级数据布局参考。
  2. 实现电源/复位控制,确认引擎固件、引脚和时钟。
  3. 按目标 SMMU context 设置 DMA 寻址和缓存维护。
  4. 读取芯片 ID,再加载固件并确认返回的几何参数。
  5. 解码完整帧,将坐标变换到显示方向。
  6. 检查稳定接触 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 真机结果不代表该路径已通过验证。