Skip to content

Building Usage and Troubleshooting

Jump to bottom
Syax89 edited this page Jul 8, 2026 · 5 revisions

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.

Home

Clone this wiki locally