-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Syax89 edited this page Jul 8, 2026
·
4 revisions
Linux HID-over-SPI driver for the touchscreen on the Microsoft Surface Laptop 4 (AMD)
— ACPI device MSHW0231, on the AMD FCH AMDI0060 SPI controller.
This wiki explains how the driver works. For the full reverse-engineering journal (every
experiment, every dead end, every measurement) see
docs/GROUND_TRUTH.md
in the main repo — this wiki is the "here's the design" complement to that "here's how we got
here" journal.
Current release: 1.0.0-beta1 (see the repo's VERSION file).
| Feature | Status |
|---|---|
| Device init (reset → descriptor → report descriptor) | Stable |
| Single-touch (Report ID 0x40) | Stable, working |
| Pen/Stylus (Report ID 0x01) | Stable, working |
Multi-touch (raw_mode=1) |
Experimental — blob detection works, but the mode-switch handshake is unreliable |
Want to try it? See Building, Usage and Troubleshooting
for the one-command beta installer (tools/install.sh).
The driver ships two kernel modules:
-
spi-amd.ko(driver/spi-amd.c) — the AMD FCH SPI controller driver -
spi-hid.ko(driver/spi-hid-core.c) — the HID-over-SPI transport + protocol state machine
- Architecture — how the two modules fit together, the IRQ-driven state machine, and why this device needed a custom driver instead of the generic upstream one
- Wire Protocol — the HID-over-SPI "V0" byte format this device actually speaks, and the AMD FCH SPI controller registers used to talk to it
- Report Descriptor — the 936-byte HID report descriptor, why it's read live from the device instead of fully hardcoded, and the one hardware quirk that needs patching
- Standard Touch Mode — how single-touch and pen actually work today (the stable, default path)
-
Multi-touch Experimental —
raw_mode=1: raw heatmap streaming, blob detection, and the still-unsolved reliability problem - Building, Usage and Troubleshooting — how to build, load, and debug the driver, module parameters, and recovery tools
- Further Reading — pointers into the main repo for deeper technical detail (the full investigation journal, register maps, decompiled Windows/UEFI drivers)
| Component | Value |
|---|---|
| Touchscreen ACPI HID |
MSHW0231 (falls back to generic PNP0C51) |
| SPI controller |
AMDI0060 (AMD FCH Cezanne) |
| Controller MMIO base | 0xFEC10000 |
| SPI mode | Mode 0 (CPOL=0, CPHA=0), up to 33.33 MHz |
| Vendor/Product/Version ID |
0x045E / 0x0C19 / 0x0004
|
| Report descriptor length | 936 bytes |