[mashen11]

这是什么

同一台机器（gaokun3 / MateBook E Go，CSOT ppc357db1-4 + HX83121A 级联从片）在
Linux 侧的笔实现：文档 + 纯 Python 参考代码。

和本项目走的是两条不同的路：

	本项目	这个 PR
笔坐标	主片 / BT-MCU	级联从片 spi20 的原始帧
平台	Windows 11 ARM64	Linux（实测 7.2.9）
输出	HID 注入	uinput stylus + cursor 镜像

但两边用的是同一对 IC、同一套硬件约定（raw_out_sel=0xF6、rawdata_addr=0x5AA5、
ICID=0x83121a00、MCU 事件 0x08/0x09/0x71、压感 ReportID 0x55），所以下面的数字
可以和贵项目的抓包结论直接对表。

为什么可能对你有用

README 里写着 Active Stylus / BT-MCU integration is temporarily disconnected in this
branch。这份文档补的正是"笔"这块的另一条独立实现，而且有几条与平台无关的坑：

1. 从片的初始化必须晚于主片的 FW reload（见下）——这是"主片 + 级联从片"的时序问题，
   与语言无关；
2. 从片相对主片只差两处（F5/F4 操作码 + 两个必须写的寄存器），不写第二个会稳定回全零帧；
3. 倾斜轴向与上游 gk3pend 的写法相反（左右倾改列、前后倾改行）；
4. 被动耦合在主片网格上分不开"极近悬停"与"轻触"（best 140–360 vs 400–580 重叠），
   我们在主片上试了 16 个内核补丁后整体退役 —— 这条可以作为"别在主片上做笔"的结论。

那条时序结论（最值得参考的部分）

现象：开机后能画，但悬停光标满屏乱跳、点击不灵敏；重载一次驱动即恢复。

根因：从片 probe（~3.5 s）早于主片 pin reset + FW reload（~4.2 s）。在那之前写
raw_out_sel = 0xF6，级联 TX1 锚点通路还没就绪。同一 boot 内 A/B：

重载前：tx1_valid 12~28%，锚点列在 2→52 之间乱跳，坐标满屏飞
重载后：tx1_valid 64.6%，锚点列收敛到 12~25，光标平滑

看门狗重写同一个寄存器救不回来（问题在写入时机，不在值）；只有整模块重载能恢复。
修法是 probe 里等 2.5 s（msleep），之后 slave init 落在 FW reload done 之后 2 s：

19:31:21  himax-spi spi1.0: FW reload done
19:31:23  himax-hx83121a-pen spi0.0: slave init 0
（开机那条 "watchdog: no frame for 1 s, re-init #1" 彻底消失，wd_reinits 0）
悬停帧间位移 p50 2 px / p90 6~21 px，压力 p50 2015~2695

内容

• docs/linux-pen-slave.md —— 拓扑、协议、五条定案、用户态踩坑（为什么必须报
  BUS_USB、Mutter 50 为什么需要 cursor 镜像补 BTN_LEFT）、复现步骤、未解决项
• Tools/LinuxPenSlave/ —— 两个纯 Python 文件（无第三方依赖）：
  • gk3pend.py：从片帧 + MCU 压感 → uinput 笔（含镜像设备）
  • gk3pen_solver.py：帧 → 坐标 / 倾斜解算

不参与 CMake 构建：顶层 CMakeLists.txt 没有 add_subdirectory(Tools/...)，
Tools/ 下各项本来就是独立的，这两个文件只是参考实现。如果你更希望它只作为文档附录，
我可以把它们移到 docs/LinuxPenSlave/ 并重开 PR。

许可

• 本 PR 新增的两个 Python 文件：MIT（文件头 SPDX）。
• gk3pen_solver.py 的算法移植自 Android 侧 gk3pend/solver.h（SPDX: GPL-2.0 AND MIT），
  其 HPP3 步骤的更早来源即本项目的 EGoTouchRev-rebuild ⇒ 双许可允许以 MIT 分发，
  原始声明保留在模块 docstring 里。
• 内核侧代码不随本 PR 提交（MODULE_LICENSE("GPL") = GPL-2.0，与 MIT 不兼容），
  文档中给出外链：mashen11/MateBookEgo-linux-kernel →
  patches/common/linux-gaokun/0083…0110。

未解决（如实列出）

1. 从片在"极近悬停"仍偶发幽灵上报（peak 300–700 边界效应），彻底解需要主动笔 HPP；
2. 倾斜幅度未校准（物理 45° 报 ~69°，沿用上游常数）；
3. 手掌误触：uinput 笔没有 ID_PATH，libinput 的 touch arbitration 用不上；
4. 帧率退化：头 2–3 s 165 Hz，之后 ~37 Hz（疑似帧泵停住而非降频）。