Skip to content

Fix ROCKNIX RK3326 SDL menu segfault by falling back to system SDL2 - #90

Merged
misantronic merged 3 commits into
mainfrom
rocknix/sdl-doctor
Aug 9, 2026
Merged

Fix ROCKNIX RK3326 SDL menu segfault by falling back to system SDL2#90
misantronic merged 3 commits into
mainfrom
rocknix/sdl-doctor

Conversation

@misantronic

@misantronic misantronic commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Fixes the ROCKNIX RK3326 segfault where the SDL menu crashed back to EmulationStation on launch.

Root cause

The pygame-ce wheel ships its own private libSDL2-2-<hash>.0.so.0.3200.10, but that SDL dlopens the system's libEGL.so.1, libwayland-client.so.0, libwayland-egl.so.1 and libdecor-0.so.0. That hybrid stack segfaults inside pygame.display.set_mode() on RK3326 with the libmali blob. ROCKNIX's own /usr/lib/libSDL2-2.0.so.0, which every emulator on the device already uses, works fine.

The crash is a native SIGSEGV, so no Python handler could ever catch it, and the driver-fallback loop couldn't help because driver choice was never the problem.

This also retires the earlier theory that the vendored pygame build had to be swapped. The pygame-ce swap did fix a different device (Anbernic RG DS, Mali-G52, #55) but never RK3326, because pygame was not the culprit.

Changes

tool-launcher.sh

  • Tries <driver>|<preload> combinations and caches the first survivor in rocknix_sdl_attempt. The bundled SDL is still attempted first, so devices where it already works are unaffected.
  • Tees stdout/stderr to menu-stdout.log. Previously these were discarded entirely, which is why months of logs never showed the cause — a native SDL crash leaves no Python traceback, so that output was the only record.

sdl-doctor.sh + sdl_probe.py (new)

A diagnostic installed as a second Tools entry. Runs window creation across a matrix of SDL configurations, capturing stdout, stderr, decoded exit signal and filtered dmesg per attempt, plus an environment survey. The SDL_VIDEODRIVER=dummy control probe is what identified the fault as the GPU/wayland path rather than pygame itself.

Verification

Diagnostic output from an affected device (GKD Pixel 2, HW_DEVICE="RK3326"):

Probe Result
dummy / offscreen (control) SUCCESS — pygame build is fine
wayland baseline SIGSEGV
wayland, libdecor off SIGSEGV
wayland, windowed SIGSEGV
wayland, system SDL2 preloaded SUCCESS
kmsdrm not available (sway holds DRM master)

Attempt ordering verified across all three cache states: fresh affected device recovers after one crash and caches; returning device goes straight to the working combination; devices where the bundled SDL works keep their current behavior.

Confirmed working end-to-end on-device by the reporter, so SDL_ttf and SDL_image are fine under the preload, not just base SDL.

Does not address the separate RG DS dual-screen rendering issue in #55, which remains open.

SDL Doctor is opt-in

The diagnostic scripts always ship in the bundle, but the Tools entry is only created when the toggle at the top of the generated installer is flipped:

INSTALL_SDL_DOCTOR="${INSTALL_SDL_DOCTOR:-false}"

So a normal install is unchanged and no extra Tools entry appears. For a support case, the reporter edits that one line to true (or runs INSTALL_SDL_DOCTOR=true ./RAOfflineProxy-...-Install.sh) — no rebuild needed. Switching it back off removes the entry again rather than leaving a stale one behind.

@misantronic
misantronic merged commit ccf4558 into main Aug 9, 2026
2 checks passed
@misantronic
misantronic deleted the rocknix/sdl-doctor branch August 9, 2026 17:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant