Netlink uevent hotplug monitor (mechanism + headless diagnostic)

[mariotaku]

Replaces the 3-second joystick and hidraw presence polls on webOS with kernel uevents. Both backends are wired up.

Background: https://gist.github.com/mariotaku/131ed7ba5a9bbdfc3a1dbb1261feb174 — context is moonlight-tv#614, which carries the reconnect workaround as a build-time patch. This should let that PR drop the patch file, the apply step, and the revision pin.

Problem

No libudev in the app jail, so enumeration_method falls back to ENUMERATION_POLLING. Every 3s LINUX_FallbackJoystickDetect rescans /dev/input and diffs a 32-bit presence bitmask. A controller that disconnects and reconnects on the same index between two polls leaves the bitmask unchanged, so SDL never notices.

Two things beyond the gist:

• The webOS poll branch only ever called MaybeAddDevice for present indices — never MaybeRemoveDevice. Plain disconnects weren't reported by this path either.
• There was a second, independent 3s poller in src/hidapi/SDL_hidapi.c doing its own hidraw bitmask diff. A DualShock 4 goes through HIDAPI, so fixing only the joystick side would have left half the latency in place. Both are gone now.

Using it

The monitor is self-contained — no harder than the poll it replaces:

monitor = SDL_webOSUeventMonitorOpen(SDL_WEBOS_DEVICE_PRESENCE_CHECK_EVDEV);

while (SDL_webOSUeventMonitorPoll(monitor, &event)) {
    if (event.action == SDL_WEBOS_UEVENT_ACTION_ADD) {
        MaybeAddDevice(event.devnode);
    } else {
        MaybeRemoveDevice(event.devnode);
    }
}

Open() binds the socket and only then enumerates what's already attached, queueing those as ordinary add events — so callers have one code path for existing and hotplugged devices, and the bind-before-scan ordering is handled internally rather than left to each integration to remember. Poll() filters to the requested node class, collapses events that wouldn't change what the caller believes, and returns a devnode ready for MaybeAddDevice().

Overflow recovery is internal for the same reason. Netlink is lossy: the kernel discards broadcasts under pressure and reports ENOBUFS once. An earlier revision exposed this as LostEvents(), which only worked if the caller remembered to ask — and forgetting left the device list permanently stale, silently, which is worse than the polling it replaces. The monitor now re-enumerates on ENOBUFS and reports the difference against what it last told the caller. This matters on webOS because an app can be backgrounded or suspended, and a process not draining while devices come and go is exactly how the buffer fills.

Other design points:

• Each subsystem opens its own monitor. Netlink delivers a copy to every bound socket; sharing one fd would mean whichever side drained first ate the other's events.
• DEVNAME preferred over DEVPATH, falling back to DEVPATH's trailing component since a remove on an older kernel can omit DEVNAME.
• Sender validation. Any user process can bind netlink and unicast at us, so messages not from portid 0 / not on a multicast group are dropped — a malformed path can't be injected into MaybeAddDevice.
• Node tracking is by name, so it has none of the bitmask's 32-index ceiling.

Polling stays for exactly two cases: a socket that won't open, and the re-enumeration behind overflow recovery.

	before	after
joystick	scandir + stat sweep every 3 s	non-blocking recv, usually EAGAIN
hidraw	separate 3 s bitmask diff	same monitor, own socket
latency	up to 3 s	sub-100 ms
same-index reconnect	invisible	explicit remove + add

Hardware results

Measured with testwebosuevent, running the monitor and the presence poll side by side over the same hotplug activity. webOS 4 and 3.4 ran inside a real native_devmode jail via jailer, as the app's unprivileged uid.

kernel	webOS	context	poll changes	netlink transitions	missed by netlink	poll lost	mean lead
5.4.268	10 (OLED C5)	devmode user	30	36	0	5	1722 ms
4.4.84	4 (LK5900)	jail uid 6927	14	14	0	0	2701 ms
4.4.84	4 (LK5900)	jail uid 5235	12	18	0	6	1813 ms
4.4.84	4, 2 controllers	jail uid 5235	21	21	0	0	1631 ms
3.10.19	3.4 (UH6100)	jail uid 6339	34	46	0	12	1912 ms

111 poll-detected changes across three kernel generations. Netlink missed none. The poll lost 23 transitions netlink caught.

• Kernel 3.10 works. The gist listed unprivileged bind on 3.x as expected-but-unverified, and it was the only reason the fallback was load-bearing. Verified on a UH6100 (webOS 3.4, glibc 2.19): binds and delivers inside the jail.
• The blind spot, captured live. On the C5: remove hidraw/0 at 62.575, add hidraw/0 at 62.756 — 181 ms apart, both between two polls, bitmask byte-identical across them.
• Whole connect/disconnect cycles vanish. On 3.10, a controller appeared and disappeared inside 1.77 s between two scans: netlink saw 2 transition(s), the bitmask could express 0.
• Burst load is fine. A Logitech Unifying receiver enumerating 5 tracked nodes within 21 ms, and two controllers connecting together, both with 0 dropped.
• Lead time is a distribution, not a constant — 82 ms to 3.0 s. The poll's latency is a coin flip between "fine" and "three seconds" on every event.

End to end, through SDL's own API

testwebosuevent --sdl reports SDL_JOYDEVICEADDED/REMOVED instead, which checks the backend wiring rather than the stream underneath it. On the UH6100 (kernel 3.10), inside the jail:

[  0.540] SDL joystick subsystem up, 2 joystick(s) already present
[  1.390] SDL_JOYDEVICEADDED    device index 0 (PS4 Controller)
[  1.390] SDL_JOYDEVICEADDED    device index 1 (Google Stadia Controller)
[ 48.791] SDL_JOYDEVICEREMOVED  instance id 2
[ 48.826] SDL_JOYDEVICEREMOVED  instance id 1     <- 35 ms later
[ 51.247] SDL_JOYDEVICEADDED    device index 0 (PS4 Controller)
[ 51.949] SDL_JOYDEVICEADDED    device index 1 (Google Stadia Controller)
[ 52.384] SDL_JOYDEVICEREMOVED  instance id 3     <- 435 ms later
[ 53.778] SDL_JOYDEVICEADDED    device index 1 (PS4 Controller)
[ 54.395] SDL_JOYDEVICEREMOVED  instance id 4     <- 617 ms later
[120.013] 2 joystick(s) present at exit

Five distinct transitions inside two 3-second windows, each surfaced as its own SDL event — the old code could emit at most one bitmask diff per window. The two controllers already attached at startup arrive as ordinary SDL_JOYDEVICEADDED at 1.390 s, which is the monitor's internal enumeration.

Over the run: 7 adds, 5 removes, 2 present at exit. The accounting balances exactly, so 12 transitions of aggressive hotplugging left no leaked or phantom entries in SDL's device list.

Tests

Both follow the testevdev pattern: internal sources are compiled in rather than linked (they're unexported), and SDL_internal.h comes first so the dynapi renaming applies to the public declarations as well as our own calls. On webOS builds the test targets also need __WEBOS__ — SDL_dynapi.h keys SDL_DYNAMIC_API off it, and the library gets it from sdl-build-options while tests don't, so without it the test references SDL_*_REAL while the library defines plain names and fails to link.

• test/testwebosuevent_parse (non-interactive, ctest): nine synthetic uevents — evdev add, remove without DEVNAME, hidraw, change/bind rejection, libudev-format rejection, missing ACTION, trailing-slash path, index past 31.
• test/testwebosuevent (needs hardware): headless, meant to run over SSH on a TV. Cross-checks netlink against the poll and reports NETLINK USABLE / FALLBACK REQUIRED / INCONCLUSIVE, the latter because an idle system produces no uevents whether or not the socket works. --sdl switches to reporting SDL's own device events.

Not gated on WEBOS — the mechanism is plain Linux netlink, so it runs on a desktop with a USB controller too.

On the fallback trigger

The gist suggests falling back to polling if no uevent arrives within a settle window after the initial scan. I'd argue against that specific rule: absence of events isn't evidence of breakage, since an idle TV legitimately produces none. The runs bear this out — netlink was silent for 45 s at a stretch while working perfectly. Open() failing plus ENOBUFS covers what's actually detectable.

Open question

On the C5, netlink reported hidraw/1 add and remove that the presence poll never saw in either direction, while hidraw/0 tracked correctly. Most likely that jail's /dev didn't contain the node. It didn't reproduce on the other two TVs. So netlink can report devices the jail can't open — MaybeAddDevice opens the path and fails gracefully, so this should be safe, but it's the one behaviour I'd want a second opinion on.

🤖 Generated with Claude Code