Skip to content

Building Usage and Troubleshooting

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

Building, Usage and Troubleshooting

Building

make LLVM=1 -C /lib/modules/$(uname -r)/build M=$PWD/driver modules

LLVM=1 is required — this codebase relies on clang-only build flags; a plain gcc build fails.

Loading

sudo rmmod spi_hid spi_amd 2>/dev/null
sudo insmod driver/spi-amd.ko
sudo insmod driver/spi-hid.ko

After loading successfully, 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.

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