fix(rockchip-rk3588): Enable mesa-vpu extension for GPU acceleration

[brainwavecoder9]

Description

This PR enables GPU acceleration for all RK3588 boards (Orange Pi 5/5B/5+, Rock 5A/5B/5C, etc.). For desktop use it's probably not noticeable, but for 3D graphics, ML inference, and video processing expect 10-100x improvement.

The issue is that RK3588 boards ship with llvmpipe software rendering instead of GPU acceleration on desktop images due to driver binding precedence. The proprietary mali driver is selected by default, which Mesa cannot use. The panthor-gpu overlay resolves this.

The mesa-vpu extension (May 2024) was created for this purpose, with the author intending this to be "enabled on all for rk3588 distributions". However, the rockchip family config was defined before this and was never updated.

Fixes the root cause of issues like #7507, #7504.

Documentation summary for feature / change

Short description: Enable mesa-vpu extension for RK3588 GPU acceleration

Summary: Desktop images will now use hardware GPU acceleration (Mali-G610/Panfrost) as the default instead of software rendering (llvmpipe). The extension automatically configures the panthor-gpu overlay for vendor kernel builds.

Example of usage: After flashing desktop image, glxinfo | grep renderer shows Mali-G610 (Panfrost) instead of llvmpipe

Workaround for existing systems: Add overlays=panthor-gpu to /boot/armbianEnv.txt and reboot.

How Has This Been Tested?

Tested on Orange Pi 5 Plus 16GB with Armbian 25.8.1 Noble vendor 6.1.115 XFCE:

• Before: glxinfo shows llvmpipe (LLVM 20.1.2, 128 bits)
• After: glxinfo shows OpenGL renderer string: Mali-G610 (Panfrost)
• Verified with eglinfo showing GPU acceleration working
• Community validation: https://forum.armbian.com/topic/55941-custom-build-on-new-version25110-is-not-enabling-panfrost-mali-gpu-driver-boardorangepi5-plus-branchvendor-releasenoble-desktopcinnamon/#comment-227661

Additional Acknowledgement

Shout out to @pollen-robotics for letting me beta test Reachy Mini, a project cool enough to inspire me to actually need this GPU.

Summary by CodeRabbit

• New Features
  • Mesa VPU hardware acceleration is now enabled by default on Rockchip RK3588 devices, improving graphics and video processing performance and compatibility.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai[bot]]

Walkthrough

Adds a new public shell function extension_prepare_config__enable_mesa_vpu() to the Rockchip RK3588 family config that calls enable_extension "mesa-vpu" during configuration preparation.

Changes

Cohort / File(s)	Change Summary
Rockchip RK3588 Family configuration config/sources/families/rockchip-rk3588.conf	Added new public function extension_prepare_config__enable_mesa_vpu() that invokes enable_extension "mesa-vpu" to auto-enable the mesa-vpu extension.

Sequence Diagram(s)

sequenceDiagram
    participant Loader as Config loader
    participant RK3588 as rockchip-rk3588.conf
    participant ExtMgr as enable_extension

    rect rgba(100,150,200,0.08)
    Loader->>RK3588: call extension_prepare_config__enable_mesa_vpu()
    end

    rect rgba(150,200,150,0.06)
    RK3588->>ExtMgr: enable_extension("mesa-vpu")
    ExtMgr-->>RK3588: success
    end

    RK3588-->>Loader: return

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

• Check function naming consistency with other extension_prepare_config__* functions.
• Confirm placement doesn't affect config load ordering or visibility.

Poem

🐰 I hopped into config, soft and spry,
A tiny function, a wink in my eye,
I call "mesa-vpu" with joy and delight,
Enabling VPU dreams through the night. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: enabling the mesa-vpu extension for GPU acceleration on RK3588 boards, which matches the file modification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 4cf545f2a72a95324b68e15596bce0789c87421d and 03455cb7fd9a5fecf035dd4f4a37d423b378697d.

📒 Files selected for processing (1)

• config/sources/families/rockchip-rk3588.conf (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-10-26T12:56:29.185Z

Learnt from: rpardini
Repo: armbian/build PR: 8820
File: config/sources/families/include/meson64_common.inc:51-53
Timestamp: 2025-10-26T12:56:29.185Z
Learning: In the Armbian build framework, scripts/config correctly handles kernel configuration option names both with and without the CONFIG_ prefix, so opts_m+=("CONFIG_RTL8822CS") and opts_m+=("RTL8822CS") are both valid and will work correctly.

Applied to files:

• config/sources/families/rockchip-rk3588.conf

🔇 Additional comments (1)

config/sources/families/rockchip-rk3588.conf (1)

58-61: Verify scope: Should this be conditional on desktop builds?

The PR description emphasizes that this fixes GPU acceleration for "desktop images," but the function unconditionally enables mesa-vpu for all RK3588 builds (including server/minimal). Please confirm:

1. Does the mesa-vpu extension internally handle non-desktop scenarios gracefully?
2. Should this be gated with a condition like [[ "${BUILD_DESKTOP}" == "yes" ]]?

Run the following script to examine the mesa-vpu extension implementation:

Additionally, please search the web for the mesa-vpu extension documentation to confirm its intended usage:

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions[bot]]

Hey @brainwavecoder9! 👋

Thanks for submitting your first pull request to the Armbian project — we're excited to have you contributing! 🧡
Your effort doesn’t just improve Armbian — it benefits the entire community of users and developers.

If you'd like to stay informed about project updates or collaborate more closely with the team,
you can optionally share some personal contact preferences at armbian.com/update-data.
This helps us keep in touch without relying solely on GitHub notifications.

Also, don’t forget to ⭐ star the repo if you haven’t already — and welcome aboard! 🚀

[brainwavecoder9]

Initially I added ENABLE_EXTENSIONS=mesa-vpu but saw in the docs that ENABLE_EXTENSIONS are expected to be build time options, meaning any other extensions will wipe out this change and cause issues similar to #7482.

Updated approach as the RK3588 family config should enable it by default and not overwrite even if others are set.

[brainwavecoder9]

I took more time to understand the conflicts here, and I am no longer confident that there is a simple/easy path to enabling the hardware.

Initially I was of the opinion that a default config would make for a better starting point, but it does not appear possible for desktop rendering and NPU to exist in the same configuration. NPU + GPU is possible, but only with software acceleration for desktop GPU (and that's probably not the best default).

In light of this, I'm leaning towards leaving things as-is and discussing how it could be best communicated that additional steps are necessary for different use cases. Instead of this change, I think a better approach might be to help bridge the gap between what ships and what is necessary to get where one wants to be. I'm working on a way to communicate this and would like your thoughts on how to best present to users. I also wonder about more deterministic overlays, or other patterns for making this happen.

Perhaps there is documentation out there that I haven't seen, but at this time I'd propose closing this without changes and continuing a discussion. I am happy to have that discussion wherever you would prefer, whether that is here, or on a new issue, or on the forum (whether an existing thread or elsewhere).

In any case, thank you for sharing these thoughts. I do very much appreciate your consideration.

[brainwavecoder9]

FYI here's a first pass... leaving here for reference but happy to put more work into communicating / integrating options (ideally I'd like a selector for one of the options, whether these specific breakdowns or otherwise)

RK3588 - GPU/NPU Driver Options & Config Guide

Main Configuration Options

Config	Kernel	Driver	Panthor Overlay	Desktop	Display Server	NPU (RKNN)	GPU Accel	Desktop Perf	Primary Use Case
A	6.1 vendor	libMali	OFF	None (headless)	N/A	✅ Full	⚠️ Basic	N/A	Production ML/Robotics
B1	6.1 vendor	libMali	OFF	XFCE	X11 only*	✅ Full	❌ Software	⚠️ Slow	ML + Occasional Debug
B2	6.1 vendor	libMali + WSI	OFF	GNOME/KDE	Wayland only**	✅ Full	⚠️ With WSI	⚠️ Unknown	NPU + Smooth Desktop (requires WSI)
C1	6.1 vendor	Panthor	ON	XFCE	X11 only*	❌ Broken	✅ Hardware	✅ Smooth	Desktop (no ML)
C2	6.1 vendor	Panthor	ON	GNOME	X11 or Wayland	❌ Broken	✅ Hardware	✅ Smooth	Desktop (no ML)
D1	6.12 mainline	Panthor	N/A (built-in)	XFCE	X11 only*	❌ No support	✅ Hardware	✅ Smoothest	Latest desktop (no ML)
D2	6.12 mainline	Panthor	N/A (built-in)	GNOME	X11 or Wayland	❌ No support	✅ Hardware	✅ Smoothest	Latest desktop (no ML)

XFCE does not support Wayland in any configuration *Requires WSI layer installation - unofficial with successful community reports

---

What Each Configuration Gives You

Config	NPU Performance	Desktop Performance	Hardware Used	Typical FPS
A - Headless	25-40ms inference (30-40 FPS YOLO)	N/A	NPU: Full, GPU: Minimal, CPU: Normal	N/A
B1 - XFCE Debug	25-40ms inference (30-40 FPS YOLO)	Slow/laggy UI	NPU: Full, GPU: Compute Only, CPU: High (renders desktop)	<30 FPS desktop
B2 - Wayland+WSI	25-40ms inference (30-40 FPS YOLO)	Community reported smooth	NPU: Full, GPU: Partial, CPU: Medium	Unknown (untested)
C - Panthor Desktop	N/A (no NPU)	Smooth 60 FPS UI	NPU: Unused, GPU: Full, CPU: Low	60 FPS desktop
D - Mainline Desktop	N/A (no NPU)	Smoothest 60 FPS UI	NPU: Unavailable, GPU: Full, CPU: Low	60 FPS desktop

---

Display Server Compatibility Matrix

Desktop Environment	Driver	X11 Support	Wayland Support	Result
XFCE	libMali	✅ Works (software rendering)	❌ XFCE has no Wayland	Slow desktop, NPU works
XFCE	Panthor	✅ Works (hardware accel)	❌ XFCE has no Wayland	Smooth desktop, no NPU
GNOME/KDE	libMali	✅ Works (software rendering)	⚠️ Requires WSI layer (experimental)	X11: Slow / Wayland+WSI: Possibly smooth, NPU works
GNOME/KDE	Panthor	✅ Works (hardware accel)	✅ Works (hardware accel)	Smooth desktop, no NPU

---

Required Packages by Configuration

Config	Kernel Packages	Driver Packages	NPU Packages	Desktop Packages
A	armbian-linux-image-vendor-rk3588	libmali-valhall-g610 .deb	rknnlite2 (pip)	None
B1	armbian-linux-image-vendor-rk3588	libmali-valhall-g610 .deb	rknnlite2 (pip)	xfce4, lightdm
B2	armbian-linux-image-vendor-rk3588	libmali-valhall-g610 .deb, mesa-vulkan-wsi-layer .deb	rknnlite2 (pip)	gnome/kde, gdm/sddm
C	armbian-linux-image-vendor-rk3588	mesa-vulkan-drivers (PPA)	N/A	xfce4/gnome, lightdm/gdm
D	armbian-linux-image-edge-rockchip-rk3588	mesa-vulkan-drivers (built-in)	N/A	xfce4/gnome, lightdm/gdm

---

Hardware Utilization Summary

Config	Mali-G610 GPU Load	NPU Load	CPU Load	Memory for Desktop
A - Headless	Idle/minimal	High (ML)	Normal	0 MB (no desktop)
B1 - XFCE Debug	Idle (not used)	High (ML)	High (SW rendering)	~300 MB
B2 - Wayland+WSI	Partial (Wayland compositor)	High (ML)	Medium	~1000 MB
C - Panthor Desktop	High (desktop)	Idle (unused)	Low	~300-1000 MB
D - Mainline Desktop	High (desktop)	N/A	Low	~300-1000 MB

---

The Fundamental Constraint

⚠️YOU MUST CHOOSE ONE OF THE FOLLOWING⚠️

Option 1: NPU Hardware Acceleration (libMali)

• ✅ NPU: RKNN/ML inference
• ✅ GPU for Compute: OpenCL, OpenCV acceleration, basic OpenGL
• ❌ GPU for Display on X11: No desktop hardware rendering (software rendering only)
• ⚠️ GPU for Display on Wayland: Hardware acceleration via WSI layer (GNOME/KDE only, community reported; NPU should work but untested in this combination)

Option 2: GPU Hardware Acceleration (Panthor)

• ✅ GPU for Display: Full desktop rendering at 60 FPS (smooth compositor)
• ✅ GPU for Compute: Full OpenGL/Vulkan/OpenCL support (faster than libMali)
• ❌ NPU: No RKNN/ML hardware acceleration

Both options offer equivalent VPU: Hardware video encode/decode (H.264, H.265, VP9)

WHY YOU (MOSTLY) CANNOT HAVE BOTH: The RK3588 hardware is capable of running NPU + GPU simultaneously, but the available software drivers conflict. Exception: libMali + Wayland + WSI layer (Config B2) may provide both but is experimental and community-reported only.

[khanh-it]

@brainwavecoder9 Please check https://forum.armbian.com/topic/56374-expected-default-graphics-acceleration-for-rk3588/#findComment-229221

[brainwavecoder9]

Thank you @khanh-it. I suspect there could be more configurations that have not made their way into formal support but yours is at least one potential "everything" so I have added it.

[khanh-it]

@brainwavecoder9

Wayland only**

https://github.com/ginkage/vulkan-wsi-layer/releases/tag/v1.3.276-1-d48decd https://github.com/zeyadadev/mali-vulkan-icd-wrapper With the latest patch from zeyadadev. The WSI also has X11 support, so Xwayland works!

[EvilOlaf]

Since we're close to 6.18 which may become next LTS kernel I could not recommend going for current, last but not least because rk3588 was in a barely working state when 6.12 came out. Lots of stuff has landed in mainline since then.