SouveraineOS/saf/device/touch.md

PAF · Touch — ST FTS, reset polarity, GPI-DMA, tap-to-wake

Current glass result — 2026-07-11

On kernel 7.1.1-sdm845-g56b0a053bef8, daytime touch works and the FTS recognizes DBLTAP. The current defect is downstream of gesture recognition: the first double tap can prepare the panel and then immediately unprepare it (green flash then black); a second double tap wakes the display. The first half-wake is kernel-trace confirmed. Treat DT2W as detected but unreliable until the screen-toggle/DPMS prepare-unprepare ping-pong is fixed. This is not the old IRQ/FIFO bug.

Status 2026-07-10 (morning): TAP-TO-WAKE WORKS, verified on glass by Casey on kernel d7a8f7dc9. FTS probes clean, gesture mask armed at boot, double-tap wakes from armed sleep, touch alive after wake, hypridle 60s idle screen-off enabled. The one remaining suspend-path defect was the IRQ handler, not the controller — see the closed item below.

Suspend-path doctrine (2026-07-10, learned the hard way)

• gesture_enabled MUST be 1 before any DPMS-off. Unarmed suspend takes the SLPI-handoff branch (fts_suspend_work): controller handed to the PARKED sensor island + IRQ disabled → resume races → level IRQ storm (millions on IRQ 148) → kernel kills the IRQ → touch dead until driver rebind or reboot. With SLPI's sar.cc wall unfixed, the handoff target is unavailable — gesture-armed suspend (AP keeps the bus) is the only safe mode.
• The compiled gesture_mask sysfs is the STASH-THEN-APPLY variant: echo "01 20" > stages only; the following cat applies (updateGestureMask) and sets gesture_enabled=1. blueline-dt2w.sh does both since de4fe40.
• Live recovery from a dead touch IRQ, no reboot: echo 2-0049 > /sys/bus/i2c/drivers/fts/unbind && echo 2-0049 > .../bind — but Hyprland then holds stale input handles (taps flow at evdev level, UI ignores them); a session restart or reboot is needed after rebind.
• VERIFIED 2026-07-10 (clean boot-time arm, Casey on glass): daytime touch works, and touch SURVIVES a full sleep/wake cycle — the regression is closed. Wake was power-button; double-tap did NOT wake.
• CLOSED 2026-07-10 (kernel d7a8f7dc9) — tap-to-wake works on glass. The "controller never enters gesture scan" theory was WRONG: enterGestureMode runs and succeeds at every armed suspend (Sense OFF → gesture mode → enableGesture DONE in dmesg). The real defect was fts_interrupt_handler: during armed sleep bus_refmask==0, so the bus-ref gate refused every IRQ and returned WITHOUT reading the FIFO. Level IRQ line stayed asserted → refired forever (the "582k IRQs" were the unserviced line, not full-rate scanning), gesture events were dropped unread (why double-tap never woke), and a bogus release call in the refusal branch logged one pr_err per IRQ — 85k lines in one screen-off window, enough printk to freeze the phone on long sleeps (2026-07-10 morning freezes). Fix: service the FIFO without taking a bus ref when gesture_enabled && sensor_sleep (taking one would queue a resume per IRQ), drop the bogus release, ratelimit the bus-ref pr_err. The port's 30177cb7e (AP keeps bus in gesture mode) had changed the ownership model without teaching the IRQ path — classic lost-handler.

The hardware truth (settled — do not re-litigate)

• This unit is the LG panel + ST FTS variant: FTS controller at 0x49 on i2c-2 (888000 geni SE). Settled from per-unit persist calibration + LOS init.blueline.rc.
• The Samsung sec_ts@48 nodes in the downstream DTBO (fragment@81, sec,reset_gpio, …) belong to the OTHER hardware variant. Never cite fragment@81 as evidence for our touch config — that mistake shipped ba0620d5c and killed touch for a day.
• Pins: reset tlmm 99 (active-low RESETB), IRQ tlmm 125 (level low), AP↔SLPI bus switch tlmm 136.

Reset polarity — the post-mortem

The ported vendor driver (drivers/input/touchscreen/stm/) uses gpiod logical assert semantics: acquires reset GPIOD_OUT_HIGH ("asserted"), pulse is set(1) → 20ms → set(0) → 50ms, and its own comment says "active-low reset" (fts.c ~4320). Therefore the DT flag must be GPIO_ACTIVE_LOW, so logical assert = physical LOW.

With GPIO_ACTIVE_HIGH (ba0620d5c, 2026-07-09 14:02) deassert drives the pin physically LOW → RESETB held forever → controller NACKs every I2C access → probe fails after 3 reset attempts. Signature in dmesg: gpi ... Error in Transaction: code=0x10 status=0x40 on EVERY read (including the first 8-byte poll), fts_system_reset: ERROR 80000002, Probe Failed!. Nobody noticed for a day because every boot in that window had a black display. f3c5f5a11 reverts to ACTIVE_LOW.

Triage rule: all-reads-fail = controller not out of reset / not powered / bus switch wrong — a dead chip, not a DMA problem. Large-read-only failure = the (historic) GPI-DMA wall below.

GPI-DMA wall (historic — status needs one clean-boot check)

The 888000 SE is GPI-mode-only (its SE firmware has FIFO disabled — no FIFO fallback exists; verified in i2c-qcom-geni probe). Historically small reads worked and the first large read (209-byte readSysInfo) died with MSM_GPI_TCE_UNEXP_ERR. Instrumentation ff6e6e2e8 logs completion status + error-log register on any recurrence. ANSWERED 2026-07-10, first clean f3c5f5a11 boot: the wall is GONE. Zero gpi ... Error in Transaction lines in dmesg; the driver read the 105,140-byte firmware file and ran CX/Panel CRC verification over the bus (Fw Update Finished! error = 00000000), FTS input device registered. Large GPI-DMA transfers on the 888000 SE work. Whatever ate the 209-byte read in the 2026-07-08 era was fixed by the intervening driver/power work or was reset-state fallout all along; if it ever recurs, the ff6e6e2e8 telemetry will say why. Deep diagnosis archive: ../CLAUDE.md "Touch / FTS-on-mainline key facts".

Gesture / suspend design (in-tree, working as of 07-09 morning)

• 08687bec9 power+reset sequencing, e31aa9da7 prototype fix, 30177cb7e keep AP bus ownership during gesture mode, 3d9eb1028 sensor_sleep bookkeeping in gesture-mode suspend.
• Gesture mode: on suspend the driver keeps the controller alive for double-tap; XF86WakeUp → Hyprland bind → blueline-screen-toggle (see display.md). dt2w service wiring: blueline-dt2w.service in rootfs-overlay (uncommitted edits pending as of 2026-07-10).
• Proximity gate (2026-07-20): blueline-screen-toggle checks net.hadess.SensorProxy ProximityNear over D-Bus before dispatching DPMS on; if blocked (phone in pocket) the wake is suppressed and logged, the FTS gesture still fires XF86WakeUp either way. Fails open if the D-Bus query errors, so a dead sensor proxy never permanently blocks wake. Requires iio-sensor-proxy running, which is now always-on (see slpi.md). This closes half the "hot pocket" problem; the other half (screen already on + locked, phone pocketed) is blueline-proximity-lock (overlays/systemd-user/), a monitor-sensor --proximity watcher that blanks via the same blueline-screen-toggle off path when locked.

THE GOAL (unchanged): one FTS driver = daytime touch + tap-to-wake

Like LOS: FTS drives the controller when awake; on suspend it hands the controller to the SLPI over the tlmm 136 switch, where the sns_touch_gesture nanoapp (SLPI's own i2c bus 5) watches for double-tap and wakes the AP. stmfts (mainline driver) can never do this — no switch, no handoff; it is fallback-only. Two tracks converge:

1. FTS daytime path — WORKING modulo the polarity fix verify.
2. SLPI-side tap-to-wake — unblocked by the sar.cc fix (see slpi.md), but not required for the current AP-side gesture design.