Rockchip 平台 librga 安装部署与权限问题排坑指南

在基于瑞芯微（Rockchip）芯片（如 RK3566、RK3568、RK3588 等）的嵌入式 Linux 开发中，多媒体与边缘 AI 处理有一条经典的高性能流水线：

$$\text{MPP (硬件编解码)} \longrightarrow \text{RGA (图像预处理)} \longrightarrow \text{RKNN (神经网络推理)}$$

• MPP（Media Process Platform）：调用 VPU 硬件，对高分辨率视频流（H.264/H.265/VP9 等）进行低延迟解码，输出原始图像帧（通常为 YUV/NV12 格式）。
• RGA（Raster Graphic Acceleration Unit）：调用专用 2D 硬件加速器，在零 CPU 占用下完成图像格式转换（如 NV12 转 BGR/RGB）、硬件缩放、居中裁剪及旋转，将图像尺寸与色彩空间对齐为模型输入要求。
• RKNN：利用 NPU 硬件对预处理后的张量执行深度学习模型推理。

这两大硬件加速库在部署上有显著区别：MPP 没有官方预编译成品库，必须在本地或交叉编译环境中由源码构建；而 librga 仓库内置了各架构的预编译成品库，直接部署即可。

本文以 aarch64 平台（立创·泰山派 RK3566、野火鲁班猫等）为例，详细记录 MPP 的本机源码编译（包含低内存防 OOM 技巧）与部署、librga 的规范安装验证，以及普通用户调用 RGA 时 /dev/rga 权限拒绝的完整排坑与永久解决方案。

---

一、前置驱动节点检查

无论是使用 MPP 还是 RGA，均依赖内核底层对应的硬件驱动支持。在部署应用库前，请务必先检查设备节点：

1.1 检查 MPP 硬件驱动（VPU）

ls -l /dev/mpp_service

• 若输出类似 crw-rw---- 1 root video ... /dev/mpp_service，说明内核 VPU 驱动已就绪。
• 若提示 No such file or directory，说明当前固件内核缺少 MPP 驱动，硬件视频编解码将无法使用。

1.2 检查 RGA 硬件驱动

ls -l /dev/rga

• 若输出类似 crw-rw---- 1 root video ... /dev/rga，说明内核 RGA 驱动工作正常。
• 若缺失此节点，多见于第三方的极简版 Armbian 固件，此时需更换官方标准发行版固件或为内核配置并编译 rkrga 模块。

---

二、Rockchip MPP 本机源码编译与部署

MPP（Media Process Platform）是瑞芯微官方的 VPU 编解码硬件库，仅负责视频编解码，与 NPU AI 推理独立：

• 支持硬件解码：H.265 / H.264 / H.263 / VP9 / VP8 / MPEG-4 / MPEG-2 / MPEG-1 / VC1 / MJPEG / AV1
• 支持硬件编码：H.265 / H.264 / VP8 / MJPEG
• 官方仓库：https://github.com/rockchip-linux/mpp
• 官方开发指南：仓库内 doc/Rockchip_Developer_Guide_MPP_CN.md

2.1 安装编译依赖

sudo apt update
sudo apt install -y git cmake make gcc g++ ffmpeg

2.2 拉取 MPP 源码

# 官方 GitHub 地址
git clone https://github.com/rockchip-linux/mpp.git

# 国内加速可选：
# git clone https://mirror.ghproxy.com/https://github.com/rockchip-linux/mpp.git
# 或者 Gitee 镜像：
# git clone https://gitee.com/mirrors/rockchip-mpp.git

cd mpp

2.3 关键防坑：低内存开发板防 OOM 编译

立创·泰山派 RK3566 等开发板常为 1GB 或 2GB 内存版本。在多核全开编译大型 C++ 项目时，极其容易触发内核 OOM Killer，导致编译中途直接报错 Killed。

进入 aarch64 编译构建目录：

cd build/linux/aarch64

修改编译脚本 make-Makefiles.bash，将并发编译参数改为单线程 -j1：

vim make-Makefiles.bash

找到关于 cmake --build 的分支逻辑，修改为 -j1：

if [ "${CMAKE_PARALLEL_ENABLE}" = "0" ]; then
    cmake --build .
else
    cmake --build . -j1
fi

执行编译构建：

./make-Makefiles.bash

2.4 部署 MPP 头文件

编译完成后，当前位于 build/linux/aarch64 目录下，将源码 include 拷贝至系统目录：

sudo mkdir -p /usr/include/mpp
sudo cp ../../../inc/* /usr/include/mpp/

后续 C/C++ 工程中即可按官方规范引用：

#include <mpp/rk_mpi.h>
#include <mpp/mpp_err.h>

2.5 部署 MPP 动态库（推荐）

在 build/linux/aarch64/mpp/ 目录下生成了以下产物：

• librockchip_mpp.so.0（动态库本体）
• librockchip_mpp.so.1、librockchip_mpp.so（软链接）
• librockchip_mpp.a（静态库）

注意：部署时必须将库本体与软链接一同拷贝，否则动态链接器在运行时可能找不到符号：

cd mpp
sudo cp librockchip_mpp.so.0 librockchip_mpp.so.1 librockchip_mpp.so /usr/lib/aarch64-linux-gnu/
sudo ldconfig

2.6 部署 MPP 静态库（可选）

如需脱离系统动态库独立静态打包，可复制静态库：

sudo cp librockchip_mpp.a /usr/lib/aarch64-linux-gnu/

2.7 MPP 校验与版本查看

确认系统已成功载入动态库：

ldconfig -p | grep rockchip_mpp

运行编译产物中的测试工具查看 MPP 详细版本及支持特性：

# 回到 build/linux/aarch64 目录
cd ..
./test/mpp_info_test

---

三、Rockchip librga 部署与配置

RGA（Raster Graphic Acceleration Unit）是 2D 图形硬件加速器，用于快速执行绘制、缩放、旋转、bitBlt、alpha 混合以及色彩空间转换（如 NV12 到 RGB/BGR），在图像预处理阶段性能远高于 CPU OpenCV 软转换。

• 官方仓库：https://github.com/airockchip/librga
• 官方开发指南：Rockchip_Developer_Guide_RGA_CN.md
• 官方 FAQ：Rockchip_FAQ_RGA_CN.md

3.1 库类型说明

官方仓库自带各主流平台的预编译二进制文件，无需从源码重新编译：

• librga.so（动态库，推荐）：应用开发、调试以及 Python 使用 ctypes 调用时必需。
• librga.a（静态库，可选）：供 C/C++ 静态编译，Python 无法调用。

💡 环境准备建议：
若后续需在 Python 环境下通过 ctypes 调用 RGA（例如实现视频帧预处理并对接 RKNN 推理），建议配合独立的 Python 虚拟环境运行，避免污染或破坏系统环境。可参考前文：
👉 RK3566 Ubuntu26.04 安装 Python3.12

3.2 获取源码仓库

git clone https://github.com/airockchip/librga.git

# 国内加速镜像：
# git clone https://mirror.ghproxy.com/https://github.com/airockchip/librga.git

cd librga

3.3 部署头文件

仓库 include/ 下直接是 .h/.hpp 文件。为规范代码结构，将其拷贝至 /usr/include/rga/：

sudo mkdir -p /usr/include/rga
sudo cp include/* /usr/include/rga/

代码中按如下方式引用：

#include <rga/im2d.h>
#include <rga/rga.h>

3.4 部署动态库与静态库

针对 aarch64 平台，部署预编译库到系统库目录并刷新缓存：

# 部署动态库（推荐）
sudo cp libs/Linux/gcc-aarch64/librga.so /usr/lib/aarch64-linux-gnu/
sudo ldconfig

# 部署静态库（可选）
sudo cp libs/Linux/gcc-aarch64/librga.a /usr/lib/aarch64-linux-gnu/

3.5 版本查询与日志调试

确认动态库已注册进系统链接器：

ldconfig -p | grep librga

查询 librga API 版本号：

strings /usr/lib/aarch64-linux-gnu/librga.so | grep rga_api | grep version

查询当前内核 RGA 驱动版本：

cat /sys/kernel/debug/rkrga/driver_version
# 若 debugfs 不可用，可查询 proc 节点
cat /proc/rkrga/driver_version

开启详细运行时调试日志（librga $\ge$ 1.9.0 支持）：

export ROCKCHIP_RGA_LOG=1
export ROCKCHIP_RGA_LOG_LEVEL=3

---

四、踩坑排查：调用 RGA 时的 /dev/rga 权限问题

4.1 问题现象

在开发板上以非 root 用户（如默认用户 cat、pi、linaro、ubuntu 等）运行 Python 脚本或 C/C++ 程序时，经常出现 RGA 初始化失败报错：

E [librga]: rga_init: failed to open /dev/rga, errno=13 (Permission denied)

查看设备权限 ls -l /dev/rga 会发现其权限默认为 crw-rw---- 1 root video ...，普通用户无权读写该设备节点。

4.2 临时解决方案

最快速的临时方案是直接修改节点权限：

sudo chmod a+rw /dev/rga

⚠️ 缺陷：Linux 系统的 /dev 属于虚拟内存文件系统（devtmpfs）。设备重启后节点会重新生成，权限立即恢复原样，导致再次开机应用又报权限拒绝。

4.3 永久解决方案（推荐）

方案 A：配置 udev 规则（最通用可靠）

通过在 /etc/udev/rules.d/ 中添加规则，让系统在每次创建 /dev/rga 节点时自动将其模式设置为 0666：

# 写入 udev 规则
echo 'KERNEL=="rga", MODE="0666"' | sudo tee /etc/udev/rules.d/99-rga.rules

# 重新加载规则并立即触发
sudo udevadm control --reload-rules
sudo udevadm trigger

检查节点权限确认生效：

ls -l /dev/rga
# 正常输出：crw-rw-rw- 1 root video ... /dev/rga

方案 B：将当前用户加入所属设备组

如果不想将设备节点全局开放为 0666，可将当前运行用户添加至所属的 video 用户组：

sudo usermod -aG video $USER

提示：修改用户组后需注销并重新登录当前会话方可生效。

---

五、卸载与环境清理

如需升级版本或重置开发板系统环境，可执行以下命令清理：

5.1 卸载 MPP

sudo rm -f /usr/lib/aarch64-linux-gnu/librockchip_mpp.so*
sudo rm -f /usr/lib/aarch64-linux-gnu/librockchip_mpp.a
sudo rm -rf /usr/include/mpp
sudo ldconfig

5.2 卸载 librga

sudo rm -f /usr/lib/aarch64-linux-gnu/librga.so
sudo rm -f /usr/lib/aarch64-linux-gnu/librga.a
sudo rm -rf /usr/include/rga
sudo rm -f /etc/udev/rules.d/99-rga.rules
sudo ldconfig

---

六、总结

在 Rockchip 嵌入式硬件加速体系中：

1. MPP 承担编解码重任，部署关键在本机编译的内存保护（修改脚本采用 -j1 单线程降并发防 OOM）；
2. librga 承担 2D 硬件预处理重任，部署关键在利用官方预编译库快速归档规范；
3. 权限机制不可忽视，配置 udev 规则可以一劳永逸避免生产/调试环境中因普通用户权限导致的 /dev/rga 调用崩溃。

两者结合，即可为后续的 RKNN 边缘 AI 推理提供高吞吐、零 CPU 瓶颈的底层多媒体加速支持。

---

相关阅读与链路实践

• Python 环境隔离：RK3566 Ubuntu26.04 安装 Python3.12
• 边缘 AI 推理落地：RK3566 搭建 RKNN-Toolkit2 环境笔记