Linux gamepad via udev: add a STATE API to gamepad_source/linux.zig (so Linux desktop needn't link SDL)

[apotema]

Summary

Give src/gamepad_source/linux.zig a full gamepad STATE surface (buttons/axes/pump), so Linux desktop gamepad can run on the existing evdev/udev source with no SDL dependency — the intended end-state from the core#28 slice-5 decision (SDL opt-out by default on desktop; Linux uses udev). Today this is deferred because it can't be runtime-verified without bare-metal Linux hardware and would replace the working SDL Linux path.

Tracked locally as a deferred follow-up of core#28; filing it so it survives as a real issue.

Current state

• gamepad_source/linux.zig is detection-only: it opens each /dev/input/event* node just long enough to read identity (EVIOCGID/EVIOCGNAME) then closes the fd. It implements init/deinit/pollEvents/describe but no update/isAvailable/isButtonDown/isButtonPressed/axisValue (the gamepad_source state contract treats those as optional, so it compiles — but Linux can't serve gamepad STATE).
• After core#28, the raylib/sokol desktop backends route gamepad through the shared SDL backends/sdl_gamepad source on all desktop OSes incl. Linux.
• The SDL source is now CI-runtime-verified on Linux (assembler#279, 23/23 via an in-process SDL virtual gamecontroller) — but only the SDL joystick subsystem; it does not exercise the kernel device path.

Scope

1. core — gamepad_source/linux.zig: add the state surface mirroring backends/sdl_gamepad's Source exactly (canonical raylib-compatible numbering, sticks [-1,1], triggers [0,1], synthesized left/right_trigger_2 at the trigger threshold, per-slot prev/cur edge snapshot):
   • keep the event* fd open per tracked slot (close on disconnect/deinit),
   • update(): per frame, snapshot current state via EVIOCGKEY (button bitmap) + EVIOCGABS(axis) ioctls (recommended for parity with the SDL snapshot-and-edge model) or drain the evdev event stream,
   • isAvailable/isButtonDown/isButtonPressed/axisValue,
   • the KEY_*/ABS_* → canonical button/axis mapping + axis normalization from each axis's input_absinfo{min,max,flat} (read once at connect),
   • matching no-op state methods on the non-Linux FallbackSource so the file still cross-compiles everywhere.
2. assembler — backend Impl routing: on a Linux desktop target, route raylib/sokol gamepad to core.gamepad_source (udev) instead of sdl_gamepad, and don't link SDL2 there. (This is the per-OS 3-way selection sketched in the core#28 slice-5 plan.)

Acceptance (needs bare-metal Linux + a real pad)

The SDL virtual-device harness can't cover these — they're the kernel-path criteria (overlaps assembler#249):

• connect/disconnect hotplug via evdev/udev with a physically (re)plugged controller,
• /dev/input/* permission handling + a clean unavailable_reason when denied,
• GUID/identity stability across replug,
• buttons/axes/edges read correctly for at least one real pad (Xbox + one other).

Why deferred

No bare-metal Linux hardware available to runtime-verify, and shipping an unverified evdev state path would replace the working, now-CI-verified SDL Linux path — a regression risk with nothing to catch it. Pick up when Linux hardware (or a Linux runtime-CI job with a real/virtual evdev device) is available.

Related

• core#28 — gamepad epic; this is its deferred Linux follow-up.
• assembler#249 — Linux evdev/udev + wasm detection sources (Phase 1); carries the wasm + permissions-UX scope and the kernel-path acceptance criteria.
• assembler#279 — hardware-free SDL gamepad CI harness (verifies the SDL Linux path, not the kernel path).

[apotema]

The "needs bare-metal Linux" blocker is softer than stated — uinput can stand in for hardware for most of the acceptance list.

Verified on a stock WSL2 kernel (6.18, Ubuntu 26.04): CONFIG_INPUT_UINPUT=m, CONFIG_INPUT_EVDEV=m, CONFIG_INPUT_JOYDEV=m all present, and modprobe uinput exposes /dev/uinput. A synthetic gamepad created through uinput is a real kernel input device: it appears as /dev/input/event*, answers EVIOCGID/EVIOCGNAME with whatever vendor/product/name the feeder declares, serves EVIOCGKEY/EVIOCGABS state, carries genuine input_absinfo ranges for normalization, and fires real hotplug events on create/destroy. That is exactly the surface this issue's scope targets — the kernel-layer analogue of the SDL virtual-gamecontroller harness from assembler#279.

Consequences for the acceptance criteria:

• Coverable with uinput (WSL or plausibly a ubuntu-latest CI job): enumeration, connect/disconnect hotplug, state reads (buttons/axes/edges), axis normalization from absinfo, and replug identity stability (recreate the device with the same ids).
• Still hardware-bound: real-pad quirks (Xbox GIP vs plain HID report layouts), and the /dev/input permission + udev-rule UX in a real desktop session (partially simulable via chmod, but the real-world diagnostic flow deserves a hands-on check).

So the work can start now: implement the state surface, verify it against a uinput feeder, and keep the SDL source as the routed default until the bare-metal items are checked off. Starting with the detection-only code that exists today: a uinput device gives pollEvents/describe their first runtime verification too.

[apotema]

Scope item 1 is merged: #34 implements the full state surface (update / isAvailable / isButtonDown / isButtonPressed / axisValue) with sdl_gamepad parity — canonical numbering, absinfo-normalized axes, trigger synthesis, hat d-pads, dense lowest-free slot reuse, hotplug pump throttled to ~1/s inside update(), no threads. Measured cost with two pads connected: avg 11us / max 36us per update() (~0.07% of a 60fps frame). #35 turns the uinput harness into a CI regression gate (the 'Gamepad runtime check' job, green on ubuntu-latest hosted runners). Remaining here: scope item 2 (assembler routing: point raylib/sokol Linux desktop at this source, drop the SDL2 link there) and the bare-metal checklist (real-pad label quirks, /dev/input permission UX).

[apotema]

Scope item 2 is merged: assembler#282 routes raylib/sokol desktop Linux gamepad to this source (core pinned at v1.16.1, which includes the #37 hardening) and links no SDL2 there — ldd on Linux-built backend binaries shows zero SDL and zero libudev (dlopen'd at runtime). Windows/macOS keep the SDL route; Android/iOS/wasm untouched. Shipping in assembler v0.39.0.

Also relevant from today: the Windows real-pad smoke test happened (physical HID pad, connected before launch, drove a full raylib game session) — so the analogous bare-metal item left here is Linux-specific only:

• real pad on bare-metal Linux: label quirks (xpad NORTH/WEST), /dev/input permission UX + udev rule flow, replug GUID with physical hardware

Everything else in this issue's scope is implemented, CI-gated (uinput runtime job), and routed.