Skip to content

Home

Jump to bottom
Syax89 edited this page Sep 19, 2026 · 11 revisions

SL4A TouchScreen — Linux Kernel Driver

A reverse-engineered Linux kernel driver for the Microsoft Surface Laptop 3/4 (AMD) touchscreen: standard HID single-touch (pen node published, unvalidated) plus a beta raw-heatmap multi-touch pipeline.

The driver speaks the pre-release HID-over-SPI Version 0 (V0) protocol that these panels use, over the AMD FCH SPI controller (AMDI0060). It is a from-scratch implementation validated against the reference Windows stack and real hardware — not a fork of an in-tree driver.

Supported hardware

Component Identity Notes
Surface Laptop 4 (AMD) touch controller ACPI MSHW0231 (HID 045E:0C19) 72×48 grid, 3456 CapImg cells
Surface Laptop 3 (AMD) touch controller ACPI MSHW0162 78×52 grid, 4056 CapImg cells
SPI controller (both) AMDI0060 (AMD Cezanne FCH SPI V2, MMIO 0xFEC10000) PIO mode, 33.33 MHz, mode 0

The driver selects device-specific tuning (grid geometry, CapImg sample count, baseline length) from the ACPI ID at probe time — see Architecture.

Two operating modes

Mode raw_mode What you get Status
Standard HID 0 (default) Single-touch (pen node published, unvalidated), firmware-computed coordinates, ~10 ms reports (field observation) Qualified profile, recommended
Raw heatmap 1 Sensor-grid data processed host-side into multi-touch Beta

Standard Touch Mode is what you should run day to day. Multi-touch (Beta) documents the raw path and its caveats.

Quick start

git clone https://github.com/Syax89/SL4A_TouchScreen.git
cd SL4A_TouchScreen
sudo ./tools/sl4a-touch.sh install     # hardware check, DKMS build, boot service
sudo reboot

After reboot the driver binds automatically. Verify with:

sudo ./tools/sl4a-touch.sh status      # hardware + runtime state
sudo evtest                            # pick "spi 045E:0C19", touch the screen

Full instructions: Build & Install · Usage & Troubleshooting.

How it works, in one picture

Linux input subsystem (evdev)
        ▲
   hid-generic / hid-input         ┌───────────────────────────┐
        ▲                          │  raw_mode=1               │
   hid_input_report()              │  heatmap → baseline →     │
        │                          │  peaks → CCL → Hungarian  │
  ┌─────┴──────────┐               │  → MT slots → input_mt    │
  │ spi-hid-core   │◄──────────────┤  (mshw0231-raw.c)         │
  │ V0 protocol +  │               └───────────────────────────┘
  │ IRQ sequencer  │
  └─────┬──────────┘
        │ SPI transfers
  ┌─────┴──────────┐
  │ spi-amd        │   AMD FCH SPI V2 PIO controller
  └─────┬──────────┘
        │ SPI bus (33.33 MHz, mode 0)
   MSHW0231 / MSHW0162 touch controller

The two kernel modules, the sequencer state machine and the IRQ model are described in Architecture; the wire format in Protocol and Wire Protocol.

Wiki map

Page What it covers
Architecture Module split, sequencer state machine, IRQ model, sysfs interface, recovery
Protocol HID-over-SPI V0: discovery, message types, feature exchange, timing
Wire Protocol Byte-level framing: headers, bodies, opcodes, PIO continuations
Report Descriptor The 936-byte descriptor: collections, reports, PIO read invariant
Touch Pipeline Raw multi-touch chain: baseline, peaks, CCL, Hungarian, slots
Config Table Pipeline constants and their Linux mapping
Hardware Both panels, AMD FCH SPI registers, wiring, ACPI power
Standard Touch Mode Default mode: report formats 0x40/0x01, why it is stable
Multi-touch (Beta) Raw mode: activation, per-device geometry, operational safety
Build & Install Installer, DKMS, Secure Boot/MOK, module parameters, build from source
Usage & Troubleshooting Day-to-day usage, debugging, recovery, common issues
Reverse Engineering Methodology, evidence, known gaps
Further Reading Repository docs: reference material, supports, tests

Repository documentation

The repo's docs/ directory holds the evidence-grade material this wiki is built on: protocol and register references, hardware validation procedures and the deeper design notes. See Further Reading for the map.

License and status

GPL-2.0, beta software. This is a beta, reverse-engineered driver — use at your own risk. The standard mode is the qualified profile; raw mode is beta.

Home

Clone this wiki locally