GPU driver

Two GPU drivers are shipped. ArchR boots Panfrost (Mesa) by default, with libmali available as opt-in.

Quick reference

Switch driver

EmulationStation → System Settings → Graphics → GPU driver → choose panfrost or libmali. Reboot.

The setting persists in /storage/.config/system.cfg (gpu.driver=panfrost|libmali). On boot, the gpudriver --start script:

1. Loads the chosen kernel module (panfrost or mali_kbase)
2. Bind-mounts the right user-space libraries over Mesa
3. Masks the wrong Vulkan ICD JSON

If the chosen driver fails to bind to the GPU node (e.g. mali_kbase reports a regulator error), the script automatically falls back to the other one so you get a graphical system either way.

Why Panfrost is the default

• Mesa 26.0.5 has solid Mali-G31 (Bifrost v9) support — no missing extensions for any libretro core we ship.
• MESA_GLTHREAD matrix tuned per-emulator (Flycast, PPSSPP) gives extra throughput.
• Active upstream: bug fixes land continuously; frozen vendor blob means stuck on whatever 2019 quirk shipped.
• Same API surface as libmali for everything except Vulkan.

When to try libmali

Specific edge cases reported in community testing:

• A specific emulator / game shows render glitches under Panfrost
• You want to try Vulkan-via-mali (PanVK at G31 isn't conformant)
• libretro shader pack X works one way but not the other

The runtime fallback means switching is low-risk — if the chosen driver fails to attach to the GPU at boot, the system swaps to the alternate automatically.

Mesa quirks applied (Panfrost path)

For RK3326 / Mali-G31, ArchR exports these globally for emulators:

PAN_MESA_DEBUG=forcepack            # forces format-pack on G31
                                    # (despite the name, NOT a debug flag)
MESA_NO_ERROR=1                     # skip GL error tracking
MESA_SHADER_CACHE_DIR=/storage/.cache/mesa_shader_cache
MESA_SHADER_CACHE_MAX_SIZE=128MB    # shader cache survives reboots

Per-emulator (only where benefit was confirmed):

MESA_GLTHREAD=true   # Flycast, PPSSPP standalone — see /docs/mesa-glthread-matrix

Vulkan

PanVK on Mali-G31 (Bifrost v9) is not conformant — the upstream Mesa team only ships PanVK officially for Mali-G610 (Valhall). ArchR disables PanVK at build time on RK3326 so emulators that probe for Vulkan don't try and fail.

If a future emulator update needs Vulkan and we've validated PanVK against it, the toggle would land in the same Graphics menu.

Troubleshooting

Black screen after switching to Panfrost. The DTBO overlay for your panel might not have loaded. Check with cat /sys/class/drm/card0/connector/*/status. Switch back to libmali via the recovery path:

1. Power off, remove the SD card
2. On a PC, mount the BOOT partition
3. Edit /storage/.config/system.cfg (on the storage partition) — set gpu.driver=libmali
4. Re-insert and boot

gpudriver warns "did not bind to GPU". The auto-fallback already triggered — your effective driver is the other one. Check journalctl -t gpudriver (over SSH) for the exact message.

Vulkan probe spam in logs. Some PortMaster ports try Vulkan first. Harmless — they fall back to GLES.