v1.0.0-beta1 — First public beta

SL4A_TouchScreen v1.0.0-beta1

First beta release of the Linux HID-over-SPI driver for the Microsoft Surface Laptop 4 (AMD) touchscreen (ACPI device MSHW0231, AMD FCH AMDI0060 SPI controller).

Updated shortly after initial publish: fixed several DKMS packaging bugs found live within hours of release, all surfaced by real kernel updates on real hardware — see "Fixed in this update" below. If you installed before this update, just re-run sudo ./tools/install.sh to pick up the fix.

What works in this build

• Single-touch is stable and working via the device's standard HID mode (Report ID 0x40) — tap, drag, and single-finger gestures all work correctly under KDE/Wayland.
• Pen/Stylus is stable and working (Report ID 0x01).
• Device initialization (reset → device descriptor → HID report descriptor) is reliable — the 936-byte report descriptor is read live from the device every boot (98.5%) with a targeted patch for a characterized hardware quirk in the remaining bytes.

What's experimental in this build

• Multi-touch (2+ fingers) is available behind an opt-in raw_mode=1 module parameter. The blob-detection algorithm itself works correctly (verified with real 2-finger input), but the handshake that switches the device into raw sensor-streaming mode only succeeds intermittently, for reasons not yet fully understood. A built-in watchdog retries automatically, but this path is not recommended for daily use — stick to the default (raw_mode=0) for a stable experience.

See the wiki for a full explanation of how the driver works, and docs/GROUND_TRUTH.md for the complete reverse-engineering journal.

Install (simplest way)

git clone https://github.com/Syax89/SL4A_TouchScreen.git
cd SL4A_TouchScreen
sudo ./tools/install.sh

That's it. The script:

1. Checks that your system actually has the MSHW0231 touchscreen and the build tools it needs (dkms, make, clang/gcc, kernel headers).
2. Builds spi-amd.ko + spi-hid.ko via DKMS, so they're automatically rebuilt for every kernel you install afterward — no manual rebuilding after a kernel update.
3. Installs a systemd service so the driver loads automatically on every boot, in the stable single-touch + pen configuration.

Your touchscreen and pen should start working immediately after the script finishes — no reboot required.

To remove everything the installer added:

sudo ./tools/uninstall.sh

Requirements

• A Surface Laptop 4 (AMD) with the MSHW0231 ACPI touchscreen device.
• dkms, make, kernel headers for your running kernel, and either clang or gcc (whichever your kernel was itself built with — the installer detects and requires the right one).
• This is an unsigned out-of-tree kernel module — if your system enforces Secure Boot strictly, you may need to enroll DKMS's MOK signing key (see your distribution's DKMS + Secure Boot documentation).

Fixed in this update

All found live on real hardware within hours of the initial publish, across two rounds of real system/kernel updates:

• DKMS module name/version corruption on kernel updates. The initial version string (1.0.0-beta1) contained a hyphen, which Arch/CachyOS's own pacman DKMS hook mis-parses (it splits the source directory name on the last hyphen to guess the module name/version), silently re-registering the module under the wrong name on every kernel update and failing to build for the new kernel. Fixed by using 1.0.0~beta1 internally.
• A stale leftover source directory from before that same hotfix kept getting rediscovered by the same pacman hook (which scans /usr/src/*-*/dkms.conf directly, independent of DKMS's own bookkeeping) on every later kernel update, producing noisy "Bad return status" errors during pacman -Syu — even though the correctly-named installation kept working throughout. install.sh/uninstall.sh now sweep and remove any leftover source directory from a previous version automatically.
• Build failure on non-CachyOS kernels. The build unconditionally passed LLVM=1, which is only correct for kernels built with clang (like CachyOS's). A plain Arch kernel (built with gcc) rejects those clang-only flags and failed to build. The installer now detects each kernel's own compiler automatically from its .config.
• A module autoload race between spi-amd.ko and spi-hid.ko on systems where DKMS has already registered a module alias — loading order adjusted to avoid it.

Known limitations

• Multi-touch is experimental (see above).
• Once raw_mode=1 is used, the device stays in raw mode until a full reboot (a persistent device-side state that isn't cleared by a software power-cycle).
• Right after a kernel package update (before rebooting), systemctl status sl4a-touch may show failed — this is expected (DKMS can no longer build for the old, currently-running kernel once its headers are removed) and harmless; the already-loaded modules keep working for the rest of that session, and the service starts cleanly again after rebooting into the new kernel.
• This is beta software for a reverse-engineered, undocumented hardware protocol. Please open an issue if you run into problems.