punktfunk/design/gamepad-driver-health.md

Windows gamepad-driver health: failure modes and how each is surfaced

Written for the "host doesn't see the client's gamepad" class of bug report (2026-07-02). The Windows virtual pads have many silent ways to fail: the stack spans the host process, a named shared-memory section, a PnP software devnode, a UMDF driver in its own WUDFHost.exe, and finally the game's input API (XInput / HID / SDL). Before this work the host logged only its own create calls — a pad could "exist" with no driver installed and nothing was ever logged. This document enumerates the failure modes and states, for each, how it is now detected and what the log line says. All host lines land in stderr / %ProgramData%\punktfunk\logs\host.log (service) and the in-memory ring served at GET /api/v1/logs → the web console Logs page.

The health signals

The gamepad drivers have no IOCTL plane (hidclass gates the device stack), so the only cross-process channel is the shared section itself. Two fields were carved out of reserved space (layout-compatible; old drivers simply never write them, pf-driver-proto pins the offsets):

field	XusbShm	PadShm	writer	meaning
driver_proto	@32	@144	driver	GAMEPAD_PROTO_VERSION once attached; 0 = no driver on this section
driver_heartbeat	@36	@148	driver	XUSB: +1 per serviced XInput IOCTL (game-visible path). DS/DS4: +1 per ~8 ms timer tick (liveness)

Host side, every pad owns a DriverAttach watcher (inject/windows/gamepad_raii.rs), fed from the existing service() poll. State machine, each transition logs exactly once:

• driver_proto != 0 → INFO gamepad driver attached to the shared section (with late=true if it came after the warning); WARN on a proto/host version mismatch.
• 3 s of silence → one diagnosis WARN combining: driver-store check (pnputil /enum-drivers, cached once per process, only run on the failure path), devnode PnP status (CM_Locate_DevNodeW
  • CM_Get_DevNode_Status on the instance id captured from the SwDeviceCreate callback, with a plain-language hint per CM problem code), and the driver's own debug log path.

Failure modes

#	failure	cause examples	detection	surfaced as
1	Driver package not installed	fresh box, installer's driver install --gamepad skipped/failed, package pruned	attach timeout → pnputil /enum-drivers misses pf_xusb.inf/pf_dualsense.inf	WARN driver package NOT in the driver store — run: punktfunk-host.exe driver install --gamepad
2	Package present but binding failed	certificate not in Root/TrustedPublisher, Memory Integrity (HVCI) rejects it, stale DriverVer kept the old binary	attach timeout → devnode problem code (28 = drivers not installed, 52 = signature rejected, 31/39 = load failure)	WARN with the CM problem code + hint
3	Driver bound but crashed / never started	WUDFHost crash, WdfDeviceCreate/queue failure inside the driver	attach timeout → devnode status shows driver_loaded/started flags; the driver's own log (C:\Users\Public\pf*-driver.log) has the failing WDF call	WARN referencing both
4	SwDeviceCreate fails outright	not Administrator/SYSTEM, PnP wedged, _ in enumerator (E_INVALIDARG)	existing error path (unchanged)	WARN SwDeviceCreate failed; … devnode unavailable, pad continues on the out-of-band fallback
5	SwDeviceCreate callback never fires	PnP service hung	was silently mis-read as success (zero-init HRESULT(0) + ignored WaitForSingleObject return). Fixed: result inits to E_FAIL, the wait result is checked	ERROR enumeration callback never fired (10s) — PnP may be wedged
6	Driver attached, then WUDFHost died mid-session	crash, killed	driver_heartbeat freezes (DS/DS4: timer-driven, so a freeze is conclusive; XUSB: only advances while a game polls, so absence is not an error)	field exists for a future stall check; not auto-warned yet (XUSB semantics make a generic rule false-positive-prone)
7	Version skew host↔driver	new host + old installed driver (or vice versa)	driver_proto ≠ host's GAMEPAD_PROTO_VERSION; pre-health drivers read as never-attached	WARN driver/host protocol mismatch — update the drivers (mismatch) / the mode-1 diagnosis text notes the pre-health case
8	Whole backend latched off	first pad creation failed → broken latch disables pads for the session	existing behaviour, now with remedy text	ERROR …controller input disabled until the next client connect (install/repair: punktfunk-host.exe driver install --gamepad)
9	Section created but game can't see the pad	XInput slot ordering, HidHide-style HID filters on the game process, RPCS3 pad-handler config, GameInput's instance-path VID/PID parse	not host-detectable — outside our process and the driver's stack. XUSB driver_heartbeat advancing proves "some XInput client polls us", which brackets the problem to the game's side	diagnosis text points at the driver log; the client-side controller view (Android "Connected controllers") covers the other end of the chain

What deliberately did NOT change

• The broken latch stays one-way per session (retry loops against a missing driver would spam PnP); the log line now says so and gives the remedy.
• No mgmt-API health endpoint yet — the log ring is the surfacing channel. If the web console ever grows a "gamepad health" card, DriverAttach is the state to expose.
• The DS/DS4 heartbeat is not yet watched for mid-session stalls (mode 6): worth adding once the XUSB/DS semantics split is encoded (DS freeze = conclusive, XUSB freeze = normal when no game polls).

Validation status

• Linux-side: workspace build/tests/clippy green; pf-driver-proto layout asserts pin the new offsets (compile-time).
• Windows host code + both drivers: compile-checked in CI only (this box cannot cross-build the native deps); not yet on-box validated. On-box test recipe: stop the service, pnputil /delete-driver the gamepad package, connect a client with a pad → expect the mode-1 WARN in the console Logs page within ~3 s of the pad arriving; reinstall drivers → expect the attached (late=true) INFO on the next session.