
清空记录
历史记录
取消
清空记录
历史记录

有了上篇的基础认知,本篇直接深入实操实战,逐段拆解 [mk-rootfs-bookworm.sh](mk-rootfs-bookworm.sh)从显示服务、编解码、Camera、NPU到WiFi/BT、音频、中文本地化,每一步都有对应的官方适配指南章节和验证方法。同时附上完整验证清单、常见问题排坑指南和经验总结,帮你避开适配路上最常踩的那些坑。无论你用的是RK3568、RK3576还是RK3588,这套方法论和脚本逻辑均可直接迁移,只需按芯片型号替换预编译包即可。
目录-下篇
5.核心实战:逐段拆解 [mk-rootfs-bookworm.sh](mk-rootfs-bookworm.sh)(RK3576 为例)
6.适配验证清单
7.常见问题排坑指南
8.经验总结
rs/media/platform/rockchip/isp
5、核心实战
逐段拆解[mk-rootfs-bookworm.sh](mk-rootfs-bookworm.sh)
完整脚本见SDK/debian/mk-rootfs-bookworm.sh。以下按脚本执行顺序,对照官方《第三方系统适配开发指南》的六个服务章节逐一讲解。
case "${ARCH:-$1}" in arm|arm32|armhf) ARCH=armhf ;; *) ARCH=arm64 ;;esacsudo tar -xpf linaro-bookworm-alip-*.tar.gzsudo cp -rpf packages/$ARCH/* binary/packages # RK 预编译包sudo cp -rpf overlay/* binary/ # 核心配置sudo cp -rpf overlay-firmware/* binary/ # 固件# VERSION=debug 时:sudo cp -rpf overlay-debug/* binary/ARCH变量贯穿整个适配流程—— 所有包、库、脚本都分 arm64/armhf 两套,先确认架构再动手。
sudo chroot $TARGET_ROOTFS_DIR
脚本在chroot内做了一批 "地基" 工作:
1.修正属主:把以普通用户 uid 解包产生的文件统一 chown 到 root,再把/home/
下的用户目录归位—— 否则系统起来后一堆文件属主错乱。
2.DNS 与软件源:写入8.8.8.8 / 127.0.0.53 / 114.114.114.114三个nameserver;追加中科大USTC镜像的bookworm-backports源,再apt-get update && upgrade。国内网络环境下这一步是构建成功的命脉。
3.串口免密登录(开发板刚需):
sed -i "s~\(^ExecStart=.*\)~# \1\nExecStart=-/bin/sh -c '/bin/bash -l /dev/%I 2>&1'~" \ /usr/lib/systemd/system/[email protected]
4.电源管理:安装pm-utils triggerhappy bsdmainutils,替换triggerhappy服务;logind.conf里HandlePowerKey=ignore,避免按电源键直接关机。
显示链路是"显示应用+图形显示框架+图形显示接口+GPU"四层结构:
显示应用 | 支持的框架 | 接口 |
x11 / xfce4 | xserver | OpenGL ES/GBM |
gnome / kde / sdl2 | xserver / wayland | OpenGL ES/GBM |
(1)GPU适配——选对libmali包
${APT_INSTALL} /packages/rga2/*.deb # RGA 2D 加速${APT_INSTALL} /packages/libmali/*.deb注意:脚本里/packages/libmali/*.deb 会把目录下所有型号的 libmali 装进去,实际产品适配时建议只装本机 GPU 型号对应的包,避免库冲突。RK3576 应只保留: |
(2)Xserver 适配
${APT_INSTALL} /packages/xserver/*.debapt-mark hold xserver-common xserver-xorg-core xserver-xorg-legacyxserver版本众多,官方提供的是编译好的1.20.11补丁版(对应源码external/xserver,可用git format-patch 导出补丁移植到你的版本)。apt-mark hold锁死这三个包—— 否则一次 apt upgrade 把 xserver 升回官方版本,硬件加速补丁就白打了。
(3)Wayland/Weston与libdrm
${APT_INSTALL} libseat-dev${APT_INSTALL} /packages/weston/*.deb /packages/wayland/*.deb${APT_INSTALL} /packages/libdrm/*.deb${APT_INSTALL} /packages/libdrm-cursor/*.deblibdrm-cursor是官方针对鼠标硬件光标层的用户态接口(把光标画在独立图层,避免每帧重绘)。X场景下还需要一个"注入"动作——见下方的DRI清理段内容,通过LD_PRELOAD让X进程强制加载libdrm-cursor。
(4)验证显示适配是否成功
# RK3588 官方示例(valhall-g610)cat /sys/devices/platform/fb000000.gpu/utilisation# RK3576(Mali-G52 @ 0x27800000)应查看:cat /sys/devices/platform/27800000.gpu/utilisation
渲染画面或拖动窗口时观察该值,GPU利用率有明显变化即表示OpenGL ES硬件加速生效(注意:不同平台的GPU节点路径不同)。若该节点没有负载变化,多半是libmali包选错或应用走的是软件渲染(llvmpipe)。
${APT_INSTALL} gstreamer1.0-plugins-bad/base/ugly gstreamer1.0-tools gstreamer1.0-alsa${APT_INSTALL} /packages/mpp/* # 硬件编解码中间层${APT_INSTALL} /packages/gst-rkmpp/*.deb # gstreamer → mpp 插件${APT_INSTALL} /packages/gstreamer/*.deb${APT_INSTALL} /packages/gst-plugins-base1.0/*.deb # gst-base 预编译包${APT_INSTALL} /packages/gst-plugins-bad1.0/*.deb${APT_INSTALL} /packages/gst-plugins-good1.0/*.deb架构是"多媒体框架(GStreamer)→MPP中间层→VPU硬件"。MPP的职责是给GStreamer这类通用软件提供访问硬件编解码器的统一接口。注意gst-plugins-*1.0装的是官方预编译包,如果和你的系统版本不兼容,需要按指南 "重新部署源码到目标机器编译":
cd 源码目录sudo apt build-dep .sudo DEB_BUILD_OPTIONS=nocheck dpkg-buildpackage -rfakeroot -b -d -us
验证编解码适配(rockchip-mpp-demos 提供测试工具):
# 编码:H.264 1080p 7 秒mpi_enc_test -w 1920 -h 1080 -t 7 -o /tmp/test.h264# 解码mpi_dec_test -w 1920 -h 1080 -t 7 -i /tmp/test.h264# GStreamer 硬解验证:日志中出现 mpp 调用字样 = 硬件解码成功sudo GST_DEBUG=2 gst-launch-1.0 playbin \ uri=/tmp/test.h264 video-sink="waylandsink" audio-sink=fakesink
还要注意设备节点权限——debian/overlay/etc/udev/rules.d/99-rockchip-permissions.rules里配置了/dev/vpu-*、/dev/rga等节点对linaro用户的访问权限,节点权限不对的时候,普通用户调用MPP会直接失败。
${APT_INSTALL} cheese v4l-utils${APT_INSTALL} /packages/libv4l/*.deb${APT_INSTALL} /packages/cheese/*.debcp -rf /packages/rkisp/*.deb / # ISP 处理库cp -rf /packages/rkaiq/*.deb / # 3A 算法库camera_engine_rkaiq是ISP 的用户态接口。
RK3576 必须选camera_engine_rkaiq_rk3576_arm64.deb(rpakage 目录按芯片细分,选错会加载失败)。
验证Camera适配(MIPI CSI 摄像头,RK3576 上为 IMX415):
v4l2-ctl -d /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=NV12 \ --stream-mmap=4 --stream-skip=3 --stream-to=/tmp/0.yuv \ --stream-count=1 --stream-poll
能抓出正确图像即适配成功。不同平台/不同摄像头节点、格式、分辨率不同,请按实际v4l2-ctl--list-devices结果调整。
if [ -e "/usr/lib/aarch64-linux-gnu" ]; then mv /packages/rknpu2/rknpu2.tar / # 仅 arm64 打入fi${APT_INSTALL} /packages/rktoolkit/*.debNPU适配分三件套(源码在SDK/external/rknpu2):
组件 | 内容 | 用途 |
rknn_runtime | librknnrt.so + librknn_api.so | 用户态运行库,拷贝进文件系统即可 |
rknn_server | rknn_server 服务 | 配合 PC 端 RKNN-Toolkit2 在板上通信调试用;模型在 PC 上转好 rknn 后导入板子则不需要 |
rknn demo | external/rknpu2/examples | 官方示例(如 rknn_yolov5_demo) |
RK3576的NPU是双核6TOPS,地址npu@27700000。适配完成后即可跑rknn_yolov5_demo做端侧推理——结合MIPI摄像头+HDMI显示的完整实战流程,可参考本公众号另一篇《RK3576+YOLOv5 端侧部署实战》。
${APT_INSTALL} /packages/rkwifibt/*.debln -s /system/etc/firmware /vendor/etc/Wi-Fi/BT模组因板而异(瑞芯微的rkwifibt体系),预编译包+固件(overlay-firmware)+服务脚本三件套。脚本最后还把固件目录统一挪到/usr/lib/firmware/rockchip/。
sed -i 's/^# *\(zh_CN.UTF-8\)/\1/' /etc/locale.genecho "LANG=zh_CN.UTF-8" >> /etc/default/localelocale-gen${APT_INSTALL} ttf-wqy-zenhei fonts-aenigma xfonts-intl-chinese${APT_INSTALL} ibus ibus-libpinyin${APT_INSTALL} pipewire pipewire-pulse pipewire-alsa libspa-0.2-bluetooth${APT_INSTALL} /packages/pipewire/*.deb /packages/wireplumber/*.debfind /usr/lib/systemd/ -name "wireplumber*.service" \ | xargs sed -i "/Environment/s/$/ DISPLAY=:0/"注意最后一行把DISPLAY=:0注入wireplumber 服务环境 ——Wayland/X11混合场景下音频服务找不到显示环境的老坑,官方用 sed 一行解决。
# ① 锁死全部已装包,防止 apt 后续升级破坏适配apt list --installed | grep -v oldstable | cut -d/ -f1 | xargs apt-mark hold# ② 屏蔽两个等待网络的 systemd 服务(开机卡 90 秒的元凶)systemctl mask systemd-networkd-wait-online.servicesystemctl mask NetworkManager-wait-online.service# ③ DRI 目录清理 + libdrm-cursor 注入(仅 arm64 分支)sed -i "1aexport LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libdrm-cursor.so.1" /usr/bin/Xcd /usr/lib/aarch64-linux-gnu/dri/cp kms_swrast_dri.so swrast_dri.so rockchip_dri.so /rm /usr/lib/aarch64-linux-gnu/dri/*.somv /*.so /usr/lib/aarch64-linux-gnu/dri/# ④ 固件瘦身(reduce 500M):只保留 rockchip 固件rm -rf /usr/lib/firmwaremkdir -p /usr/lib/firmware/mv /rockchip /usr/lib/firmware/
(1)apt-mark hold 是适配的 "保险丝":升级系统时若某个被适配的包被更新成上游版本,硬件加速会静默失效,而日志里毫无线索。锁死后才敢放心用apt upgrade。
(2)屏蔽 wait-online 服务
没有这步,无网线环境开机会在 "等待网络就绪" 上卡~90 秒,属于开发板必踩的坑。
(3)DRI 库替换+LD_PRELOAD:把官方验证过的三个DRI驱动
(含rockchip_dri.so)放回目录,并让 X 进程预加载libdrm-cursor实现硬件光标。最后清理apt lists、cache 与/packages/,出包。
6、适配验证流程
按指南结构,六大服务适配完成后建议逐项过一遍:
服务 | 验证命令 | 成功标志 |
显示(GPU) | cat /sys/devices/platform/27800000.gpu/utilisation | 渲染/拖窗时数值明显变化 |
RGA | ls /dev/rga* + linux-rga 源码 sample(im2d API) | 设备节点存在,旋转/缩放测试正确 |
编解码 | mpi_enc_test / mpi_dec_test | 正常出码/出帧 |
GStreamer | GST_DEBUG=2 gst-launch-1.0 playbin uri=... | 日志出现mpp调用 |
Camera | v4l2-ctl --stream-to=/tmp/0.yuv | 抓图成功且画面正确 |
NPU | rknn_yolov5_demo(external/rknpu2/examples) | 推理正常出框 |
WiFi/BT | nmcli dev wifi / bluetoothctl | 扫描到网络 / 设备 |
7、常见问题排坑指南
现象 | 原因 | 解法 |
界面卡顿、GPU 利用率不动 | libmali 包与 GPU 型号 / 显示框架不匹配 | 按芯片换libmali- |
apt upgrade后X起不来/白屏 | xserver 补丁被上游覆盖 | apt-mark hold xserver-common xserver-xorg-core xserver-xorg-legacy(脚本已处理) |
安装 blueman时服务自动启动失败 | 包安装钩子触发 blueman 服务 | 官方技巧:装包前echo exit 101 > /usr/sbin/policy-rc.d,装完删除 |
MPP 调用报权限错误 | 设备节点权限未配置 | 检查overlay/etc/udev/rules.d/99-rockchip-permissions.rules |
开机卡在 "等待网络" | wait-online 服务 | systemctl mask systemd-networkd-wait-online.service |
中文字体显示方块 | locale 未生成 | 启用zh_CN.UTF-8 后locale-gen |
预编译包与系统不兼容、安装失败 | 系统库版本依赖不满足 | 源码重编:apt build-dep . + dpkg-buildpackage -b -d -us |
抓图失败 | 摄像头节点 / 格式 / 分辨率不对 | 先v4l2-ctl --list-devices,按实际节点改命令 |
8、经验总结&参考文档
第三方系统适配的本质,是把 RK SoC 的 "硬件全家桶" 用一套用户态库 + 配置文件 + 防呆机制接到发行版生态上。掌握这条链路后,你会发现:
•换芯片(RK3568→RK3576 →RK3588)时,90%的改动集中在 "选对包",libmali的GPU型号、rkaiq的芯片型号;
•换系统(Debian→Ubuntu→其他发行版)时,重点在 "重编包",GStreamer、xserver 等按你的系统版本重新编译;
•出问题时,先看验证清单定位是哪个服务层没通,再顺着external/ 源码排查。
参考文档
•《Rockchip第三方系统适配开发指南》(docs/cn/Linux/System/)
•debian/mk-rootfs-bookworm.sh、debian/mk-base-debian.sh、debian/mk-image.sh
•《Rockchip_Developer_Guide_MPP_CN.pdf》(MPP接口)
•《Rockchip_Developer_Guide_Linux_WIFI_BT_CN.pdf》(Wi-Fi/BT)
