Skip to content
BranchesTags
 
 

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
hid-multitouch-fix
hid-multitouch-fix
 
 
mt-fix
mt-fix
 
 
.gitignore
.gitignore
 
 
FIX.md
FIX.md
 
 
README.md
README.md
 
 
install-patched-module.sh
install-patched-module.sh
 
 

Repository files navigation

Fix-touchpad

修复 HTIX5288 (0911:5288) 触摸板在 Linux 下双指快速滑动后抬指的"幽灵双指"bug。

本仓库同时维护两套方案：上游 Arch 方案（原仓库内容，mt-fix/）与 Debian 方案（本 fork 新增，hid-multitouch-fix/，用于本笔记本）。

致谢

本项目 fork 自 xjimlinx (Xein) 的开源项目 Fix-touchpad。

由衷感谢来自NPU（西北工业大学）的原作者 Xein 的出色工作

所以是怎么能翻出来win8的触控板的协议的

本 fork 仅在其基础上补充了 Debian 适配与自动化重打补丁脚本，核心修复成果全部归功于原作者。

问题

双指快速滑动滚动条 → 抬掉一根手指 → 剩余手指仍被识别为两指，指针/滚动冻结在抬指位置。

根因

hid-multitouch 内核驱动将 HTIX5288 错配为 MT_CLS_NSMU（仅带 NOT_SEEN_MEANS_UP），缺少 Win8 精准触摸板应有的 MT_QUIRK_CONTACT_CNT_ACCURATE 和 MT_QUIRK_IGNORE_DUPLICATES，导致抬指后的陈旧坐标污染剩余手指的 slot。

修复

一行改动：MT_CLS_NSMU → MT_CLS_WIN_8_FORCE_MULTI_INPUT_NSMU（0x000a → 0x0018）。详见 FIX.md。

2024 年 12 月的内核提交 b5e65ae 首次修复了同设备"抬指信号丢失"（NSMU），但遗漏了 CONTACT_CNT_ACCURATE 导致幽灵坐标污染。此补丁在其基础上补全。

本笔记本配置

本 fork 在以下环境中开发与验证：

项目 值
机型 MECHREVO WUJIE14 PRO（机械革命 无界14 Pro）
CPU AMD Ryzen 7 7840HS（含 Radeon 780M 核显）
系统 Debian GNU/Linux 13 (trixie)
内核 6.12.101+deb13-amd64
桌面 niri（Wayland 合成器；系统同时装有 KDE Plasma）
触控板 HTIX5288:00 0911:5288（I2C HID，Bus 0018，Goodix/Hantick）
触控板 sysfs /devices/platform/AMDI0010:03/i2c-0/i2c-HTIX5288:00/0018:0911:5288.0001

触控板以 I2C 方式挂载在 AMDI0010:03（AMD I2C 控制器）下，HID 设备地址为 0018:0911:5288.0001，内核模块为 hid_multitouch。

仓库结构

Fix-touchpad/
├── FIX.md                        # 上游补丁原理说明
├── README.md
├── install-patched-module.sh     # 上游 Arch 安装脚本
├── mt-fix/                       # 上游 Arch 方案：模块源码 + 编译产物 (zstd)
└── hid-multitouch-fix/           # ★ 本 fork 新增：Debian 适配目录
    ├── hid-multitouch.c          # 打补丁后的驱动源码（修复核心）
    ├── hid-ids.h                 # 设备 ID 定义（0x0911 / 0x5288）
    ├── Kbuild                    # 构建描述（obj-m）
    ├── reapply.sh                # ★ 一键修复脚本（内核升级后可自动重打）
    ├── README.md                 # Debian 目录的详细说明
    ├── hid-multitouch.ko         # 编译产物（ELF 内核模块）
    ├── hid-multitouch.ko.xz      # 压缩版（Debian 实际部署文件）
    └── ...                       # 其余为 kbuild 中间/记录文件，可安全删除

两套方案的区别

上游 Arch（mt-fix/） Debian（hid-multitouch-fix/）
目标发行版 Arch Linux Debian / Ubuntu 等
模块格式 .ko.zst（zstd） .ko.xz（XZ）
安装脚本 install-patched-module.sh reapply.sh
主要特点 静态编译安装 自动化检测 + 打补丁 + 编译 + 重载 + 刷 initramfs

适用的发行版

原仓库的 install-patched-module.sh 是为 Arch 设计的，无法直接在 Debian 上运行：

项 原仓库 install-patched-module.sh Debian reapply.sh
模块格式 .ko.zst（Debian 内核不支持 zstd，CONFIG_MODULE_COMPRESS_ZSTD 未开启） .ko.xz（Debian 支持）
编译产物 无（mt-fix/ 只有源码，脚本会直接报错退出） 自动下载源码 + 编译
内核版本 绑定 Arch 7.1.3-arch1-2（vermagic 不匹配，无法跨版本加载） 针对当前 Debian 内核编译
设备地址 硬编码 0018:0911:5288.0008 自动检测当前设备

其中"模块格式"和"内核版本"是硬性障碍：Debian 内核未开启 zstd 模块压缩支持，且内核模块严格绑定内核版本（vermagic 不一致即拒绝加载）。

修复脚本逻辑（reapply.sh）

hid-multitouch-fix/reapply.sh 是本 fork 新增的一键修复脚本，内核升级后无需人工重新编译。整体流程：

① 检测当前内核模块是否为补丁版
      │
      ├─ 已是补丁版 → 跳过编译，直接 ② 重载 + ③ 刷 initramfs
      │
      └─ 原厂版 → 准备重新打补丁
            ├─ 拉取对应内核版本的官方源码
            ├─ 检测上游是否已官方修复 → 是则直接用原厂模块
            ├─ 否则 sed 打补丁 → 编译 → 压缩 → 安装（自动备份原模块）
            └─ depmod
② 在线重载模块（unbind → modprobe -r → modprobe → bind，免重启）
③ update-initramfs -u（保证重启后仍加载补丁版）

关键设计：

  • 幂等：每次执行先检查系统模块，用 strings | grep intree 区分"原厂版"和"补丁版"——补丁版由 kbuild 外部编译，不含 intree 标记。已是补丁版则秒过，绝不重复编译。
  • 上游已修复时自动放弃：编译前先 grep 最新源码的 Hantick 条目，若上游已改用 MT_CLS_WIN_8_FORCE_MULTI_INPUT_NSMU，直接使用原厂模块，不打多余补丁。
  • 安全回滚：安装前自动备份原模块为 .ko.xz.backup；加载失败自动恢复备份。
  • 内核兼容：编译用 PAHOLE=/bin/true 跳过 BTF，避免 split BTF 与运行内核不匹配导致加载 EINVAL；压缩按内核标准 --check=crc32 --lzma2=dict=2MiB。
  • 免重启：通过 sysfs unbind/bind + modprobe 在线重载，无需重启即可生效。

原 install-debian.sh 仅负责"把编译好的 .ko.xz 拷入系统并重载"，其功能已被 reapply.sh 完全覆盖（reapply 额外处理检测、打补丁、编译、initramfs），故已移除，统一使用 reapply.sh。

安装（Debian / 本笔记本）

cd hid-multitouch-fix
sudo bash reapply.sh

脚本会自动完成：检测 → 打补丁 → 编译 → 安装 → 重载 → 刷 initramfs，全程无需重启。

若系统缺少内核编译头文件，脚本会提示先安装：

sudo apt install linux-headers-$(uname -r)

恢复原始模块

sudo cp /lib/modules/$(uname -r)/kernel/drivers/hid/hid-multitouch.ko.xz.backup \
        /lib/modules/$(uname -r)/kernel/drivers/hid/hid-multitouch.ko.xz
sudo depmod && sudo modprobe -r hid_multitouch && sudo modprobe hid_multitouch

验证补丁生效

cat /proc/sys/kernel/tainted          # 应非 0（说明载入了非官方/未签名模块）
grep hid_multitouch /proc/modules     # 模块已加载
sudo dmesg | grep -i multitouch       # 无 'Touch jump' 等报错

安装（上游 Arch 方案，原仓库）

sudo ./install-patched-module.sh

受影响硬件

Chuwi Minibook, GPD Win Mini, T-bao Tbook Air, Cube Thinker, EZBook 3 Pro, Polaroid 1400, Mediacom FlexBook, 部分 Huawei 设备等。

环境

  • Debian（本笔记本）：Debian 13 (trixie)，内核 6.12.101+deb13-amd64，niri / KDE Plasma（Wayland），HTIX5288:00 0911:5288（I2C HID）
  • 上游 Arch：Arch Linux，内核 7.1.3-arch1-2，KDE Plasma / Wayland，HTIX5288:00 0911:5288 Touchpad

About

based on the origin repository to generate a fix shell for debian13

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages