Linux SDK 编译

本文档介绍 RK3588 Linux 6.1 SDK 的编译流程，包括获取 SDK、配置、编译完整镜像（U-Boot + Kernel + 根文件系统）和单独编译某个模块。

适用范围： 在 PC 上的 RK3588 Linux SDK 环境中完成完整镜像编译，最终通过系统烧录指南中的方式烧录到 C-3588LQ V1.0 + SHIMETAPI-M5-R2A V1.0 底板。 注意： SDK 编译只可在 PC 端执行；开发板上不涉及本章命令。

1. 概念基础

1.1 SDK 是什么

RK3588 Linux SDK 是 Rockchip 官方提供的完整软件开发套件，集成了：

U-Boot — 一级引导程序
Kernel 6.1 — Linux 内核
根文件系统 — Buildroot（小型嵌入式）或 Debian（桌面级）
多媒体栈 — MPP 编解码、RGA、gstreamer-rockchip 等
NPU 驱动与工具链 — rknpu2、rknn-toolkit2
板级配置 — BoardConfig、parameter 分区表

1.2 编译流程

Bootloader (U-Boot)  →  Kernel  →  Rootfs  →  分区镜像  →  update.img 统一固件
   build.sh uboot      build.sh kernel    build.sh rootfs/debian    mkfirmware.sh    build.sh updateimg

最终 ./build.sh all 会依次执行前 3 步（U-Boot、Kernel、Rootfs），./build.sh allsave 则在前 3 步之外再执行打包。

1.3 RK3588 vs RK3568 SDK 关键差异

差异点	RK3588	RK3568
内核	Linux 6.1	Linux 5.10
工具链	GCC 10.3-2021.07（AArch64）	GCC 6.3.1
Debian	11 (bullseye) / 12 (bookworm)	10 (buster)
显示控制器	`CONFIG_ROCKCHIP_VOP2=y`	`CONFIG_ROCKCHIP_VOP=y`
NPU	6 TOPS 内置	无

2. 准备工作

2.1 硬件清单

组件	型号/规格	数量	备注
主控板	C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板	1	用于烧录验证（可选）
调试串口线	USB 转 TTL（3.3V）	1	波特率 1500000（验证）
电源适配器	4V/5A DC	1
Micro SD 卡	16GB+ Class10	1	SD 卡启动时（可选）
USB 数据线	USB-A to USB-C	1	用于烧录（OTG 口 J6）

2.2 PC 软件要求

项目	最低配置	推荐配置
CPU	4 核	8 核及以上
内存	16GB	32GB+
磁盘空间	200GB SSD	500GB+ SSD（推荐 NVMe）
操作系统	Ubuntu 20.04	Ubuntu 22.04

2.3 烧录后启动输出预期

系统烧录好之后给开发板上电，串口终端应能看到 DDR 初始化和 U-Boot 启动日志，看到这些输出就说明前面流程没问题：

DDR 4.11 ...
LPDDR4/LPDDR4X/DDR4, xxxxMHz
channel 0: xxxxMB
channel 1: xxxxMB
...

3. 软件准备（PC 端）

3.1 安装依赖包

电脑端：

sudo apt update
sudo apt install -y \
    repo git ssh make gcc g++ cmake \
    libssl-dev liblz4-tool \
    expect patchelf chrpath gawk texinfo diffstat \
    binfmt-support qemu-user-static live-build \
    bison flex fakeroot unzip zip dos2unix \
    device-tree-compiler python3 python3-pip \
    ncurses-dev pyelftools pkg-config \
    gcc-multilib g++-multilib \
    lib32z1 lib32ncurses5 lib32stdc++6 \
    bc rsync file lzop liblz4-tool zstd gdisk mtd-utils

3.2 安装 Repo 工具

电脑端：

# 方法一：从 apt 安装
sudo apt install repo

# 方法二：手动安装（推荐）
mkdir -p ~/.local/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.local/bin/repo
chmod a+x ~/.local/bin/repo
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

3.3 配置 Git

电脑端：

git config --global user.name "your name"
git config --global user.email "your.email@example.com"

3.4 预编译工具链（SDK 内置）

用途	路径	版本
U-Boot / Kernel 编译 (64-bit)	`prebuilts/gcc/linux-x86/aarch64/`	GCC 10.3
Buildroot 编译	`buildroot/output/rockchip_rk3588/host/bin/aarch64-buildroot-linux-gnu-`	GCC 10.3

RK3588 使用 GCC 10.3 工具链（aarch64-none-linux-gnu），与 RK3568 的 GCC 6.3.1 有显著差异。

4. 获取 SDK

4.1 方案一：通过 repo 同步（需 Rockchip 权限）

电脑端：

repo init \
    -u https://github.com/rockchip-linux/manifests \
    -b rk3588_linux_release_v1.0.0.xml \
    -m rk3588_linux_release_v1.0.0.xml

repo sync -c -j4

repo sync 会下载约 50 GB 数据，耗时数小时。建议在公司内网或外网畅通的环境下进行。

4.2 方案二：解压官方发布包（推荐）

电脑端：

mkdir rk3588
tar xvf RK3588_LINUX_SDK_RELEASE_V1.0.0.tgz -C rk3588
cd rk3588
.repo/repo/repo sync -l
.repo/repo/repo sync -c --no-tags

4.3 方案三：国内镜像加速

电脑端：

repo init \
    -u https://mirrors.tuna.tsinghua.edu.cn/git/rockchip-sdk/manifests \
    -b rk3588_linux_release_v1.0.0.xml \
    -m rk3588_linux_release_v1.0.0.xml

repo sync -c -j4

5. SDK 目录结构

解压后的主要目录（已知，便于定位）：

<SDK>/
├── app/                  # 应用层代码（qcamera/qplayer/qsetting 等）
├── buildroot/            # Buildroot 根文件系统
├── debian/               # Debian 根文件系统构建脚本
├── device/rockchip/      # 板级配置（BoardConfig、parameter 分区表）
├── docs/                 # 官方文档
├── external/             # 外部组件（rknpu2、rknn-toolkit2、mpp、rga 等）
├── kernel/               # Linux 内核（6.1）
├── prebuilts/            # 预编译工具链
├── rkbin/                # Rockchip 二进制文件（ddr/trust/spl）
├── rockdev/              # 编译输出镜像目录
├── tools/                # 烧录与调试工具
├── u-boot/               # U-Boot
├── build.sh              # 主编译脚本
├── mkfirmware.sh         # 固件打包脚本
└── envsetup.sh           # 环境设置脚本

板级配置子目录：

device/rockchip/rk3588/
├── BoardConfig-rk3588-evb1-ddr4-v10.mk
├── BoardConfig-rk3588-evb1-lp4x-v10.mk
├── BoardConfig-rk3588-nvr.mk
└── ...

具体 BoardConfig 文件以实际 SDK 版本为准。shimetapi 开发板应选择与硬件匹配的 BoardConfig。

6. 完整编译（电脑端）

6.1 选择板级配置

电脑端：

cd <SDK_PATH>

# 加载指定 BoardConfig（推荐）
./build.sh device/rockchip/rk3588/BoardConfig-rk3588-evb1-ddr4-v10.mk

# 查看当前已加载的配置
./build.sh info

6.2 一键全编译

电脑端：

./build.sh all

依次执行：

编译 U-Boot
编译 Kernel
编译 Rootfs（默认为 Buildroot）

6.3 全编译 + 打包

电脑端：

./build.sh allsave

在 all 之上额外执行：

./mkfirmware.sh — 将编译产物复制到 rockdev/ 目录
生成 update.img 统一烧录固件
保存镜像和补丁

6.4 选择根文件系统类型

电脑端：

# Buildroot（默认）
export RK_ROOTFS_SYSTEM=buildroot
./build.sh

# Debian（12 bookworm 默认；可指定 11 bullseye）
export RK_ROOTFS_SYSTEM=debian
./build.sh

详细根文件系统构建参考 ch04-根文件系统构建。

7. 单独编译模块（电脑端）

7.1 编译 U-Boot

./build.sh uboot

产物：

u-boot/uboot.img — U-Boot 镜像
u-boot/trust.img — Trust（ATF/OP-TEE）镜像
rkbin/ — SPL + TPL 打包后的 Miniloader

7.2 编译 Kernel

./build.sh kernel

产物：

kernel/arch/arm64/boot/Image — 内核镜像
kernel/arch/arm64/boot/dts/rockchip/ — 设备树 .dtb 文件
内核模块（在 kernel/ 目录下）

7.3 单独编译内核模块

./build.sh modules

7.4 编译根文件系统

# Buildroot
./build.sh rootfs
# 输出: buildroot/output/rockchip_rk3588/images/rootfs.ext4

# Debian
./build.sh debian

Debian 构建分三步详解参见 ch04-根文件系统构建 §4.2。

7.5 Buildroot 包级别编译

source ./envsetup.sh rockchip_rk3588

make <package>             # 编译
make <package>-rebuild     # 重新编译
make <package>-reconfigure # 重新配置
make <package>-dirclean    # 完全清理

7.6 打包固件

# 1. 把分区镜像汇总到 rockdev/
./mkfirmware.sh

# 2. 生成 update.img 统一烧录固件
./build.sh updateimg

update.img 是包含所有分区的统一烧录文件，可直接被 RKDevTool 烧录。

7.7 查看帮助

./build.sh --help

8. 输出镜像

8.1 镜像清单

编译完成后所有镜像文件位于 rockdev/：

镜像文件	大小	分区	说明
`MiniLoaderAll.bin`	~1MB	loader	SPL+TPL，初始化 DDR
`parameter.txt`	~1KB	-	分区表描述
`uboot.img`	4MB	uboot	U-Boot 引导
`trust.img`	4MB	trust	ATF + OP-TEE 安全固件
`misc.img`	4MB	misc	启动模式（normal/recovery/loader）
`boot.img`	32MB	boot	内核 + 设备树（Kernel Image + DTB）
`recovery.img`	32MB	recovery	恢复系统
`rootfs.img`	6GB+	rootfs	根文件系统（ext4）
`oem.img`	128MB	oem	OEM 分区
`userdata.img`	剩余空间	userdata	用户数据
`update.img`	-	全分区	统一烧录固件

8.2 boot.img 生成逻辑

boot.img = kernel.img（内核镜像）+ resource.img（含 DTB）

电脑端：

# 生成 kernel.img
scripts/mkkrnlimg arch/arm64/boot/Image kernel.img

# 生成 dtb.img
scripts/mkimg --dtb rk3588-xxx.dtb

# 最终 boot.img 由 mkkrnlimg + mkimg 自动组装

9. 分区表说明

9.1 默认分区表

RK3588 默认使用 GPT 分区表，parameter.txt 定义大小和位置。

分区	说明
uboot	U-Boot 引导程序
misc	启动标识（normal/recovery/loader）
boot	内核镜像 + 设备树
recovery	恢复系统，OTA 升级用
backup	OTA 备份（AB 系统切换）
rootfs	根文件系统
oem	厂商应用、配置、资源
userdata	用户数据

9.2 修改分区表

电脑端： 编辑 device/rockchip/rk3588/parameter.txt，修改 CMDLINE: 行中的分区定义。修改后重新编译并烧录即可生效。

10. 故障排除（电脑端）

10.1 编译报错：缺少依赖包

现象： 提示 command not found 或缺少头文件。

解决方案：

sudo apt install -y repo git ssh make gcc g++ cmake \
    libssl-dev liblz4-tool expect patchelf chrpath gawk texinfo \
    diffstat binfmt-support qemu-user-static live-build \
    bison flex fakeroot unzip zip device-tree-compiler \
    python3 python3-pip ncurses-dev pyelftools pkg-config

10.2 repo sync 失败

现象： repo sync 中断，出现网络错误或超时。

解决方案：

# 重试（支持断点续传）
repo sync -c -j4

# 减少并发
repo sync -c -j1

# 使用国内镜像（见 §4.3）

10.3 编译 U-Boot 失败

现象： ./build.sh uboot 失败。

解决方案：

# 确认工具链路径
ls prebuilts/gcc/linux-x86/aarch64/

# 清理后重试
./build.sh cleanall
./build.sh uboot

10.4 编译后无法启动

现象： 烧录后系统无法启动，串口无输出。

解决方案：

确认 BoardConfig 与硬件匹配
完整编译打包：./build.sh allsave
通过 RKDevTool 重新烧录 update.img