Linux SDK 编译

1. 概述

1.1 功能简介

RK3576 Linux SDK 是 Rockchip 官方提供的完整软件开发套件，支持 Buildroot 和 Debian 两种根文件系统方案。SDK 集成了 U-Boot、Kernel 6.1、根文件系统以及丰富的multimedia/图形栈/NPU 驱动，为基于 RK3576 的嵌入式 Linux 产品开发提供一站式编译环境。

1.2 应用场景

• 产品原型开发：基于 SDK 快速搭建完整的系统镜像，验证硬件功能
• 模块化编译：单独编译 U-Boot、Kernel、Rootfs 等模块，加速开发迭代
• 量产固件生成：通过 SDK 编译生成最终量产固件 update.img
• 根文件系统选型：根据产品需求选择 Buildroot（小型/嵌入式）或 Debian（桌面/通用）

1.3 工作原理

SDK 编译流程分为三个主要阶段：Bootloader（U-Boot）→ Kernel → Rootfs（根文件系统），最终通过 mkfirmware.sh 打包生成分区镜像和 update.img 统一固件。

原理类内容优先引用 RK 官方文档，此处仅做要点提炼。 详见 RK 官方文档（S-07）：[《Rockchip_Developer_Guide_Linux_Software_CN.pdf》] SDK 获取方式见 资料下载，以实际发布的 RK3576 SDK 为准。

---

2. 硬件准备

2.1 硬件清单

组件	型号/规格	数量	备注
主控板	C-3576BQ 核心板 + M4-R2 底板	1	已烧录 Linux 系统
调试串口线	USB 转 TTL（3.3V）	1	波特率 1500000
电源适配器	5V 电源适配器（Type-C 或 6pin 输入）	1	空载最小 1000mA
Micro SD 卡	16GB+ Class10	1	用于 SD 卡启动（可选）
USB 数据线	USB-A to USB-C	1	用于烧录（Type-C 本地升级口）

2.2 硬件连接

1. 连接调试串口线到主控板的调试串口引脚（4pin/1.0mm，3.3V，波特率 1500000）
2. 串口线 USB 端插入电脑，使用 PuTTY/minicom 连接
3. 连接 5V 电源适配器（Type-C 或 6pin 二选一供电）

⚠️ 调试串口网络名：规格书（S-01）标注为 UART2（RX2/TX2），底板原理图（S-04）中为 UART0_TX_M0_DEBUG（GPIO0_D4_D）/UART0_RX_M0_DEBUG（GPIO0_D5_D），两者命名不一致，具体以实际物料与 SDK 配置为准（待板上验证）。

2.3 硬件确认

连接串口后上电，应能在串口终端看到 Rockchip 启动日志输出：

DDR 4.11 ...
LPDDR5, xxxxMHz
channel 0: xxxxMB
channel 1: xxxxMB
...

---

3. 软件准备

3.1 开发环境要求

SDK 编译需要在 Linux 环境下进行，推荐使用 Ubuntu 20.04 LTS 或 22.04 LTS（64 位）。开发电脑最低配置要求：

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

3.2 安装依赖包

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.3 安装 Repo 工具

SDK 使用 Google Repo 工具管理多个 Git 仓库：

# 方法一：从 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.4 配置 Git

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

3.5 预编译工具链

SDK 内置了预编译工具链，无需单独安装：

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

以上工具链路径与版本以实际发布的 RK3576 SDK 为准。

---

4. 操作步骤

4.1 获取 SDK

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

# 以实际发布的 RK3576 Linux 发布清单为准（示例：rk3576_linux_release_v1.0.0.xml）
repo init \
    -u https://github.com/rockchip-linux/manifests \
    -b rk3576_linux_release_v1.0.0.xml \
    -m rk3576_linux_release_v1.0.0.xml

repo sync -c -j4

注意：repo sync 会下载大量数据（约 50 GB），耗时数小时。建议在网络条件良好的环境下进行。

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

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

方案三：国内镜像加速

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

repo sync -c -j4

SDK 获取方法见 SDK下载与编译环境搭建，发布清单名称与镜像地址以实际发布为准。

4.2 SDK 目录结构

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           # 环境设置脚本

4.3 选择板级配置

SDK 为不同的 RK3576 硬件配置提供了多个 BoardConfig 文件：

device/rockchip/rk3576/
├── BoardConfig-rk3576-xxx.mk
├── BoardConfig-rk3576-evb1-lp4x-v10.mk
└── ...

具体 BoardConfig 文件以实际 SDK 版本为准，文件名为示例。M4-R2 开发板应选择与硬件匹配的配置（RK3576 + LPDDR5）。

选择配置后，可以通过以下方式加载：

# 方式一：直接指定 BoardConfig（推荐）
./build.sh device/rockchip/rk3576/BoardConfig-rk3576-xxx.mk

# 方式二：查看当前配置
./build.sh info

4.4 完整编译

一键全编译

./build.sh all

该命令依次执行以下步骤：

1. 编译 U-Boot
2. 编译 Kernel
3. 编译 Rootfs（默认为 Buildroot）

全编译 + 打包

./build.sh allsave

该命令在执行 all 的基础上，还会执行：

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

选择根文件系统类型

通过环境变量 RK_ROOTFS_SYSTEM 选择根文件系统：

# 编译 Buildroot 系统（默认）
export RK_ROOTFS_SYSTEM=buildroot
./build.sh

# 编译 Debian 系统
export RK_ROOTFS_SYSTEM=debian
./build.sh

4.5 单独编译模块

编译 U-Boot

./build.sh uboot

编译产物：

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

编译 Kernel

./build.sh kernel

编译产物：

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

单独编译内核模块

./build.sh modules

编译 Buildroot 根文件系统

./build.sh rootfs

输出文件：buildroot/output/rockchip_rk3576/images/rootfs.ext4

编译 Debian 根文件系统

./build.sh debian

Debian 的构建分为三步，也可手动执行：

cd debian/

# 1. 构建基础 Debian 系统
sudo apt-get install binfmt-support qemu-user-static live-build
sudo dpkg -i ubuntu-build-service/packages/*
sudo apt-get install -f
RELEASE=bullseye TARGET=desktop ARCH=arm64 ./mk-base-debian.sh

# 2. 构建 RK 定制 Debian 根文件系统
VERSION=debug ARCH=arm64 ./mk-rootfs-bullseye.sh

# 3. 创建 ext4 镜像
./mk-image.sh

以上路径与 Debian 版本（如 bullseye）以实际发布的 RK3576 SDK 为准。

4.6 单独编译软件包（Buildroot）

Buildroot 环境下，可以单独编译某个软件包：

# 进入 Buildroot 环境
source ./envsetup.sh rockchip_rk3576

# 编译指定包
make <package>

# 重新编译指定包
make <package>-rebuild

# 完全重新配置并编译
make <package>-reconfigure

# 清理指定包
make <package>-dirclean

4.7 打包固件

# 1. 打包所有分区镜像到 rockdev/
./mkfirmware.sh

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

update.img 是包含所有分区的统一固件文件，用于烧录工具直接烧录。

4.8 编译帮助

./build.sh --help

---

5. 输出镜像说明

5.1 镜像清单

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

镜像文件	分区	说明
MiniLoaderAll.bin	loader	一级启动加载器（SPL+TPL），初始化 DDR
parameter.txt	-	分区表描述文件
uboot.img	uboot	U-Boot 引导程序
trust.img	trust	ATF + OP-TEE 安全固件
misc.img	misc	启动模式标识（normal/recovery/loader）
boot.img	boot	内核 + 设备树（Kernel Image + DTB）
recovery.img	recovery	恢复系统镜像
rootfs.img	rootfs	根文件系统（ext4）
oem.img	oem	OEM 分区，存放厂商应用
userdata.img	剩余空间	用户数据分区
update.img	全分区	统一烧录固件（包含所有分区）

具体分区大小与镜像内容以实际 SDK 版本为准。

5.2 镜像生成逻辑

boot.img 由 kernel Image 和 DTB 组成：

# 生成 dtb.img（设备树）
scripts/mkimg --dtb rk3576-xxx.dtb

# 最终 boot.img 包含 kernel.img + resource.img

rootfs.img 为 ext4 格式的根文件系统镜像，包含完整的 Linux 用户空间。

---

6. 分区表说明

6.1 默认分区表

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

6.2 分区说明

分区	说明
uboot	存储 U-Boot 引导程序
misc	存储启动标识，用于控制进入 normal/recovery/loader 等模式
boot	包含 Linux 内核镜像（Image）和设备树（DTB）
recovery	独立的恢复系统，用于 OTA 升级和系统恢复
backup	OTA 升级时的备份分区，用于 AB 系统切换
rootfs	根文件系统，对应 Buildroot/Debian 的根文件系统镜像
oem	存储厂商特定的应用、配置和资源文件
userdata	用户数据分区

6.3 修改分区表

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

---

7. 常见问题

7.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

7.2 repo sync 失败

现象： repo sync 过程中断，出现网络错误

解决方案：

# 重新执行 sync（断点续传）
repo sync -c -j4

# 如果持续失败，尝试减少并行数
repo sync -c -j1

# 或使用国内镜像源

7.3 编译 U-Boot 失败

现象： ./build.sh uboot 编译失败

解决方案：

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

# 清理后重新编译
./build.sh cleanall
./build.sh uboot

7.4 编译后无法启动

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

解决方案：

1. 确认使用的 BoardConfig 与硬件匹配（RK3576、LPDDR5 配置）
2. 重新执行 ./build.sh allsave 完整编译打包
3. 使用 RKDevTool 重新烧录 update.img

---

相关文档

• SDK下载与编译环境搭建 — SDK 下载和环境搭建
• 内核配置与裁剪 — 内核配置详解
• 设备树详解与实践 — 设备树开发
• 根文件系统构建 — 根文件系统构建
• 核心板参数 — 硬件事实基线