RK3568平台Rockit多媒体库编译实战：从环境准备到运行测试

刚拿到一块 RK3568 的开发板要把 Rockit 这套多媒体库编译起来跑一轮测试记录一下整个过程的思路、步骤和踩过的坑。搜热点时看到很多人也在碰 RK3568 的 OV5695 调试、BT.1120 输出、设备树修改之类的问题这些其实都绕不开 Rockit 周边这套工具链。这篇文章就按我实际操作的顺序来写从环境准备到编译执行再到运行测试用例最后把典型报错整理成速查表希望对正在折腾 RK3568 的同行有帮助。Rockit 的定位要搞清楚。它是瑞芯微面向多媒体和视觉应用的一套用户态库把 ISP 图像处理、视频编解码、RGA 加速这些底层能力封装成相对统一的 C/C 接口。在 RK3568 上做摄像头采集、视频推流、AI 前处理基本都会碰到它。编译 Rockit 本身不难难的是把交叉编译环境、系统依赖、设备树配置、Sensor 驱动这些周边因素理顺。这篇文章主要适合两类人一是刚接触 RK3568、准备跑通 Rockit SDK 做视频开发的新手二是已经在用 Rockit、但编译或运行阶段卡住的工程师。1. 在动手之前先梳理 Rockit 在 RK3568 上的组成Rockit 并不是一个孤立的库文件它更像是一套多媒体中间件依赖底层 MPPMedia Process Platform、RGA、DPP、AIQISP 调试等组件。在编译之前先把这些概念理清楚后面排查问题会省很多时间。1.1 Rockit 的模块划分RK3568 的 Rockit 框架大致分成四块VIVideo Input从 MIPI CSI、BT.1120、LVDS 等接口采集图像数据经过 ISP 处理后输出给内存或直接送显。RK3568 的 ISP 支持 8M 像素OV5695 这类 500 万 Sensor 是很常见的搭配。VENC/VDEC硬件编码和解码支持 H.264、H.265、JPEG。这部分底层走的是 MPPMPP 编译不过的话 Rockit 编码功能基本全废。RGARaster Graphic Acceleration负责图像缩放、裁剪、格式转换、旋转等操作。Rockit 的 AI 前处理大量依赖 RGA如果 rga 头文件版本不对编译 Rockit 时会报一堆函数未定义。AIQCamera 3A自动曝光、自动白平衡、自动对焦的算法库。这个库通常由瑞芯微以闭源二进制形式提供编译 Rockit 时需要链接相关 .a 文件。如果你在编译过程中发现某个模块始终有问题建议先确认整个 SDK 的版本是否匹配。Rockit 代码迭代很快不同版本的 MPP、RGA 头文件可能不兼容混用版本是最常见的编译失败原因。1.2 编译方式的选择Rockit 在 RK3568 上有两种典型编译方式在 SDK 源码树内编译瑞芯微发布的完整 SDK 中Rockit 位于external/rockit/与 MPP、RGA、Camera 驱动等一起构建。这种方式最省心因为依赖关系由构建系统统一处理。独立下载 Rockit 源码交叉编译只拿到rockit目录或者从 GitHub 拉取源码然后用交叉编译器单独编译。这种方式更灵活但需要自己手动指定依赖库和头文件路径。大部分情况下我建议直接用 SDK 内的整体构建但如果只是验证一个模块独立编译会更快。下面以独立编译为主线因为它能把依赖关系暴露得更清楚也更容易定位问题。2. 环境准备交叉编译工具链与 SDK 目录结构编译 Rockit 之前先把交叉编译环境搭好。RK3568 是 ARMv8 架构的 64 位平台常见工具链是aarch64-linux-gnu-系列。可以使用瑞芯微 SDK 自带的工具链也可以使用系统的gcc-aarch64-linux-gnu。2.1 安装交叉编译工具链我用的是 Ubuntu 22.04直接安装系统包方便一些sudo apt update sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnu验证工具链是否可用aarch64-linux-gnu-gcc --version如果开发板使用的是 Buildroot 或 Yocto 环境则需要使用对应 SDK 中提供的工具链路径通常类似export CROSS_COMPILE/path/to/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu-有一点需要留意工具链版本不要过于陈旧。Rockit 新版本代码用到了 C14 甚至 C17 的特性老工具链可能遇到语法报错这类报错往往非常锻炼耐心。2.2 确认 SDK 目录结构独立编译时建议把依赖库的源码或头文件提前准备好。一次比较典型的目录布局如下rk3568_sdk/ ├── external/ │ ├── rockit/ │ │ ├── include/ │ │ ├── src/ │ │ └── sample/ │ ├── mpp/ │ ├── rga/ │ └── camera_engine/ │ └── include/ ├── kernel/ ├── u-boot/ └── buildroot/Rockit 的源码目录在瑞芯微 SDK 中通常是external/rockit依赖的头文件在external/camera_engine/include、external/mpp/include、external/rga/include等位置。编译时可以通过-I参数把这些路径加进来也可以通过环境变量统一设置后面会详细说明。2.3 安装必要的宿主工具虽然最终产物是 ARM 平台的可执行文件但编译过程中可能用到cmake、make、pkg-config、python3等工具这些属于宿主机的构建工具也需要提前装好sudo apt install cmake make pkg-config python3如果是老一点的 SDK可能还会用到android-tools相关的工具去打包或刷机但编译 Rockit 本身用不到这里就不展开了。3. Rockit 编译流程一条命令背后的逻辑Rockit 提供了build.sh或在CMakeLists.txt中预设好的交叉编译工具链文件。实际操作时我会先看一遍README和CMakeLists.txt开头的注释确认默认参数和输出路径。3.1 查看编译脚本入口以 SDK 内的 Rockit 源码为例进入目录后第一件事是查看文件结构cd external/rockit ls -la cat README.md通常可以看到build.sh或者CMakeLists.txt。如果有build.sh先打开它看里面的关键变量#!/bin/bash export ARCHarm64 export CROSS_COMPILEaarch64-linux-gnu- export PATH$PATH:/path/to/toolchain/bin cmake -DCMAKE_C_COMPILER${CROSS_COMPILE}gcc \ -DCMAKE_CXX_COMPILER${CROSS_COMPILE}g \ -DCMAKE_SYSTEM_NAMELinux \ -DCMAKE_SYSTEM_PROCESSORaarch64 \ ${ROCKIT_ROOT_DIR} make -j$(nproc)有些版本的脚本还会引用RK_PLATFORM、RK_CHIP等变量用来控制 BOARD 相关配置。比如export RK_CHIP3568 export RK_PLATFORMlinux这些变量会影响目标平台的 sysroot 路径和特定头文件选择。如果你的板子不是瑞芯微标准 SDK需要检查这些路径是否指向实际存在的目录。3.2 一个可参考的交叉编译命令在没有现成脚本的情况下我整理了一套可直接执行的步骤export ROCKIT_ROOT$(pwd) export MPP_ROOT/path/to/external/mpp export RGA_ROOT/path/to/external/rga export CAMERA_ENGINE_ROOT/path/to/external/camera_engine mkdir -p build cd build cmake .. \ -DCMAKE_C_COMPILERaarch64-linux-gnu-gcc \ -DCMAKE_CXX_COMPILERaarch64-linux-gnu-g \ -DCMAKE_SYSTEM_NAMELinux \ -DCMAKE_SYSTEM_PROCESSORaarch64 \ -DCMAKE_BUILD_TYPERelease \ -DROCKIT_PLATFORMRK3568 \ -DROCKIT_HAL_PATH$CAMERA_ENGINE_ROOT \ -DROCKIT_MPP_PATH$MPP_ROOT \ -DROCKIT_RGA_PATH$RGA_ROOT然后再执行make -j$(nproc)如果顺利会在build/目录下生成librockit.so和对应的头文件复制目录示例程序可能生成在build/samples/下面。3.3 编译选项说明上面几个关键编译选项的解释ROCKIT_PLATFORM: 告诉库代码目标芯片型号影响部分硬件相关宏定义。比如 RK3568 的 ISP 支持、编解码规格都会与 RK3588 有差异。ROCKIT_HAL_PATH: 指向 camera_engine 的根目录用于编译调用 ISP 相关接口。如果没有指定可能出现rk_aiq.h找不到的报错。ROCKIT_MPP_PATH: 指向 MPP 解码器库路径缺失时会报mpp_*.h相关错误。ROCKIT_RGA_PATH: 指向 RGA 加速库路径缺失时会报rga.h相关错误。这里有个经验宁可把依赖头文件目录多传几个也不要一开始就追求精简。Rockit 源码里对私有头文件的引用比对外 API 多得多漏一个目录都会让编译中途中断而报错位置往往离真正的缺失头文件很遥远。4. 运行测试用例编译成功只是第一步编译生成库只是热身真正能体现问题是运行测试程序。Rockit 自带的一堆sample程序是快速验证功能的最短路径。4.1 找到合适的 sample 程序在 Rockit 源码中示例程序一般位于sample/目录常见的有sample_vi_venc: 从 VI 采集视频编码为 H.264保存为文件或通过 RTSP 推流sample_venc: 纯编码可以直接把 YUV 文件编码为 H.264/H.265sample_vdec: 解码测试读入码流文件输出 YUVsample_vi: 仅图像采集输出原始图像或经过 ISP 处理的图像sample_camera: 配合 AIQ 使用的摄像头采集程序我先跑sample_venc和sample_vi因为这两个对传感器和显示环境的依赖最少最容易验证基础链路。编译这些 sample 前需要确认 CMake 中的BUILD_SAMPLE宏是否打开。有的 SDK 默认不编译 sample需要手动开启。在 cmake 命令行追加-DBUILD_SAMPLEON如果样列代码里还引用了live555等库需要先交叉编译它们。瑞芯微 SDK 里通常会捆绑三方库源码位置可能在external/下将其一并编译或者链接静态库即可。4.2 使用 sample_venc 快速验证编码链路以sample_venc为例典型用法是把 YUV 文件编码成 H.264./sample_venc -w 1920 -h 1080 -f 3 -t 7 -b 4000000 -i input.yuv -o output.h264 -n 300 -s 30参数含义大致是-w/-h: 输入宽度和高度-f: 输入像素格式比如 3 表示 NV12-t: 编码类型比如 7 表示 H.2648 表示 H.265-b: 码率-n: 编码帧数-s: 帧率如果输入 YUV 文件格式或参数不匹配程序可能会直接退出或者在编码中途出现花屏。所以测试时最好先准备一段已知正确的 NV12 文件或者用工具从解码器转出来。4.3 使用 sample_vi_venc 验证摄像头链路有摄像头时跑sample_vi_venc能一次验证 Sensor 配置、ISP 通路、编码通路。一个典型命令./sample_vi_venc --aiq1 --sensorov5695 --width1920 --height1080 --formatNV12 --vench264 --rate30 --bitrate8000000 --output/tmp/test.h264运行日志中关注三点Sensor 是否注册成功日志里会打印 sensor 名称和对应的 I2C 地址ISP 通路是否正常如果 AIQ 初始化失败通常会打印rkaiq相关错误编码码率是否接近设定值如果码率异常偏差大可能是 MPP 配置异常如果日志中出现fail to open device /dev/video0一类错误不要先怀疑 Rockit先检查板卡设备节点ls /dev/video* ls /dev/media*常见情况是驱动没加载或者设备树里摄像头节点没配好。这里提醒一个我之前踩过的坑RK3568 某些 SDK 默认把video0分配给 ISPvideo1分配给 VIPP不同内核版本命名可能不同Rockit 并不是直接打开/dev/videoX的它的路由是通过 media-controller 框架完成的所以如果 media 设备拓扑不对即使/dev/videoX存在依然无法采到数据。4.4 把编译好的库与测试程序部署到板端把交叉编译得到的.so、可执行程序和依赖库一起拷贝到开发板。这里建议使用 NFS 挂载或者 ADB pushadb push build/librockit.so /usr/lib/ adb push build/samples/sample_vi_venc /userdata/ adb push build/samples/input.yuv /userdata/然后通过串口或 SSH 进入板子设置动态库路径export LD_LIBRARY_PATH/usr/lib:$LD_LIBRARY_PATH运行前可以用ldd检查是否缺少依赖库ldd ./sample_vi_venc如果输出中出现not found需要把对应的.so一并推到板子上。常见的缺失库包括librockit.solibrkaiq.solibrga.solibmpp_enc.so或libmpp_dec.solibdrm.solibion.so其中libion.so特别值得注意。Rockit 早期版本依赖 ION 内存分配器但新内核上 ION 已经被 DMA-BUF Heap 替代某些 SDK 里可能已经没有/dev/ion节点导致运行时初始化失败。如果你的 Rockit 版本比较老遇到open /dev/ion failed这种报错要么把内核 ION 驱动配置打开要么换用新版本 Rockit 和 MPP。运行测试前也别忘了检查权限。Rockit 涉及DRM、RGA、ION等设备节点如果直接 root 运行当然没问题但如果是普通用户很可能会因为权限不足打不开设备。最简单的办法是先用 root 跑一遍确认链路正常后再去完善权限配置。5. 编译和运行阶段的典型报错与排查方案这部分是我觉得最实用的一节。整理一下我在 RK3568 上编译 Rockit 时遇到的几个高频问题附上根因分析和解决办法。5.1 头文件找不到rk_aiq.h、mpp_enc.h、rga.h编译报错示例fatal error: rk_aiq.h: No such file or directory根因通常是依赖路径没有加到编译搜索路径中。Rockit 的头文件分布在多个模块里比如 AIQ 的头文件在camera_engine/includeMPP 的头文件在mpp/incRGA 的在rga/include。最简单的办法是用-I把这三个路径都加上cmake -DCMAKE_C_FLAGS-I/path/camera_engine/include -I/path/mpp/inc -I/path/rga/include另外Rockit 自己的 include 目录中还有个rk_type.h定义基础类型如果报错定位到rk_type.h检查一下是不是 SDK 目录结构被改动过导致相对路径失效。5.2 链接阶段找不到库cannot find -lrockit出现这种情况多半是因为编译依赖顺序不对或者库路径不对。Rockit 的库本身是最终产物但如果 sample 程序链接时指定了-lrockit而librockit.so还没生成或者没有指定-L路径就会出现这个报错。解决方式是先编译生成librockit.so再编译 sample。或者在 CMakeLists 中调整 target 顺序。如果确认librockit.so存在但仍然报错用find看一下实际文件名确认是不是没有软链接或版本号后缀导致-lrockit无法匹配。5.3 运行时缺少链接库symbol lookup error./sample_vi: symbol lookup error: /usr/lib/librockit.so: undefined symbol: RK_MPI_VENC_CreateChn这个报错很典型通常是板子上的librockit.so与 MPP 版本不匹配。比如板子的系统里已经有一个libmpp_enc.so你新编译的 Rockit 依赖的却是另一版本的 MPP 接口。这种情况下先把板子上旧的 MPP 库、旧 Rockit 库备份后移走再放入新编译的库然后用ldd重新确认依赖关系。5.4 设备节点不通open /dev/video0 失败很多人在这一步被卡住以为是 Rockit 编译问题实际上大部分是设备树和驱动问题。排查顺序确定内核有没有编译进 ISP、MIPI DPHY、Sensor 驱动查看设备树中 Camera 节点是否使能检查/dev/mediaX和/dev/videoX是否存在用media-ctl打印当前 media 拓扑确认数据流路由与 Rockit 期望一致比如 OV5695 这类 Sensor通常需要 endpoing 里的 reg 值对应正确如果 reg 错误驱动解析时无法匹配到正确的虚拟通道。而且不同内核版本对数据通道的描述方式可能不同有的用>open /dev/ion failed allocate ion memory failedRK3568 的内核版本通常已经切换到 DMA-BUF HeapRockit 如果仍然走 ION 接口就需要修改 Rockit 源码或者开启内核的旧 ION 兼容。检查内核配置cat /sys/kernel/debug/dri/0/summary ls /dev/dma_heap如果/dev/dma_heap存在说明系统使用的是 DMA-BUF Heap。这种情况下需要确认你的 Rockit 版本是否支持USE_DMA_HEAP。有的 SDK 会有编译宏-DROCKIT_USE_DMA_HEAPON如果没有这个宏可以尝试升级 MPP 和 Rockit 到较新版本或者给内核加上 ION 兼容支持。但我的建议是优先升级用户态库因为改内核增加旧框架支持后续可能会引入新的不稳定因素。5.6 编译速度慢搜热点时发现不少人在搜“编译慢”确实在 RK3568 SDK 里如果没有使用 ccache全量编译 Rockit 和相关模块会非常依赖 CPU。如果只是单独编译 Rockit代码量不算大十几分钟到半小时内能完成。但如果你是从整个 SDK 开始构建建议开启 ccachesudo apt install ccache export USE_CCACHE1 export CCACHE_DIR/path/to/.ccache在 cmake 构建时可以设置-DCMAKE_C_COMPILER_LAUNCHERccache -DCMAKE_CXX_COMPILER_LAUNCHERccache二次编译会快非常多。如果是在多核机器上编译直接用-j$(nproc)即可但如果内存不大-j太高可能会导致 OOM建议 16G 内存以下用-j4或-j8。5.7 常见报错速查表报错信息可能原因解决方向rk_aiq.h: No such file or directorycamera_engine 头文件路径未加入添加-I指向camera_engine/includempp_enc.h: No such file or directoryMPP 头文件路径未加入添加-I指向mpp/incundefined reference to RK_MPI_*链接顺序或库缺失调整链接顺序、确认librockit.soerror: ‘V4L2_PIX_FMT_NV12’ undeclared内核头文件版本过旧或未包含 v4l2 头文件安装/更新 linux-libc-dev或添加对应 include 路径open /dev/ion failed内存分配器不匹配开启内核 ION 兼容或切换 Rockit DMA_HEAP 编译选项/dev/video0 open failed设备树或驱动问题检查 media 拓扑、设备树节点、Sensor 驱动Segmentation fault多为库版本混用或内存配置异常ldd检查库依赖、替换旧 MPP/Rockit 库No space left on device板端存储不足或 tmp 分区过小清理板端空间或调整/tmp大小6. 编译完成之后的扩展玩法BT.1120 输出和多路 Sensor 采集一旦 Rockit 编译通过并且基础测试正常可以尝试的场景就多了。热点中有人提到“配置 bt1120 输出”和“调试 ov5695”这两个我都试过一点简单说一下在 Rockit 框架下的入口。RGB/BT.1120 输出这类需求通常发生在需要把视频送出去显示的场景。Rockit 中对应的模块是 VOVideo Output或者使用 RGA 旋转缩放后再接显示通路。在 RK3568 上BT.1120 输出能力取决于芯片 Video Port 的接口定义。实际调试时首先要确认设备树中的 VOP 节点、显示接口、时钟配置都正确其次在 Rockit 中创建 VO 通道时需要把输出分辨率、像素格式、时序参数配成 BT.1120 对应的模式。这个过程比编译复杂得多很多参数需要芯片手册和显示设备的规格表对照填。OV5695 调试则主要落在 Camera 接入侧。在 Rockit 框架下先确认设备树中 OV5695 的 I2C 地址、reset GPIO、power GPIO、MIPI data lanes 等配置与 Sensor 硬件连接一致。然后在camera_engine配置文件中加入 OV5695 的 sensor 名称和对应的初始化序列。接着编译进 AIQ 的 sensor 库Rockit 初始化时才能正确加载。如果图像颜色不对多半是白平衡增益没生效如果预览黑屏大概率是数据通路没通而不是算法问题。这两类扩展方向都需要在“编译 Rockit”之外多花数倍时间但这也是 RK3568 平台好玩的地方。一套 SDKS 基础打牢之后很多上层功能都是接口配置和参数调试的事。7. 编译成功后我还会做的一组常规验证为了让后续开发少踩坑库编译成功后我一般会按顺序跑这组验证用sample_venc编码一段固定 YUV 数据确认 MPP 编解码链路正常用sample_vdec解码刚才的 H.264 数据确认闭环一致接上摄像头后跑sample_vi确认采集链路正常再跑sample_vi_venc做采集编码全流程启用 RGA 测试验证图像缩放格式转换是否满足后续 AI 前处理需求这组验证能够把 Rockit 依赖的各个核心子系统快速摸底一遍。如果其中某一步失败重点排查对应子系统而不是 Rockit 本身。比如第 2 步解码失败问题通常在 MPP而不是 Rockit 框架层。另外建议在板端测试时打开 Rockit 的调试日志。Rockit 支持通过环境变量控制日志级别例如export RK_LOG_LEVEL1这样运行时会输出更多内部调用细节定位问题会直观很多。具体变量名在不同版本可能略有差异可以在源码中搜索log_level或rk_log.回到开头说的那台板子我最后把编译好的 Rockit 库和 sample 程序打到文件系统镜像里重启验证了一遍自动加载和开机自启的流程。期间遇到的一次问题是启动脚本先加载了旧版 MPP 库导致 Rockit 初始化报版本不匹配。解决方法是把脚本里的LD_LIBRARY_PATH显式指向新库目录并把旧库目录从路径中移走。实际测试中还有个小技巧值得分享调试 Rockit 时不要只盯日志里的错误码。Rockit 很多错误码对应的是底层驱动或 MPP 模块的返回值光看数字很难定位。比较实用的做法是先在板端用v4l2-ctl直接测一遍摄像头是否出图再用mpi_enc_test这类 MPP 自带测试工具验证编解码最后回到 Rockit 层组合调试。这样一层层往上查每一步的基础都确认过问题范围会迅速缩小。这次编译测试花了一天左右主要时间都耗在依赖库版本对齐和摄像头设备树的排查上。如果只编译 Rockit 而不跑 sample那真的只是“编译”而已没有太大参考价值。我建议每个拿到 RK3568 板子的人尽量把编译、部署、运行这条完整链路都走通一遍后续做任何上层功能心里都有底。最后再补充一个小习惯Rockit 编译产物建议保留完整的编译日志万一后续换了 SDK 版本或者改了依赖路径能够快速 diff 出差异点。把这些日志和修改过的 CMake 参数统一放在一个文档里下次遇到问题翻一翻往往能省下不少重复排查的时间。