Skip to content

v1.0.0-beta1 — First public beta

Pre-release
Pre-release

Choose a tag to compare

View all tags
@Syax89 Syax89 released this 08 Jul 17:25
v1.0.0-beta1
ced49eb

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 two DKMS packaging bugs found live within hours of release (both only surfaced after a real kernel update — 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

Both found live on real hardware within hours of the initial publish, after a routine system update installed new kernels:

  • 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 — no functional difference for users, just a packaging detail.
  • 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.

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).
  • This is beta software for a reverse-engineered, undocumented hardware protocol. Please open an issue if you run into problems.
Assets 2
Loading