Building Usage and Troubleshooting

Building, Usage and Troubleshooting

Installing (beta testers)

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

This is the recommended path if you just want to try the driver. It builds the modules via DKMS — so they get automatically rebuilt for every kernel you install afterward, instead of silently going stale on the next kernel update like a plain out-of-tree build would — and installs a systemd service that loads the driver in the stable configuration (raw_mode=0) on every boot. It checks for the MSHW0231 ACPI device and for build dependencies first (dkms, make, kernel headers, plus clang or gcc — whichever your running kernel was itself built with), and is safe to re-run.

Remove everything it installed with:

sudo ./tools/uninstall.sh

This is beta software — see the Home page's status table. It taints the kernel (unsigned out-of-tree module); if your system enforces Secure Boot strictly, you may need to enroll DKMS's MOK key (see your distro's DKMS Secure Boot docs).

After installing, the touchscreen appears as:

• /dev/input/eventN — spi 045E:0C19 (ABS_X, ABS_Y, BTN_TOUCH) for touch
• /dev/input/eventN — spi 045E:0C19 Stylus for the pen

Check with dmesg | grep -E "SEQ|spi-hid|hid-generic" — a successful load ends with a line like hid-generic ...: input,hidraw3: SPI HID v1.00 Device [spi 045E:0C19] on spi-MSHW0231:00.

Building from source (developers)

If you're working on the driver code itself, building/reloading directly from the working tree (bypassing DKMS entirely) is much faster to iterate on:

make LLVM=1 -C /lib/modules/$(uname -r)/build M=$PWD/driver modules
sudo rmmod spi_hid spi_amd 2>/dev/null
sudo insmod driver/spi-amd.ko
sudo insmod driver/spi-hid.ko

LLVM=1 is needed only when your running kernel was itself built with clang (true for CachyOS's own kernels) — its Makefile.build emits clang-only compiler flags in that case, and a plain gcc build fails. On a kernel built with gcc (e.g. vanilla Arch's linux package), drop LLVM=1 entirely — passing it forces clang against gcc-only flags and fails the other way. Check with grep CONFIG_CC_IS_CLANG /lib/modules/$(uname -r)/build/.config. The DKMS config (driver/dkms.conf, used by the beta installer above) detects this automatically per kernel — this manual command doesn't, since it always builds for whatever kernel is currently running.

driver/sl4a-touch.service (a systemd unit that insmods straight from the checkout, absolute path, no DKMS) plus tools/rebuild_and_install.sh (rebuild + reload in one step) automate this loop — install the service once:

sudo cp driver/sl4a-touch.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sl4a-touch.service

then after every code change:

./tools/rebuild_and_install.sh

Pass extra arguments to do a one-off manual load with module parameters instead (e.g. to try raw_mode=1) — this bypasses the systemd service for that single run only; the service itself always loads with no parameters:

./tools/rebuild_and_install.sh raw_mode=1 debug_coords=1

⚠️ The beta installer (tools/install.sh) and this developer loop both install a systemd unit with the same name (sl4a-touch.service), but they are different files — installing one overwrites the other. Pick one workflow per machine.

Module parameters (spi-hid.ko)

Parameter	Default	Meaning
raw_mode	0 (off)	1 = experimental raw heatmap multi-touch mode. See Multi-touch Experimental
debug_coords	0 (off)	Log blob grid coordinates/weights (raw_mode=1 only)
invert_x, invert_y, swap_xy	0 (off)	Axis calibration knobs for the blob detector
setfeat_speed_hz	0 (bus default, 33.33MHz)	Override SPI clock speed for the SET_FEATURE write only — an experiment, no known effect (see Multi-touch Experimental)
setfeat_no_double	0 (off)	Send SET_FEATURE without the opcode-doubling quirk — makes things worse, kept only for future experiments

Pass at insmod time, e.g.: sudo insmod driver/spi-hid.ko raw_mode=1 debug_coords=1. Most are also runtime-writable via /sys/module/spi_hid/parameters/<name> (0644), though several (like raw_mode) only take effect on the next device bind, not retroactively.

Debugging

sudo dmesg -w | grep "SEQ\|spi-hid"

The state machine logs its own state transitions (SEQ: thread seq_state=N) and every header/type it decodes (SEQ[state=N] type=T hdr=[...]) — very verbose by design, since this device's behavior is still not fully understood (see Further Reading for the deep investigation history).

Recovery tools

• tools/reset_touch.sh — power-cycles just the touchscreen via the ACPI \M010 GPIO method, without touching the loaded modules or requiring a full reboot. Useful any time the device seems stuck (in particular, some raw_mode=1 recovery scenarios).

  sudo ./tools/reset_touch.sh

• Full reboot — the only reliable way back to standard mode once raw_mode=1 has actually switched the device into raw streaming (see Multi-touch Experimental).

Common issues

• hid-generic never binds / no input devices appear — check dmesg for SEQ: ll_parse lines; if it says "device-read report descriptor failed to parse", the driver should automatically retry with the hardcoded fallback (see Report Descriptor) — if it doesn't, that's a real bug worth reporting.
• raw_mode=1 never streams data — expected some of the time; see Multi-touch Experimental for the known reliability issue and what the built-in watchdog does about it.
• Touch stopped working after testing raw_mode=1 — reboot. See the warning at the top of Multi-touch Experimental.
• systemctl status sl4a-touch shows failed right after a kernel package update, before rebooting — expected and harmless. Once a kernel update removes the currently running kernel's headers (normal on a rolling-release distro), DKMS can no longer (re)build for that exact kernel — but it already rebuilt for the new kernel(s) the update just installed (dkms status should show them as installed), and the already-loaded modules keep working fine for the rest of this session regardless of the service's status. Reboot into the new kernel and the service starts cleanly.
• dkms install ... exited 10 for a module name split at the wrong place (e.g. sl4a-touch-1.0.0/beta1 instead of sl4a-touch/1.0.0~beta1) during a pacman -Syu kernel update — this was a real packaging bug in early v1.0.0-beta1 builds (a stray leftover /usr/src/sl4a-touch-1.0.0-beta1 directory from before a mid-beta hotfix, which Arch/CachyOS's pacman dkms hook kept re-discovering independently of dkms status). Fixed in the current installer. If you still see it: sudo ./tools/uninstall.sh then sudo ./tools/install.sh again to fully clear any stale /usr/src leftovers.