RK3588 Linux SDK 编译、烧录与 MIPI 屏配置流程

本文档整理了在ubuntu系统中， RK3588 Linux SDK 在 Ubuntu 20.04 Docker 环境下的完整编译、烧录及 10.1 寸 MIPI 屏配置流程。

目录

• 关键路径参考
• [0. 整体流程](#0. 整体流程)
• [1. 准备 Docker 编译环境](#1. 准备 Docker 编译环境)
• [2. 解压 RK3588 Linux SDK](#2. 解压 RK3588 Linux SDK)
• [3. 启动 Docker 容器](#3. 启动 Docker 容器)
• [4. 同步 .repo 本地源码](#4. 同步 .repo 本地源码)
• [5. 处理 dl 离线包目录](#5. 处理 dl 离线包目录)
• [6. 配置板级 defconfig](#6. 配置板级 defconfig)
• [7. 根据屏幕型号选择 DTS](#7. 根据屏幕型号选择 DTS)
• [8. 编译生成 update.img](#8. 编译生成 update.img)
• [9. 进入 Maskrom / Loader 模式并烧录](#9. 进入 Maskrom / Loader 模式并烧录)
• [10. 串口调试](#10. 串口调试)
• [11. 系统启动验证](#11. 系统启动验证)
• [12. MIPI 屏显示验证](#12. MIPI 屏显示验证)
• [13. 背光检查](#13. 背光检查)
• [14. framebuffer 测试](#14. framebuffer 测试)
• [15. 为什么系统界面不像 Ubuntu？](#15. 为什么系统界面不像 Ubuntu？)
• [16. 最终成功路径总结](#16. 最终成功路径总结)
• [17. 其他问题和解决方案](#17. 其他问题和解决方案)
• [18. 参考链接](#18. 参考链接)
• [19. 结语](#19. 结语)

---

关键路径参考

项目	路径 / 名称
宿主机 SDK 路径	/home/nash/rk3588/rk3588_linux
Docker 镜像名	rk3588-ubuntu20.04
Docker 容器名	rk3588_build
容器内 SDK 路径	/workspace/rk3588_sdk
最终固件	/home/nash/rk3588/rk3588_linux/rockdev/update.img

---

0. 整体流程

整个过程可以分成 8 步：

1. 准备 Ubuntu 20.04 Docker 编译环境
2. 解压 RK3588 Linux SDK
3. 启动 Docker 容器并挂载 SDK
4. 执行 repo sync -l，同步本地 .repo 源码
5. 处理 Buildroot dl 离线包目录
6. 根据屏幕型号配置 DTS
7. 编译生成 update.img
8. 进入 Maskrom / Loader 模式并烧录

---

1. 准备 Docker 编译环境

由于宿主机 Ubuntu 版本较高，而 RK3588 厂商 SDK 对系统环境比较敏感，所以使用 Ubuntu 20.04 Docker 容器编译是比较稳妥的方式。

先创建 Dockerfile 目录：

mkdir -p ~/rk3588/docker/rk3588-ubuntu20
cd ~/rk3588/docker/rk3588-ubuntu20
vim Dockerfile

推荐 Dockerfile：

FROM ubuntu:20.04

ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=Asia/Shanghai

RUN apt-get update && apt-get install -y --no-install-recommends \
    sudo \
    build-essential \
    git \
    wget \
    curl \
    bc \
    bison \
    flex \
    libssl-dev \
    libgmp-dev \
    libmpfr-dev \
    libmpc-dev \
    device-tree-compiler \
    libncurses5-dev \
    u-boot-tools \
    python3 \
    python3-pip \
    python2 \
    python-is-python3 \
    rsync \
    gcc \
    g++ \
    make \
    liblz4-tool \
    expect \
    expect-dev \
    patchelf \
    chrpath \
    gawk \
    texinfo \
    diffstat \
    binfmt-support \
    qemu-user-static \
    live-build \
    fakeroot \
    bsdmainutils \
    unzip \
    file \
    cpio \
    locales \
    vim \
    nano \
    ca-certificates \
    time \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

RUN locale-gen en_US.UTF-8 || true

ENV LANG=en_US.UTF-8
ENV LANGUAGE=en_US:en
ENV LC_ALL=en_US.UTF-8

WORKDIR /workspace

CMD ["/bin/bash"]

注意： 之前 repo 包用 apt install repo 会失败，因为 Ubuntu 20.04 apt 源里不一定有这个包。SDK 里本身有 .repo/repo/repo，所以 Dockerfile 里不需要安装 repo。

构建镜像：

cd ~/rk3588/docker/rk3588-ubuntu20
docker build -t rk3588-ubuntu20.04 .

成功后会看到：

naming to docker.io/library/rk3588-ubuntu20.04

---

2. 解压 RK3588 Linux SDK

最终使用的 SDK 路径是：

/home/nash/rk3588/rk3588_linux

目录结构类似：

app
buildroot
build.sh
debian
device
dl
dl.tgz
docs
envsetup.sh
external
kernel
Makefile
prebuilts
rkbin
tools
u-boot
uefi

这说明它已经是 Rockchip Linux SDK 根目录。

如果从压缩包开始，可以类似这样：

cd ~/rk3588
tar -xzvf atk-rk3588_linux_release_v1.2_20250104.tgz

建议： 路径不要带空格、中文或移动硬盘路径，尽量使用 /home/nash/rk3588/rk3588_linux。

---

3. 启动 Docker 容器

第一次启动容器：

docker run -it \
  --name rk3588_build \
  --privileged \
  -v /home/nash/rk3588/rk3588_linux:/workspace/rk3588_sdk \
  rk3588-ubuntu20.04

进入容器后：

cd /workspace/rk3588_sdk

如果之后再次进入同一个容器，不要 再用 docker run，否则会报：

Conflict. The container name "/rk3588_build" is already in use

应该使用：

docker start -ai rk3588_build

如果容器已经在后台运行，则使用：

docker exec -it rk3588_build bash

---

4. 同步 .repo 本地源码

进入容器并执行：

cd /workspace/rk3588_sdk
.repo/repo/repo sync -l

成功输出：

Checking out: 100% (59/59), done
repo sync has finished successfully.

如果出现 Git 安全检查问题：

fatal: detected dubious ownership in repository

可以在容器里执行：

git config --global --add safe.directory '*'

然后重新同步：

.repo/repo/repo sync -l

---

5. 处理 dl 离线包目录

这是本次遇到的关键问题之一。

SDK 顶层有 /workspace/rk3588_sdk/dl，但是 Buildroot 的配置里：

BR2_DL_DIR="$(TOPDIR)/dl"

这里的 TOPDIR 对 Buildroot 来说是 /workspace/rk3588_sdk/buildroot，所以 Buildroot 实际下载目录是 /workspace/rk3588_sdk/buildroot/dl。

因此需要把 SDK 顶层的 dl/ 同步到 buildroot/dl/：

cd /workspace/rk3588_sdk
mkdir -p buildroot/dl
rsync -a dl/ buildroot/dl/

注意： 推荐使用 rsync -a dl/ buildroot/dl/，不要写成 cp -r dl buildroot/dl，否则容易出现 buildroot/dl/dl/... 这种错误嵌套。

之前遇到的 NotoSansSC.zip 下载失败，就是因为 Buildroot 没有在自己的 buildroot/dl/ 里找到离线包，才去网上下载，然后遇到 404/403。

可以验证：

ls -lh buildroot/dl/noto-sans-sc/NotoSansSC.zip

应该能看到类似：

48M NotoSansSC.zip

---

6. 配置板级 defconfig

先执行默认配置：

cd /workspace/rk3588_sdk
./build.sh alientek_rk3588_defconfig

成功后会写入 /workspace/rk3588_sdk/output/.config，日志里成功信息是：

configuration written to /workspace/rk3588_sdk/output/.config

---

7. 根据屏幕型号选择 DTS

这是 MIPI 屏能否正常显示的关键。

一开始使用的是 RK_KERNEL_DTS_NAME="rk3588-atk-devkit"，后来发现这个并不适合 MIPI 屏。

SDK 里有这些 RK3588 ATK 相关 DTS：

rk3588-atk-devkit.dts
rk3588-atk-non-mipi.dts
rk3588-atk-mipi-5p5_1080x1920.dts
rk3588-atk-mipi-5p5_720x1280.dts
rk3588-atk-mipi-10p1_800x1280.dts

本次屏幕是 10.1 寸 MIPI，800x1280 ，所以应该使用 rk3588-atk-mipi-10p1_800x1280，而不是 rk3588-atk-mipi-5p5_1080x1920。

修改 DTS 配置

在容器里执行：

cd /workspace/rk3588_sdk

把 defconfig 里的 DTS 名称替换成 10.1 寸屏对应的：

sed -i 's/RK_KERNEL_DTS_NAME="rk3588-atk-devkit"/RK_KERNEL_DTS_NAME="rk3588-atk-mipi-10p1_800x1280"/' \
  device/rockchip/.chips/rk3588/alientek_rk3588_defconfig \
  device/rockchip/.chip/alientek_rk3588_defconfig

如果之前已经改成了 5.5 寸屏，则执行：

sed -i 's/RK_KERNEL_DTS_NAME="rk3588-atk-mipi-5p5_1080x1920"/RK_KERNEL_DTS_NAME="rk3588-atk-mipi-10p1_800x1280"/' \
  device/rockchip/.chips/rk3588/alientek_rk3588_defconfig \
  device/rockchip/.chip/alientek_rk3588_defconfig

重新生成配置：

./build.sh alientek_rk3588_defconfig

确认生效：

grep -R "RK_KERNEL_DTS_NAME" -n \
  device/rockchip/.chips/rk3588/alientek_rk3588_defconfig \
  device/rockchip/.chip/alientek_rk3588_defconfig \
  output/.config

应该看到：

RK_KERNEL_DTS_NAME="rk3588-atk-mipi-10p1_800x1280"

---

8. 清理旧的 boot/resource/update 产物

修改 DTS 后，建议清理旧的 boot 和 update 产物，避免旧 DTB 被继续打包：

cd /workspace/rk3588_sdk

rm -f kernel/boot.img
rm -f kernel/resource.img
rm -f kernel/zboot.img
rm -f kernel/arch/arm64/boot/dts/rockchip/rk3588-atk-mipi-10p1_800x1280.dtb
rm -rf output/firmware
rm -rf output/update
rm -rf rockdev

然后重新编译：

./build.sh 2>&1 | tee build_mipi_10p1.log

确认打包的是正确 DTB：

grep -nE "RK_KERNEL_DTS|RK_KERNEL_DTB|resource.img|boot.img" build_mipi_10p1.log | tail -n 80

理想输出应包含：

RK_KERNEL_DTB=kernel/arch/arm64/boot/dts/rockchip/rk3588-atk-mipi-10p1_800x1280.dtb
RK_KERNEL_DTS=kernel/arch/arm64/boot/dts/rockchip/rk3588-atk-mipi-10p1_800x1280.dts
Image: resource.img (with rk3588-atk-mipi-10p1_800x1280.dtb ...)
Image: boot.img (with Image resource.img) is ready

---

9. 编译完整固件

如果前面配置没问题，完整编译命令就是：

cd /workspace/rk3588_sdk
./build.sh 2>&1 | tee build.log

编译过程中可能遇到几个依赖问题。

缺少 GMP

错误类似：

Your gmp headers are missing
Please install it:
sudo apt-get install libgmp-dev

解决：

apt-get update
apt-get install -y libgmp-dev libmpfr-dev libmpc-dev

如果 Dockerfile 已经按前面的版本写了，就不会再遇到。

缺少 /usr/bin/time

错误类似：

/usr/bin/time: No such file or directory

解决：

apt-get update
apt-get install -y time

如果 Dockerfile 已经加了 time，也不会再遇到。

---

10. 确认固件生成成功

编译成功后，会生成：

/workspace/rk3588_sdk/rockdev/update.img

在宿主机路径对应为：

/home/nash/rk3588/rk3588_linux/rockdev/update.img

检查：

ls -lhL rockdev/update.img
readlink -f rockdev/update.img

之前看到的是：

-rw-r--r-- 1 nash nash 1.5G rockdev/update.img
/home/nash/rk3588/rk3588_linux/output/update/Image/update.img

说明：

• rockdev/update.img 是软链接
• 真实文件在 output/update/Image/update.img

但是烧录时直接使用 rockdev/update.img 即可。

---

11. 修复宿主机文件权限

因为 Docker 容器里默认是 root 编译，生成文件可能属于 root：

-rw-r--r-- 1 root root ...

回到宿主机后执行：

sudo chown -R nash:nash ~/rk3588/rk3588_linux/output
sudo chown -R nash:nash ~/rk3588/rk3588_linux/rockdev
sudo chown -R nash:nash ~/rk3588/rk3588_linux/kernel/arch/arm64/boot/dts/rockchip

确认：

cd ~/rk3588/rk3588_linux
ls -lhL rockdev/update.img

应该变成：

-rw-r--r-- 1 nash nash ...

---

12. 烧录 update.img

烧录工具目录：

/home/nash/rk3588/Linux_Upgrade_Tool/Linux_Upgrade_Tool

里面有：

upgrade_tool
config.ini
Linux开发工具使用手册_v1.32.pdf

PDF 里说明 UF 命令用于升级 update.img 固件，并且在 Maskrom 和 Loader 状态下有效。

进入烧录工具目录：

cd ~/rk3588/Linux_Upgrade_Tool/Linux_Upgrade_Tool

如果 upgrade_tool 没执行权限：

chmod +x ./upgrade_tool

启动工具查看设备：

sudo ./upgrade_tool

如果没有进入烧录模式，会显示：

No found rockusb

此时需要让板子进入 Maskrom 或 Loader 模式。成功识别后，可看到：

DevNo=1 Vid=0x2207,Pid=0x350b,LocationID=121 Mode=Maskrom

说明设备已经进入 Maskrom。

烧录命令

退出交互工具后，直接执行：

sudo ./upgrade_tool uf /home/nash/rk3588/rk3588_linux/rockdev/update.img

成功输出：

Loading firmware...
Support Type:RK3588
Upgrade firmware ok.

这说明烧录完成。

---

13. 串口调试

USB 转串口设备在宿主机识别为 /dev/ttyACM0（不是 /dev/ttyUSB0）。

检查：

ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

打开串口：

sudo picocom -b 1500000 /dev/ttyACM0

退出 picocom：先按 Ctrl + A，然后按 Ctrl + X。

如果没有输出，可以试：

sudo picocom -b 115200 /dev/ttyACM0

RK3588 常用调试串口波特率是 1500000。

---

14. 系统启动验证

串口出现以下提示说明系统已经正常启动并进入 root shell：

root@ATK-DLRK3588:/#

基础检查：

uname -a
cat /etc/os-release
df -h
free -h
cat /proc/cpuinfo | head -40

之前确认当前系统是：

• Buildroot 2021.11
• Linux 5.10.160
• aarch64
• 16GB 内存
• rootfs 正常挂载
• userdata 正常挂载

---

15. MIPI 屏显示验证

对于 10.1 寸 800x1280 MIPI 屏，正确 DTS 应该是 rk3588-atk-mipi-10p1_800x1280。

启动后可以检查 DRM 状态：

for f in /sys/class/drm/card*-*/status; do
    echo "$f: $(cat $f)"
done

检查 DSI：

cat /sys/class/drm/card0-DSI-1/status
cat /sys/class/drm/card0-DSI-1/enabled
cat /sys/class/drm/card0-DSI-1/modes

如果配置正确，理想上应该看到：

connected
enabled
800x1280

查看 DRM summary：

mount -t debugfs debugfs /sys/kernel/debug 2>/dev/null
cat /sys/kernel/debug/dri/0/summary

之前错误 DTS 下看到的是：

Display mode: 1080x1920p54

换成 10.1 寸 DTS 后，应该变成类似：

Display mode: 800x1280

---

16. 背光检查

查看背光：

ls /sys/class/backlight

如果有 backlight，则检查：

cat /sys/class/backlight/backlight/max_brightness
cat /sys/class/backlight/backlight/brightness
cat /sys/class/backlight/backlight/bl_power

打开背光并设置最大亮度：

echo 0 > /sys/class/backlight/backlight/bl_power
echo 255 > /sys/class/backlight/backlight/brightness

---

17. framebuffer 测试

如果想验证显示链路，可以直接写 /dev/fb0。

对于 1080x1920 32bit：1080 × 1920 × 4 = 8294400 bytes

dd if=/dev/urandom of=/dev/fb0 bs=8294400 count=1

对于 800x1280 32bit 屏：800 × 1280 × 4 = 4096000 bytes

dd if=/dev/urandom of=/dev/fb0 bs=4096000 count=1

如果 DTS 匹配，屏幕应该出现花屏、噪点或明显变化。

之前 5.5 寸 DTS 配错时，虽然 DSI connected、DSI enabled、VOP active、fb0 active，但是写 fb0 屏幕没有变化。最终原因是屏幕实际型号是 10.1 寸 800x1280 ，而用了 5.5 寸 1080x1920 DTS。

---

18. 为什么系统界面不像 Ubuntu？

因为这次编译的是 Buildroot 2021.11，不是 Ubuntu Desktop。

系统结构大概是：

Linux kernel 5.10
+
Buildroot rootfs
+
BusyBox
+
Rockchip/ATK demo UI
+
Weston / Qt / systemui 类嵌入式界面

所以看起来像手机或平板触摸界面是正常的。

如果想要 Ubuntu 那种桌面，需要烧录或构建 Ubuntu/Debian Desktop rootfs，而不是当前 Buildroot rootfs。

---

19. 最终成功路径总结

最终正确流程应该是：

# 1. 进入容器
docker start -ai rk3588_build

# 2. 进入 SDK
cd /workspace/rk3588_sdk

# 3. 同步本地源码
.repo/repo/repo sync -l

# 4. 同步 dl 到 buildroot/dl
mkdir -p buildroot/dl
rsync -a dl/ buildroot/dl/

# 5. 配置 10.1 寸 MIPI 屏 DTS
sed -i 's/RK_KERNEL_DTS_NAME="rk3588-atk-devkit"/RK_KERNEL_DTS_NAME="rk3588-atk-mipi-10p1_800x1280"/' \
  device/rockchip/.chips/rk3588/alientek_rk3588_defconfig \
  device/rockchip/.chip/alientek_rk3588_defconfig

sed -i 's/RK_KERNEL_DTS_NAME="rk3588-atk-mipi-5p5_1080x1920"/RK_KERNEL_DTS_NAME="rk3588-atk-mipi-10p1_800x1280"/' \
  device/rockchip/.chips/rk3588/alientek_rk3588_defconfig \
  device/rockchip/.chip/alientek_rk3588_defconfig

# 6. 重新生成配置
./build.sh alientek_rk3588_defconfig

# 7. 确认 DTS
grep -R "RK_KERNEL_DTS_NAME" -n \
  device/rockchip/.chips/rk3588/alientek_rk3588_defconfig \
  device/rockchip/.chip/alientek_rk3588_defconfig \
  output/.config

# 8. 清理旧产物
rm -f kernel/boot.img
rm -f kernel/resource.img
rm -f kernel/zboot.img
rm -f kernel/arch/arm64/boot/dts/rockchip/rk3588-atk-mipi-10p1_800x1280.dtb
rm -rf output/firmware
rm -rf output/update
rm -rf rockdev

# 9. 重新编译
./build.sh 2>&1 | tee build_mipi_10p1.log

# 10. 确认打包 DTB
grep -nE "RK_KERNEL_DTS|RK_KERNEL_DTB|resource.img|boot.img" build_mipi_10p1.log | tail -n 80

宿主机烧录：

cd ~/rk3588/Linux_Upgrade_Tool/Linux_Upgrade_Tool

sudo ./upgrade_tool uf /home/nash/rk3588/rk3588_linux/rockdev/update.img

烧录成功后：

Upgrade firmware ok.

到这里，系统编译、烧录、10.1 寸 MIPI 屏显示就全部走通了。