SL4A TouchScreen

Public research dataset: 8,232 privacy-hardened SL4 AMD pinch heatmaps (72×48 rasters, relative timestamps, anonymized Windows contact markers). Includes research limitations; not the private Windows ETL or full vendor payloads.

Research evidence start here (2026-10-17): recovered historical Windows Ghidra source (468 functions) · canonical SL4A Windows evidence index · original source manifest · 24 contradictions and open gaps. These documents supersede unqualified Windows-fidelity claims in historical pipeline notes. Full 1,422-frame July CapImg corpus has already been replayed in PR #12; processed Windows contact IDs have not been verified.\n\nLinux touchscreen driver for the Microsoft Surface Laptop 4 AMD and Surface Laptop 3 AMD, built around the AMD AMDI0060 SPI controller and Microsoft MSHW0231 / MSHW0162 HID-over-SPI devices.

Warning

Beta, reverse-engineered kernel driver. Gate5 is field-qualified on one Surface Laptop 4 AMD unit, not a broad hardware/firmware/kernel compatibility guarantee. Keep recovery access available when installing or testing.

Important

Surface Laptop 4 AMD testers wanted. If you have an SL4 AMD, especially MSHW0231 + AMDI0060, independent cold-boot, suspend/resume and multitouch results are extremely useful right now. Start with the read-only ./tools/sl4a-touch.sh install --check preflight. See Testers Wanted, join the Hardware Testing Hub, or submit a structured hardware report.

What This Driver Does

On Surface Laptop 4 AMD / MSHW0231, the standard install path now combines normal HID-over-SPI discovery with the panel's high-resolution CapImg stream:

ACPI _PS0 -> _RST
        |
RESET_RSP
        |
DEVICE_DESC
        |
936-byte HID report descriptor
        |
register normal HID device
        |
write GET_FEATURE report 6
        |
do not synchronously read the GET6 body
        |
wait ~4.5-5.5 ms
        |
SET_FEATURE report 5 = 1
        |
0x0c CapImg / heatmap frames
        |
in-kernel CapImg multitouch tracker (input-quality beta)
        |
MSHW0231 Touchscreen Linux MT input

Production SL4 multitouch uses the standard HID transport. The driver discovers and registers the real HID device first, then transitions the panel into the CapImg stream and publishes multitouch from that stream. The legacy raw-transport profile is not part of the production multitouch path.

The standard SL4 profile therefore keeps:

• normal HID descriptor discovery and HID registration;
• the real 936-byte report descriptor read from the panel;
• the standard HID device, including the descriptor-created stylus interface;
• the high-resolution CapImg stream for touch;
• the in-kernel CapImg multitouch tracker exposed as MSHW0231 Touchscreen (input-quality beta).

The stylus HID node is created, but pen behavior is not yet qualified.

What This Fork Adds

This fork builds on the original Syax89/SL4A_TouchScreen foundation: AMD FCH SPI support, HID-over-SPI transport work, CapImg acquisition, and the original heatmap decoding/tracking work.

The current SL4 path adds the pieces needed to make those parts behave as one repeatable driver lifecycle:

Area	Current behavior
SL4 startup	Normal HID discovery followed by the Gate5 GET6-write → ~5 ms → SET5 transition
Multitouch	CapImg frames are processed by the in-kernel CapImg tracker (input-quality beta) while the normal HID transport remains registered
Early-frame race	Once a DATA header is consumed, its body is drained even if HID registration is still in progress
Warm reloads	The HID-registration DATA-drain race that could leave a ~4.3 KB frame queued was fixed
Suspend	Explicit _PS3 panel power-down
Resume	Explicit _PS0 -> _RST, descriptor rediscovery, then the qualified Gate5 transition again
Installer	Device-aware: MSHW0231 receives the Gate5 SL4 profile; MSHW0162 keeps the conservative standard profile
DKMS / boot	Installs through DKMS and enables a post-multi-user.target systemd activation service
Diagnostics	status, logs, protocol counters, installed-build stamping, and profile verification are built into the tool

Current Qualification

The Gate5 production path has been exercised on one physical Surface Laptop 4 AMD / MSHW0231 unit.

Test	Result
True cold power-on + touch	PASS
Warm module reload + touch	3/3 PASS
s2idle suspend/resume + touch	2/2 PASS
Production DKMS install/profile generation	PASS
Secure Boot with existing enrolled Ubuntu DKMS MOK	PASS
Secure Boot reboot + automatic systemd activation	PASS
Installed profile vs running parameters	MATCH
Unexpected post-DONE controller resets in qualification captures	0
Observed transport frame drops in qualification captures	0

The broader E1 input-quality campaign is still in progress. Close-contact tracking, crossing-finger identity, 3-5 finger behavior, palm rejection, stylus correctness, mixed pen/touch input, long-duration stress, and broader hardware/kernel coverage are not yet release claims.

See docs/GATE5-QUALIFICATION.md for the qualified activation/lifecycle evidence and docs/COMPATIBILITY.md for the evidence matrix.

Supported Hardware

Device	ACPI IDs	Standard installer behavior	Status
Surface Laptop 4 AMD	touch MSHW0231, SPI AMDI0060	Gate5 standard-transport CapImg multitouch	Field-qualified on one unit
Surface Laptop 3 AMD	touch MSHW0162, SPI AMDI0060	Conservative standard HID	Gate5 sequence not claimed

The tested SL4 HID identity is Microsoft VID/PID 045e:0c19. The SL4 heatmap geometry is 72×48 cells; SL3 uses its own device-specific geometry selected by ACPI ID.

Other Surface models, other MSHW* touch devices, and other AMD SPI controller IDs are not supported by this release.

Install

Read docs/SUPPORT.md first.

git clone https://github.com/avgbob/SL4A_TouchScreen.git
cd SL4A_TouchScreen

# Read-only hardware/build preflight
./tools/sl4a-touch.sh install --check

# Install the device-aware standard profile
sudo ./tools/sl4a-touch.sh install

The installer:

1. checks the supported ACPI hardware;
2. stages and builds the two modules through DKMS;
3. writes the device-appropriate /etc/modprobe.d/sl4a-spi-hid.conf;
4. enables sl4a-touch-activate.service;
5. activates the driver immediately when safe to do so;
6. verifies the driver is actually bound.

The boot service starts after multi-user.target, not during early kernel boot. This keeps the out-of-tree modules out of the fragile early-boot auto-binding path and leaves a working userspace recovery environment if activation fails.

Secure Boot signing

Secure Boot handling is built into the installer. When Secure Boot is enabled, the installer first resolves the actual signing identity DKMS is configured to use, including /etc/dkms/framework.conf and /etc/dkms/framework.conf.d/*.conf overrides. Ubuntu's packaged DKMS normally uses /var/lib/shim-signed/mok/MOK.priv + MOK.der; upstream/Debian DKMS normally uses /var/lib/dkms/mok.key + mok.pub. The installer validates that resolved private key and certificate as a matching pair, normalizes a PEM certificate to DER when needed, and checks that same certificate's MOK enrollment status.

If a valid pair already exists, the default is to reuse it for the newly rebuilt DKMS modules. Interactive installs also offer to generate a new pair or import another existing pair. Use --rotate-mok for an explicit scripted key rotation. The DKMS signing identity is system-wide, so rotating it can affect other DKMS-managed modules as well. Before replacement, existing MOK material is preserved under a root-only /var/lib/dkms/sl4a-mok-backup-* directory. After DKMS installs the driver on a Secure Boot system, the installer also checks both installed modules with modinfo -F signer and refuses to continue if either module is unsigned.

If only one half of the pair exists, the material is invalid, or the private key and certificate do not match, the installer will not treat it as usable. Interactive installs offer repair choices; non-interactive installs stop unless rotation was explicitly requested. A newly generated or imported certificate that is not already enrolled is staged through mokutil, and driver activation is deferred until the MOK Manager reboot completes.

The Secure Boot installer path is hardware-qualified on one MSHW0231 Surface Laptop 4 AMD unit with Ubuntu kernel 7.0.0-31-generic (2026-09-26). Qualification covered reuse of the active Ubuntu shim-signed MOK identity, DKMS rebuild/signing of both modules, post-install signer verification, reboot with Secure Boot still enabled, and successful automatic Gate5 activation. The qualification checkpoint is e2be025fd8af8720db80f0f59cd2b48969aee777. This remains a single-unit result, not a broad firmware/kernel compatibility claim. The separate fresh-enrollment path (generate/import a new certificate, complete firmware MOK Manager enrollment, then reboot) remains implemented but has not yet been independently hardware-qualified.

Status and logs

./tools/sl4a-touch.sh status
sudo ./tools/sl4a-touch.sh logs

status reports the DKMS version, the commit the installed modules were built from, configured and running profiles, hardware presence, module state, and boot activation state.

Manual activation

sudo ./tools/sl4a-touch.sh activate

The activation command refuses to displace another driver already bound to the target controller/touchscreen.

Recovery

sudo modprobe -r sl4a-spi-hid sl4a-spi-amd
sudo reboot

See docs/ROLLBACK.md for the complete rollback and upgrade procedure.

Production SL4 Profile

For MSHW0231, the standard installer selects the qualified Gate5 profile automatically. This is a standard-HID-transport profile that adds the CapImg multitouch bridge after normal HID discovery. It is not the legacy raw transport.

The low-level module parameters are documented in docs/PARAMETERS.md and docs/GATE5-QUALIFICATION.md. They retain some historical names from development, but those names do not change the production architecture described above.

For MSHW0162, the installer keeps the conservative standard-HID path.

The explicit --raw installer option is retained only as a legacy diagnostic/research transport. It is not required for SL4 multitouch and is not the production multitouch path.

Why the Gate5 Sequence Matters

During qualification, several similar-looking activation sequences behaved differently:

• SET5-only can enter CapImg and remains useful historical evidence.
• GET6 write → ~5 ms → SET5 repeatedly entered CapImg.
• Full synchronous GET6 read → SET5 caused a controller reset on the tested machine.
• A separate warm-reload reset was traced to the first CapImg DATA body being left queued while hid_add_device() was still running.

Gate5 fixes the second problem independently of activation timing: after the driver consumes a DATA header, it drains/processes the corresponding body even while HID registration is still active. Publication into the HID core remains suppressed until registration is ready.

That transport-synchronization fix is what made repeated warm activation reliable on the qualified machine.

Power Lifecycle

The SL4 production lifecycle is:

BOOT / LOAD
  _PS0 -> _RST
  -> descriptors
  -> GET6 write
  -> ~5 ms
  -> SET5
  -> CapImg

SUSPEND
  stop traffic
  -> _PS3

RESUME
  _PS0
  -> _RST
  -> rediscover descriptors
  -> GET6 write
  -> ~5 ms
  -> SET5
  -> CapImg

The tested Gate5 path survived two s2idle resume cycles with real touch after resume.

Touch Pipeline

The production SL4 path currently uses the in-kernel CapImg multitouch tracker (input-quality beta).

At a high level:

0x0c CapImg
   |
72x48 signal grid
   |
baseline / noise filtering
   |
peak detection + connected components
   |
blob splitting
   |
candidate-to-track assignment
   |
post-association ghost suppression
   |
smoothing / deadband / lift handling
   |
Linux multitouch slots

A key tracker change is the ordering of close-contact suppression: candidates are associated to existing tracks first, then the strict proximity/ghost rule is applied. That allows two nearby candidates backed by two established tracks to remain separate instead of being pre-merged simply because they are close.

Detailed processing, thresholds, and tracker behavior live in docs/PIPELINE.md.

The repository also contains the experimental userspace/sl4a-heat/ path. That remains architecture research; it is not the current installed Gate5 production path.

Known Limits

This release does not yet claim:

• Gate5 mode-1 activation on Surface Laptop 3 AMD / MSHW0162;
• validated stylus/pen behavior;
• palm rejection;
• complete 1-5 finger qualification;
• Windows-equivalent contact classification;
• long mixed-input stress;
• broad firmware, kernel, or distribution compatibility;
• support for other Surface models or other AMD SPI controller IDs.

Development / Build from Source

For development without DKMS:

make -C /lib/modules/$(uname -r)/build M=$PWD/driver modules
sudo cp driver/sl4a-spi-amd.ko driver/sl4a-spi-hid.ko /lib/modules/$(uname -r)/updates/dkms/
sudo depmod -a
sudo ./tools/sl4a-touch.sh activate

Modules built manually this way are unsigned unless you sign them yourself.

Documentation

Document	Purpose
docs/QUICKSTART.md	Short installation guide
docs/GATE5-QUALIFICATION.md	Current SL4 Gate5 activation and lifecycle contract
docs/SUPPORT.md	Supported hardware and installer profiles
docs/COMPATIBILITY.md	Evidence / compatibility matrix
docs/ACTIVATION.md	GET6 / SET5 activation experiments and current Gate5 sequence
docs/HIDSPI_PROTOCOL.md	HID-over-SPI V0 transport
docs/PIPELINE.md	Heatmap and multitouch pipeline
docs/PARAMETERS.md	Release, diagnostic, and experimental parameters
docs/TESTING.md	Reproducible test procedure
docs/EVIDENCE.md	Evidence ledger and unresolved questions
docs/ROLLBACK.md	Recovery and rollback
docs/HARDWARE_VALIDATION.md	Hardware-validation procedure
docs/AMDI0060_CONTRACT.md	AMD SPI controller boundary
userspace/sl4a-heat/README.md	Experimental userspace heat-processing work

Historical Gate3/Gate4/mode-3 documents are intentionally retained. They record how the final Gate5 sequence was discovered rather than being rewritten to look like the final result was known from the beginning.

License

GPL-2.0. See LICENSE.