Firefly ROC-RK3588-PC（RK3588S 芯片）固件编译教程编译 OpenEuler 和 Ubuntu

kikock2026-08-102025-08-10

文档信息

项目	内容
适配硬件	Firefly ROC-RK3588-PC（RK3588S 芯片）
SDK 版本	Firefly Linux 6.1 SDK（rk3588_linux6.1_release_20250513_v1.1.1e）
支持系统	Ubuntu 22.04 / OpenEuler 24.03 LTS / Debian 12 / Buildroot
编译宿主机	Ubuntu 20.04 x86_64（推荐官方环境）
官方 Wiki	Firefly Wiki - 编译 Linux 固件 (内核版本 6.1)
文档状态	融合官方 Wiki + 离线部署实战踩坑，已完整闭环

⚠️ 重要前置说明（离线部署原则）

GitHub 境外域名在内网环境无法访问，全程禁止在线拉取源码。
本文档离线章节全部采用纯离线部署方案：提前在外网设备下载所有资源后上传编译机，镜像内本地安装，不依赖任何外网连接。

第一章 SDK 获取

请联系销售（sales@t-firefly.com）获取 SDK 下载链接，并阅读下载链接的 readme 文档。

注意事项：

SDK 采用交叉编译，须在 X86_64 电脑上使用 SDK，不要将 SDK 下载到板子上
编译环境请使用 Ubuntu 20.04（真机或 Docker 容器），使用其他版本可能导致编译出错
不要在虚拟机共享文件夹以及非英文目录存放、解压 SDK
获取、编译 SDK 请全程使用普通用户，不允许也不需要使用 root 权限（除非需要 apt 安装软件）

离线环境补充：如果无法访问外网，请参考本文档第六章：离线环境特殊操作。

第二章 SDK 安装与初始化

本章描述离线场景下，将已下载好的 SDK 基础包和升级包解压安装到编译机的完整流程。

2.0 工作目录现状确认

编译机当前工作目录 /data/linux61_rk3588_work/ 的已有内容：

/data/linux61_rk3588_work/                              （drwxrwxr-x ubuntu:ubuntu）
├── base_source/                                        （drwxrwxr-x ubuntu:ubuntu）✅ SDK 基础包
│   ├── linux_sdk_tar/                                  （drwxrwxr-x ubuntu:ubuntu）
│   │   ├── rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split00   # 4.0GB
│   │   ├── rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split01   # 4.0GB
│   │   ├── rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split02   # 4.0GB
│   │   ├── rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split03   # 4.0GB
│   │   └── rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split04   # 1.8GB
│   ├── md5sum.txt                                      # 分卷 MD5 校验清单
│   └── sdk_tools.sh                                    # SDK 管理脚本（解压/校验/同步）
├── bundle_patch/                                       （drwxrwxr-x ubuntu:ubuntu）✅ SDK 升级包
│   └── *.tar.gz                                        # 升级差量包（可选）
└── rootfs_storage/                                     （drwxr-xr-x root:root）✅ 系统镜像包
    └── linux6.1/
        └── *.img / *.7z                                # Ubuntu / OpenEuler / Debian 根文件系统

目录权限说明：

base_source/、bundle_patch/ 属主为 ubuntu:ubuntu（普通用户可读写，正常）

rootfs_storage/ 属主为 root:root，如需普通用户写入，参考 2.4.3 权限修复

SDK 版本信息：

项目	内容
SDK 版本	`rk3588_linux6.1_release_20250513_v1.1.1e`
分卷数量	5 个（split00 ~ split04），共约 18.3 GB
管理脚本	`sdk_tools.sh`（支持 MD5 校验、解压、repo 同步）

2.1 解压 SDK 基础包

base_source/ 目录提供了 sdk_tools.sh 脚本统一管理 SDK 的校验、解压和同步操作，优先使用脚本，不要手动 cat 合并。

sdk_tools.sh 参数速查：

参数	功能
`--check_md5` / `-c`	校验所有分卷文件的 MD5 完整性
`--unpack` / `-x`	先 MD5 校验，通过后解压 SDK 到指定目录
`-C <目录>`	指定解压目标目录（`--unpack` 配合使用）
`--sync`	对已解压目录执行 repo sync -l 和 repo start
`--release` / `-p`	打包 SDK（开发用，量产无需）

2.1.1 MD5 完整性校验

cd /data/linux61_rk3588_work/base_source/

# 查看当前文件结构
ll
# 预期：md5sum.txt  sdk_tools.sh  linux_sdk_tar/（含 split00~split04）

# 执行 MD5 校验（自动读取 md5sum.txt，逐一校验 linux_sdk_tar/ 下各分卷）
./sdk_tools.sh --check_md5

校验成功输出示例：

Start checking MD5
linux_sdk_tar/rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split00: check MD5 success
linux_sdk_tar/rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split01: check MD5 success
linux_sdk_tar/rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split02: check MD5 success
linux_sdk_tar/rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split03: check MD5 success
linux_sdk_tar/rk3588_linux6.1_release_20250513_v1.1.1e.sdk.split04: check MD5 success

若有任意分卷显示 check MD5 error，说明文件传输损坏，需重新上传该分卷。

2.1.2 解压 SDK（脚本自动合并 + 解压）

cd /data/linux61_rk3588_work/base_source/

# --unpack：自动执行 MD5 校验 → 按 md5sum.txt 顺序合并分卷 → tar 解压到目标目录
# -C：指定解压目标目录（SDK 将解压到此目录下，生成 .repo/ 等内容）
./sdk_tools.sh --unpack -C /data/linux61_rk3588_work/

解压耗时说明：5 个分卷共 ~18.3 GB，解压约需 20～40 分钟，过程有文件名逐行输出，请耐心等待，勿中断。

解压成功后末行输出：

1 2	Uppack linux sdk success! 你可以查看firefly wiki，以获取SDK更多使用和开发信息:

2.1.3 确认 SDK 解压结果

# 查看工作目录，应新增 .repo/ 目录（SDK 核心仓库元数据）
ls -la /data/linux61_rk3588_work/

# 验证 .repo 结构完整（包含 manifests 和 repo 子目录）
ls /data/linux61_rk3588_work/.repo/
# 预期：manifests/  manifest.xml  repo/  project-objects/  projects/  等

注意：解压后 SDK 内容直接在 -C 指定的目录下（以 .repo/ 形式存在），不会创建 Firefly_Linux61_SDK/ 子目录。.repo/ 就是 SDK 的根。接下来需要用 repo sync -l 还原工作目录文件。

2.2 应用 SDK 升级补丁（bundle_patch）

如果 bundle_patch/ 目录为空或无需升级，可跳过本节。

2.2.1 确认补丁包内容

1	ls -lh /data/linux61_rk3588_work/bundle_patch/

2.2.2 解压并覆盖应用补丁

升级补丁为差量覆盖包，解压到 SDK 根目录即可（会覆盖对应文件）：

cd /data/linux61_rk3588_work/bundle_patch/

# 解压补丁到 SDK 目录（覆盖方式）
tar -xzf rk3588_linux6.1_*.tar.gz -C /data/linux61_rk3588_work/Firefly_Linux61_SDK/

# 或多个补丁包逐个应用（按版本从低到高顺序）
for f in $(ls *.tar.gz | sort); do
    echo "应用补丁: $f"
    tar -xzf "$f" -C /data/linux61_rk3588_work/Firefly_Linux61_SDK/
done

2.2.3 验证补丁应用后的 SDK 版本

cd /data/linux61_rk3588_work/Firefly_Linux61_SDK/

# 查看 SDK manifest 版本信息
cat .repo/manifests/default.xml | grep -i "revision\|name" | head -5
# 或查看版本文件（如果存在）
cat .repo/manifests/*.xml | grep "revision" | head -3

2.3 SDK 离线 repo 初始化（还原工作目录）

SDK 解压后只有 .repo/ 元数据目录，需要执行 repo sync -l 将源码文件还原到工作目录。

⚠️ 前置检查：repo 脚本依赖 Python
SDK 内置的 .repo/repo/repo 脚本使用 Python 执行，Ubuntu 20.04 自带 Python2，可直接运行；Ubuntu 22.04 默认无 python 命令，需先确认并安装 Python 2.7。

2.3.0 前置：检查宿主机 Python 环境

# 检查 python 命令是否存在
python --version 2>&1 || echo "❌ 无 python 命令"

# 检查 python2.7 是否存在
python2.7 --version 2>&1 || echo "❌ 无 python2.7"

# 检查 python3
python3 --version

检查结果	处理方式
`python --version` 输出 `Python 2.7.x`	✅ 直接执行方式一或方式二
`python2.7 --version` 输出正常，但无 `python` 软链	建软链后执行方式一或方式二，或直接用方式三
`python` 和 `python2.7` 均不存在	先执行 2.3.1 安装 Python 2.7

2.3.1 宿主机无 Python2.7 安装步骤

适用场景：Ubuntu 22.04 / 其他无 Python2 的宿主机。若已有 python2.7，跳过本节。

步骤 1：安装 Python 2.7

sudo apt update

# Ubuntu 20.04 / 22.04 官方仓库仍收录 python2.7
sudo apt install -y python2.7 python2.7-dev

# 验证安装
python2.7 --version
# 预期输出：Python 2.7.18

若 apt 找不到 python2.7（Ubuntu 24.04 等较新版本），需添加旧版源：

sudo apt install -y software-properties-common
echo "deb http://old-releases.ubuntu.com/ubuntu focal main universe" \
    | sudo tee /etc/apt/sources.list.d/focal.list
sudo apt update
sudo apt install -y python2.7 python2.7-dev

步骤 2：建立全局软链接（可选，方便直接调用 python）

# 检查是否已有 /usr/bin/python
ls -la /usr/bin/python 2>/dev/null || echo "不存在，可以安全创建"

# 创建软链接（使 python 命令指向 python2.7）
sudo ln -sf /usr/bin/python2.7 /usr/bin/python

# 验证
python --version
# 预期输出：Python 2.7.18

⚠️ 注意：若系统还有其他工具依赖 python3，创建此软链后可能影响 python 命令的默认行为。如不确定，跳过本步骤，直接使用下方方式三（指定完整路径 /usr/bin/python2.7）即可。

2.3.2 执行 repo 初始化

选择以下任一方式执行（三种方式等价，效果相同）：

方式一：显式指定 /usr/bin/python2.7（⭐ 无需配置软链，最稳妥，优先推荐）

cd /data/linux61_rk3588_work/

# 直接用 python2.7 完整路径调用 repo，完全绕过系统 python 命令是否存在的问题
/usr/bin/python2.7 .repo/repo/repo sync -l

/usr/bin/python2.7 .repo/repo/repo start firefly --all

推荐理由：不依赖系统 python 命令是否存在、是否指向正确版本，适用所有 Ubuntu 版本（20.04 / 22.04 / 24.04）。

方式二：使用 sdk_tools.sh --sync

⚠️ 重要限制：sdk_tools.sh --sync 不支持直接传入 Python 解释器路径。
脚本内部直接调用 .repo/repo/repo（其 shebang 为 #!/usr/bin/env python），Python 解释器由系统 python 命令决定，无法通过脚本参数指定 python2.7。

必须先确保 python 命令指向 python2.7，才能正常执行：

方式 2a：临时 PATH 覆盖（不修改系统，会话级生效）

cd /data/linux61_rk3588_work/base_source/

# 在当前 shell 会话中临时创建 python → python2.7 的 alias（不影响系统）
mkdir -p ~/bin
ln -sf /usr/bin/python2.7 ~/bin/python
export PATH="$HOME/bin:$PATH"

# 验证 python 命令已指向 2.7
python --version   # 应输出 Python 2.7.x

# 执行脚本
./sdk_tools.sh --sync -C /data/linux61_rk3588_work/

# 完成后清理临时 bin（可选）
rm ~/bin/python

方式 2b：建立全局软链接（永久，需 sudo）

# 建立 python → python2.7 软链（系统级，影响所有用户）
sudo ln -sf /usr/bin/python2.7 /usr/bin/python

# 验证
python --version   # 应输出 Python 2.7.x

# 执行脚本
cd /data/linux61_rk3588_work/base_source/
./sdk_tools.sh --sync -C /data/linux61_rk3588_work/

方式三：直接调用 repo（python 命令已正确配置时）

cd /data/linux61_rk3588_work/

# 离线同步（-l = local only，不访问外网）
.repo/repo/repo sync -l

# 创建并切换到 firefly 工作分支
.repo/repo/repo start firefly --all

要求宿主机 python 命令已指向 python2.7。

2.3.3 同步完成验证

# 工作目录还原后应出现 build.sh、kernel-6.1、u-boot 等目录
ls /data/linux61_rk3588_work/
# 预期：build.sh  device  kernel  kernel-6.1  u-boot  buildroot  prebuilts  .repo  ...

# 确认 build.sh 存在（SDK 核心编译入口）
ls -lh /data/linux61_rk3588_work/build.sh

常见 repo 初始化报错处理：

⚠️ 操作顺序必须正确：先 --unpack 解压，再 --sync 还原工作目录。跳过解压直接 sync 必然报错。

报错信息	根因	解决方法
`.repo/repo/repo: No such file or directory`	SDK 尚未解压，`.repo/` 目录不存在	先执行 `./sdk_tools.sh --unpack -C /data/linux61_rk3588_work/`，解压完成后再 `--sync`
`python: not found` / `No such file or directory`	系统无 `python` 命令	先执行 2.3.1 安装 Python2.7，或直接用方式一
`ModuleNotFoundError: No module named 'formatter'`	repo 脚本依赖 Python2 的 `formatter` 模块，Python3 中已移除	必须用 Python2.7 运行，不能用 python3
`error: repo is not installed.`	`.repo/repo/repo` 文件不存在	SDK 解压不完整，重新执行 `sdk_tools.sh --unpack`
`wrapper-version` 相关参数缺失	直接运行了 `main.py` 而非 repo 脚本	必须执行 `.repo/repo/repo`，不可直接跑 `main.py`

2.4 准备根文件系统（rootfs_storage）

将 rootfs_storage/ 中的根文件系统镜像注入 SDK 的 prebuilt_rootfs/ 目录。

2.4.1 确认 rootfs 镜像

1	ls -lh /data/linux61_rk3588_work/rootfs_storage/linux6.1/

预期文件示例：

1 2	-rw-r--r-- 1 root root 4.2G Ubuntu22.04-xxxxxxxx.7z -rw-r--r-- 1 root root 3.8G Openeuler24.03-xxxxxxxx.7z

2.4.2 解压并创建符号链接

Ubuntu rootfs：

cd /data/linux61_rk3588_work/rootfs_storage/linux6.1/

# 如果是 .7z 压缩格式，先解压
7z x Ubuntu22.04-*.7z

# 创建 prebuilt_rootfs 目录并建立符号链接
mkdir -p /data/linux61_rk3588_work/Firefly_Linux61_SDK/prebuilt_rootfs/
cp Ubuntu22.04-*.img /data/linux61_rk3588_work/Firefly_Linux61_SDK/prebuilt_rootfs/

cd /data/linux61_rk3588_work/Firefly_Linux61_SDK/prebuilt_rootfs/
ln -sf Ubuntu22.04-*.img rk3588_ubuntu_rootfs.img
ls -lh

OpenEuler rootfs：

cd /data/linux61_rk3588_work/rootfs_storage/linux6.1/

# 如果是 .7z 压缩格式，先解压
7z x Openeuler24.03-*.7z

# 拷贝并创建符号链接
cp Openeuler24.03-*.img /data/linux61_rk3588_work/Firefly_Linux61_SDK/prebuilt_rootfs/

cd /data/linux61_rk3588_work/Firefly_Linux61_SDK/prebuilt_rootfs/
ln -sf Openeuler24.03-*.img rk3588_openeuler_rootfs.img
ls -lh

2.4.3 rootfs_storage 权限修复（可选）

若 rootfs_storage/ 为 root:root 权限，普通用户无法读写：

1 2	# 修改为当前用户所有（替换 ubuntu 为实际用户名） sudo chown -R ubuntu:ubuntu /data/linux61_rk3588_work/rootfs_storage/

2.5 SDK 安装完成验证

所有步骤完成后，最终目录结构应如下：

/data/linux61_rk3588_work/              ← SDK 根目录（--unpack -C 指定的目标）
├── build.sh -> device/rockchip/...     # ✅ SDK 编译入口（repo sync -l 还原后出现）
├── kernel-6.1/                         # Linux 6.1 内核源码
├── u-boot/                             # U-Boot 源码
├── device/                             # 板级配置（defconfig 等）
├── prebuilt_rootfs/                    # ✅ rootfs 已注入
│   ├── rk3588_ubuntu_rootfs.img        # Ubuntu rootfs 符号链接
│   └── rk3588_openeuler_rootfs.img     # OpenEuler rootfs 符号链接
├── output/                             # 编译产物目录（编译后生成）
├── .repo/                              # repo 元数据（保留，勿删！）
│
├── base_source/                        # SDK 基础包（保留备份）
├── bundle_patch/                       # SDK 升级包（保留备份）
├── rootfs_storage/                     # rootfs 原始镜像（保留备份）
│   └── linux6.1/
└── output_img/                         # 最终固件归档（编译后使用）

执行快速检查命令：

# 检查 SDK 核心文件（repo sync -l 成功后才存在）
ls -lh /data/linux61_rk3588_work/build.sh

# 检查 prebuilt_rootfs 符号链接是否有效
ls -lh /data/linux61_rk3588_work/prebuilt_rootfs/

# 确认 repo 工作分支已创建
cd /data/linux61_rk3588_work/
.repo/repo/repo status 2>&1 | head -5

✅ 验证通过后，即可进入 第四章（编译 Ubuntu 固件） 或 第五章（编译 OpenEuler 固件） 开始编译。

2.6 SDK 清理操作

根据不同场景，提供三个级别的清理方案：

清理级别	场景	命令	保留内容
编译产物清理	切换系统配置、重新编译时	`./build.sh cleanall`	源码、.repo、rootfs
SDK 重新解压	解压出错、需要干净 SDK 时	`sdk_tools.sh --unpack`	base_source、rootfs_storage
完全清理重装	彻底重来	手动 `rm -rf` + 重新解压	base_source、rootfs_storage

2.6.1 清理编译产物（保留源码）

适用场景：切换编译配置（如从 Ubuntu 切换到 OpenEuler）、编译出错需重编、清理 output/ 节省磁盘。

cd /data/linux61_rk3588_work/

# 清理全部编译产物（output/ 目录内容、各分区 .img 等）
./build.sh cleanall

# 清理后验证 output/ 已清空
ls output/ 2>/dev/null || echo "output 目录不存在或已清空"

cleanall 不会删除源码（kernel-6.1、u-boot、device 等）和 .repo/，安全可重复执行。

分模块清理（可选）：

# 仅清理内核编译产物
./build.sh clean kernel

# 仅清理 uboot 编译产物
./build.sh clean uboot

2.6.2 重新解压 SDK（保留 .repo 前会先删除）

适用场景：--unpack 中途失败、怀疑解压不完整时，重新解压 SDK。

cd /data/linux61_rk3588_work/base_source/

# --unpack 内部会先执行 rm -rf $UPGRADE_PATH/.repo，然后重新解压
# 即：自动清理旧的 .repo/ 后重新解压，无需手动删除
./sdk_tools.sh --unpack -C /data/linux61_rk3588_work/

# 解压完成后，重新执行 repo sync 还原工作目录
./sdk_tools.sh --sync -C /data/linux61_rk3588_work/
# 或
/usr/bin/python2.7 .repo/repo/repo sync -l
/usr/bin/python2.7 .repo/repo/repo start firefly --all

⚠️ 重新解压会删除并重建 .repo/，工作目录中已有的源码修改（如自定义 patch）会丢失，请提前备份。

2.6.3 完全清理 SDK（彻底重装）

适用场景：SDK 损坏严重、磁盘空间回收、彻底从头开始。

# 查看当前 SDK 工作目录占用
du -sh /data/linux61_rk3588_work/
du -sh /data/linux61_rk3588_work/.repo/
du -sh /data/linux61_rk3588_work/output/ 2>/dev/null

# 删除 SDK 所有还原出来的工作文件（保留 base_source、bundle_patch、rootfs_storage）
cd /data/linux61_rk3588_work/
ls | grep -Ev "^(base_source|bundle_patch|rootfs_storage|output_img)$" | xargs rm -rf

# 验证只剩下需要保留的目录
ls /data/linux61_rk3588_work/
# 预期：base_source/  bundle_patch/  rootfs_storage/  output_img/

# 重新解压 + 初始化（参考 2.1 ~ 2.3 节）
cd /data/linux61_rk3588_work/base_source/
./sdk_tools.sh --unpack -C /data/linux61_rk3588_work/
./sdk_tools.sh --sync -C /data/linux61_rk3588_work/

2.6.4 仅清理 prebuilt_rootfs（切换根文件系统）

适用场景：从 Ubuntu 切换到 OpenEuler（或反向），需要替换 rootfs 镜像。

cd /data/linux61_rk3588_work/prebuilt_rootfs/

# 查看当前注入的 rootfs
ls -lh

# 备份旧镜像（可选）
mkdir -p bak_$(date +%Y%m%d)
mv *.img bak_$(date +%Y%m%d)/ 2>/dev/null || true

# 重新注入目标 rootfs（以 OpenEuler 为例）
cp /data/linux61_rk3588_work/rootfs_storage/linux6.1/Openeuler24.03-*.img .
ln -sf Openeuler24.03-*.img rk3588_openeuler_rootfs.img
ls -lh

第三章 SDK 配置介绍

3.1 目录介绍

$ tree -L 1
.
├── app
├── buildroot                                               # Buildroot 文件系统
├── build.sh -> device/rockchip/common/scripts/build.sh     # 编译脚本（统一入口）
├── device                                                  # 编译系统，内含编译配置文件
├── docs                                                    # 开发文档
├── external                                                # 一些组件
├── kernel -> kernel-6.1
├── kernel-6.1                                              # Linux 6.1 内核源码
├── Makefile -> device/rockchip/common/Makefile
├── prebuilt_rootfs                                         # 用于存放预编译好的根文件系统
├── prebuilts                                               # 用于存放交叉编译工具链
├── rkbin
├── rkflash.sh -> device/rockchip/common/scripts/rkflash.sh
├── tools                                                   # 工具，包含烧录工具等
└── u-boot                                                  # U-Boot 引导

3.2 配置文件介绍

在 device/rockchip/rk3588/ 目录下，有不同板型的配置文件（xxxx_defconfig），用于管理 SDK 每个环节的编译配置。

配置文件命名规则：

1	<vendor>_<chip>_<model>-<extra>_<OS>_defconfig

字段	说明
`vendor`	产品供应商
`chip`	产品所用芯片
`model`	产品型号
`extra`	额外属性（可为空）
`OS`	目标操作系统

配置文件内容示例（firefly_rk3588_itx-3588j_debian_defconfig）：

RK_KERNEL_DTS_NAME="rk3588-firefly-itx-3588j"                    # 指定编译内核所使用的设备树
RK_KERNEL_CFG_FRAGMENTS="firefly-linux.config"                   # 指定编译内核所使用的 config fragments
RK_UBOOT_CFG_FRAGMENTS="firefly-linux"                           # 指定编译 uboot 所使用的 config fragments
RK_USE_FIT_IMG=y
RK_BOOT_FIT_ITS_NAME="bootramdisk.its"
RK_PARAMETER="parameter-debian-fit.txt"                          # 指定固件分区表
RK_PRODUCT_MODEL="ITX-3588J"                                     # 产品名称/型号
PREBUILT_ROOTFS_IMG="prebuilt_rootfs/rk3588_debian_rootfs.img"   # 指定预编译文件系统路径
RK_MISC_RECOVERY=y
RK_RECOVERY_RAMDISK="rk3588-recovery-arm64.cpio.gz"
RK_RAMDISK_IMG="kernel/ramdisk.img"
USE_EXTBOOT=y                                                    # 使用 exlinux 风格的 boot.img
RK_EXTRA_PARTITION_NUM=1

ROC-RK3588S-PC 对应的配置文件：

defconfig 名称	目标系统
`firefly_rk3588_roc-rk3588s-pc_ubuntu_defconfig`	Ubuntu 22.04
`firefly_rk3588_roc-rk3588s-pc_debian_defconfig`	Debian 12
`firefly_rk3588_roc-rk3588s-pc-ext_ubuntu_defconfig`	Ubuntu 22.04（扩展版）
`firefly_rk3588_roc-rk3588s-pc-ext_debian_defconfig`	Debian 12（扩展版）

OpenEuler 说明：OpenEuler defconfig 文件名包含 openeuler 字样，从 SDK v1.1.1c 起已支持。

3.3 分区说明

parameter 文件中包含了固件的分区信息，例如 device/rockchip/rk3588/parameter-xxxxxx-fit.txt：

FIRMWARE_VER: 1.0
MACHINE_MODEL: RK3588
MACHINE_ID: 007
MANUFACTURER: RK3588
MAGIC: 0x5041524B
ATAG: 0x00200800
MACHINE: 0xffffffff
CHECK_MASK: 0x80
PWR_HLD: 0,0,A,0,1
TYPE: GPT
GROW_ALIGN: 0
CMDLINE: mtdparts=:0x00002000@0x00004000(uboot),0x00002000@0x00006000(misc),0x00040000@0x00008000(boot:bootable),0x00040000@0x00048000(recovery),0x00010000@0x00088000(backup),0x01c00000@0x00098000(rootfs),-@0x01c98000(userdata:grow)
uuid:rootfs=614e0000-0000-4b53-8000-1d28000054a9
uuid:boot=7A3F0000-0000-446A-8000-702F00006273

分区解读（以 uboot 为例）：

0x00002000@0x00004000(uboot) 中：

0x00004000 = uboot 分区起始位置
0x00002000 = uboot 分区大小（单位：块，每块 512 字节）

计算：0x00002000 = 8192 块 = 8192 × 512 / 1024 / 1024 = 4 MiB

分区名	镜像文件	说明
uboot	`uboot.img`	U-Boot 引导加载器
misc	`misc.img`	引导控制分区
boot	`boot.img` / `extboot.img`	内核 + 设备树
recovery	`recovery.img`	恢复分区
backup	—	备份分区
rootfs	`rootfs.img`	根文件系统（系统主体）
userdata	—	用户数据分区（自动扩展）

第三章编译 Ubuntu 固件

3.1 准备工作

安装编译依赖工具：

sudo apt update

sudo apt install repo git ssh make gcc libssl-dev liblz4-tool \
  expect g++ patchelf chrpath gawk texinfo chrpath diffstat binfmt-support \
  qemu-user-static live-build bison flex fakeroot cmake gcc-multilib g++-multilib \
  unzip device-tree-compiler ncurses-dev p7zip-full

下载并准备根文件系统：

下载 Ubuntu 根文件系统（64位，Kernel 6.1），请使用网盘中 kernel-6.1 目录下的文件系统。

# 解压
7z x Ubuntu22.04-xxxx.7z

# 移动并创建符号链接
mkdir -p ./SDK/prebuilt_rootfs/
mv Ubuntu22.04-xxxx.img ./SDK/prebuilt_rootfs/
cd ./SDK/prebuilt_rootfs/
ln -sf Ubuntu22.04-xxxx.img rk3588_ubuntu_rootfs.img
cd ..

3.2 编译前配置

执行 ./build.sh lunch 列出所有可用配置文件，选择带有 ubuntu 字样的配置文件：

1	./build.sh lunch

############### Rockchip Linux SDK ###############

Manifest: rk3588_linux6.1_release_20250114_v1.1.1c
...
Pick a defconfig:

 1. rockchip_defconfig
 2. firefly_rk3588_aio-3588jd4_buildroot_defconfig
 3. firefly_rk3588_aio-3588jd4_debian_defconfig
 4. firefly_rk3588_aio-3588jd4_ubuntu_defconfig
...
20. firefly_rk3588_roc-rk3588s-pc-ext_debian_defconfig
21. firefly_rk3588_roc-rk3588s-pc-ext_ubuntu_defconfig
22. firefly_rk3588_roc-rk3588s-pc_debian_defconfig
23. firefly_rk3588_roc-rk3588s-pc_ubuntu_defconfig    ← ROC-RK3588S-PC Ubuntu
...
Which would you like? [1]:

ROC-RK3588S-PC Ubuntu 对应选项：firefly_rk3588_roc-rk3588s-pc_ubuntu_defconfig（编号视实际 SDK 版本而定）

3.3 编译

3.3.1 完整编译

1	./build.sh all

编译完成后会生成完整固件：output/update/update.img

3.3.2 部分编译（调试加速）

自定义开发通常只涉及 kernel 和 uboot，完整编译一次后，后续修改可部分编译加速：

# 单独编译 U-Boot，生成 u-boot/uboot.img
./build.sh uboot

# 单独编译 kernel，生成 kernel/extboot.img
./build.sh extboot

# 将各部件打包成 update.img
./build.sh updateimg

第四章编译 OpenEuler 固件

4.1 准备工作

安装编译依赖工具：

sudo apt update

sudo apt install repo git ssh make gcc libssl-dev liblz4-tool \
  expect g++ patchelf chrpath gawk texinfo chrpath diffstat binfmt-support \
  qemu-user-static live-build bison flex fakeroot cmake gcc-multilib g++-multilib \
  unzip device-tree-compiler ncurses-dev p7zip-full

下载并准备 OpenEuler 根文件系统：

下载 OpenEuler 根文件系统（64位，Kernel 6.1），请使用网盘中 kernel-6.1 目录下的文件系统。

# 解压
7z x Openeuler24.03-xxxx.7z

# 移动并创建符号链接
mkdir -p ./SDK/prebuilt_rootfs/
mv Openeuler24.03-xxxx.img ./SDK/prebuilt_rootfs/
cd ./SDK/prebuilt_rootfs/
ln -sf Openeuler24.03-xxxx.img rk3588_openeuler_rootfs.img
cd ..

4.2 编译前配置

执行 ./build.sh lunch 列出所有可用配置文件，选择带有 openeuler 字样的配置文件：

1	./build.sh lunch

############### Rockchip Linux SDK ###############

Manifest: rk3588_linux6.1_release_20250114_v1.1.1c
...
Pick a defconfig:

 1. rockchip_defconfig
...
22. firefly_rk3588_roc-rk3588s-pc_debian_defconfig
23. firefly_rk3588_roc-rk3588s-pc_ubuntu_defconfig
...（openeuler 配置项，编号视 SDK 版本而定）
Which would you like? [1]:

历史版本兼容：早期 SDK（如 v1.4.0g）使用旧版命令切换配置：
1
2
3
# 旧版 SDK 切换方式（v1.4.0g 及更早）
cd /path/to/SDK
./build.sh firefly_rk3588s-pc_openeuler_defconfig

4.3 编译

4.3.1 完整编译

1	./build.sh all

编译完成后会生成完整固件：output/update/update.img

4.3.2 部分编译（调试加速）

# 单独编译 U-Boot，生成 u-boot/uboot.img
./build.sh uboot

# 单独编译 kernel，生成 kernel/extboot.img
./build.sh extboot

# 将各部件打包成 update.img
./build.sh updateimg

第五章编译 Debian / Buildroot 固件（参考）

5.1 编译 Debian 固件

5.1.1 准备工作

sudo apt update

sudo apt install repo git ssh make gcc libssl-dev liblz4-tool \
  expect g++ patchelf chrpath gawk texinfo chrpath diffstat binfmt-support \
  qemu-user-static live-build bison flex fakeroot cmake gcc-multilib g++-multilib \
  unzip device-tree-compiler ncurses-dev p7zip-full

下载 Debian 根文件系统（64位），使用网盘 kernel-6.1 目录下的文件系统：

# 解压
7z x debian12_xxxx_rootfs_xxxx.7z

# 移动并创建符号链接
mkdir -p ./SDK/prebuilt_rootfs/
mv debian12_xxxx_rootfs_xxxx.img ./SDK/prebuilt_rootfs/
cd ./SDK/prebuilt_rootfs/
ln -sf debian12_xxxx_rootfs_xxxx.img rk3588_debian_rootfs.img
cd ..

5.1.2 编译

# 选择 debian 配置
./build.sh lunch   # 选择带有 debian 字样的配置项

# 完整编译
./build.sh all

# 部分编译
./build.sh uboot       # 单独编译 U-Boot
./build.sh extboot     # 单独编译 kernel
./build.sh updateimg   # 打包

5.2 编译 Buildroot 固件

5.2.1 准备工作

sudo apt update

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

注意：Buildroot 不需要额外下载根文件系统，直接编译即可。

5.2.2 编译

# 选择 buildroot 配置
./build.sh lunch   # 选择带有 buildroot 字样的配置项

# 完整编译
./build.sh all

# 部分编译（注意：修改了 buildroot 本身需重新完整编译）
./build.sh uboot       # 单独编译 U-Boot
./build.sh extboot     # 单独编译 kernel
./build.sh updateimg   # 打包

第六章离线环境特殊操作

适用场景：内网隔离环境，无法访问外网（含 GitHub）时使用。

6.1 工作目录结构规划

编译机统一工作目录建议为 /data/linux61_rk3588_work/：

/data/linux61_rk3588_work/
├── base_source/              # SDK 基础分卷压缩包（上传后存放于此）
├── bundle_patch/             # SDK 升级补丁包（可选，版本升级用）
├── Firefly_Linux61_SDK/      # SDK 解压后的完整工作目录（核心）
│   ├── kernel-6.1/           # Linux 6.1 内核源码
│   ├── u-boot/               # U-Boot 源码
│   ├── device/               # 板级配置（defconfig、分区表等）
│   ├── prebuilt_rootfs/      # 外部根文件系统注入目录
│   ├── output/               # 各分区编译产物输出
│   └── build.sh              # SDK 统一编译入口脚本
├── rootfs_storage/           # 各 OS 根文件系统底包存放目录
│   └── linux6.1/             # Linux 6.1 对应的 rootfs 镜像
└── output_img/               # 最终量产固件归档目录

6.2 Ubuntu 22.04 编译环境 Python2 兼容修复

Ubuntu 22.04 原生无 Python2，而旧版 repo 工具及 RK SDK 编译脚本仅支持 Python2，必须预先配置兼容环境：

sudo apt update

# 1. 基础编译工具链
sudo apt install -y \
    build-essential git curl wget unzip tar \
    libssl-dev device-tree-compiler

# 2. 添加 Ubuntu Focal 旧版源，用于安装 Python 2.7
sudo apt install -y software-properties-common
echo "deb http://old-releases.ubuntu.com/ubuntu focal main universe" \
    | sudo tee /etc/apt/sources.list.d/focal.list
sudo apt update

# 3. 安装 Python 2.7 完整环境（解决 formatter 模块报错）
sudo apt install -y python2.7 python2.7-dev

# 4. 全局兼容软链接
sudo ln -s /usr/bin/python2.7 /usr/bin/python

# 5. repo 运行依赖
sudo apt install -y git-core

注意：使用官方推荐的 Ubuntu 20.04 环境无需此修复步骤。

6.3 SDK 离线初始化

进入 SDK 目录，强制使用 Python2.7 执行 repo 初始化（规避 Python3 报错）：

cd /data/linux61_rk3588_work/Firefly_Linux61_SDK

# 离线同步（-l 参数表示仅本地，不拉取远端）
/usr/bin/python2.7 .repo/repo/repo sync -l
/usr/bin/python2.7 .repo/repo/repo start firefly --all

常见报错修复：

报错信息	根因	修复方案
`python: No such file or directory`	Ubuntu 22.04 无 python 软链	`sudo ln -s /usr/bin/python2.7 /usr/bin/python`
`ModuleNotFoundError: formatter`	repo 仅兼容 Python 2	固定使用 `/usr/bin/python2.7` 执行 repo
`wrapper-version 参数缺失`	不可直接运行 repo main.py	必须执行 `.repo/repo/repo`，不可裸跑 `main.py`

6.4 离线注入 Linux-ops-box 运维工具箱（可选）

若需要将 Linux-ops-box 运维工具箱固化到 rootfs 中，提前在外网设备下载完整源码，上传至编译机：

# 工具箱目标路径
/data/Linux-ops-box/
├── install_system.sh    # 工具箱安装主脚本
├── system/              # 工具箱核心资源目录（必须完整，不可缺失）
└── ...

⚠️ 关键要求：system/ 目录必须完整保留，缺失则 install_system.sh 会尝试联网下载，内网环境必然失败。

挂载 rootfs 并固化工具箱

cd /data/linux61_rk3588_work/Firefly_Linux61_SDK
mkdir -p tmp_mnt

# 挂载根文件系统镜像
sudo mount -o loop prebuilt_rootfs/rk3588_openeuler_rootfs.img tmp_mnt

# 拷贝工具箱源码至镜像内
sudo rm -rf tmp_mnt/opt/Linux-ops-box
sudo cp -r /data/Linux-ops-box tmp_mnt/opt/
sudo chmod +x tmp_mnt/opt/Linux-ops-box/install_system.sh

# chroot 安装工具箱
# 注意：OpenEuler 极简镜像默认无 /usr/local/bin，需提前创建
sudo chroot tmp_mnt /bin/bash <<'EOT'
mkdir -p /usr/local/bin
cd /opt/Linux-ops-box
bash install_system.sh
EOT

# 校验安装结果
sudo ls -l tmp_mnt/usr/local/bin/ck_sysinit
sudo ls tmp_mnt/opt/ck_sysinit

# 安全卸载（必做）
sudo sync
sudo umount tmp_mnt

成功标志：输出出现 [本地源码检测] 发现 system/ 目录，表示离线安装成功，无外网请求。

第七章固件打包与烧录

7.1 打包最终固件

cd /path/to/SDK

# 方式一：完整编译后自动打包（推荐）
./build.sh all

# 方式二：手动打包
./build.sh updateimg

./build.sh updateimg 交互选择：

1 2	Rename the file? [N\|y] → 输入 n（回车） Make update.img? [N\|y] → 输入 y（回车）

编译成功标准输出：

MiniLoaderAll.bin  ... OK
uboot.img          ... OK
boot.img           ... OK
misc.img           ... OK
recovery.img       ... OK
rootfs.img         ... OK
CRC check          ... OK
MD5 hash           ... OK
update.img         ... DONE

⚠️ RK3588 铁律：rootfs 经过结构性修改（新增软件、改目录权限、安装工具）后，必须全量编译（./build.sh all），然后再打包。跳过全量编译直接打包，必卡开机 Firefly Logo 黑屏。

7.2 固件归档

# 归档至输出目录（可选）
cp output/update/update.img \
   /data/linux61_rk3588_work/output_img/ROC-RK3588S-PC_Ubuntu_v1.1.1c_$(date +%Y%m%d).img

ls -lh /data/linux61_rk3588_work/output_img/

7.3 烧录方式

使用 RKDevTool 或 Firefly 烧录工具：

开发板长按 MASKROM 按键后上电（或按 Reset 键）
PC 端 RKDevTool 识别到 MASKROM 设备
加载 .img 固件文件，一键烧录

第八章版本迭代快速更新规则

更新类型	操作流程
系统结构性修改（新增软件、改目录权限、安装新工具）	重新 chroot 安装 → 全量编译 `./build.sh all` → 打包 `./build.sh updateimg`
仅更新工具箱源码（无系统结构变化）	重新 chroot 安装 → 直接 `./build.sh updateimg` 快速打包
仅修改内核配置	`./build.sh extboot` → `./build.sh updateimg`
仅修改 U-Boot	`./build.sh uboot` → `./build.sh updateimg`
Buildroot 修改	必须重新 `./build.sh all` 完整编译

第九章常见问题排查

9.1 全流程报错汇总

报错现象	根因	修复方案
`python: No such file or directory`	Ubuntu 22.04 无 python 软链接	`sudo ln -s /usr/bin/python2.7 /usr/bin/python`
`ModuleNotFoundError: formatter`	repo 仅兼容 Python 2	使用 `/usr/bin/python2.7` 执行 repo 命令
`ck_sysinit 软链接创建失败`	镜像内无 `/usr/local/bin` 目录	chroot 内提前 `mkdir -p /usr/local/bin`
`install_system.sh 尝试联网`	`system/` 目录缺失	确保上传完整 Linux-ops-box（含 `system/` 子目录）
`打包缺少 MiniLoaderAll.bin`	未全量编译，分区文件缺失	执行 `./build.sh all` 完整编译后再打包
`开机卡 Firefly Logo 黑屏`	rootfs 修改后未全量编译，分区不匹配	重新全量编译 → 重新打包
`桌面图标卡死无响应`	Xfce 缓存损坏（OpenEuler Xfce 已知 BUG）	见下方 9.2 节修复方案

9.2 OpenEuler Xfce 桌面图标卡死修复

临时一键修复

sudo killall -9 xfce4-panel xfdesktop xfce4-screensaver
rm -rf ~/.cache/xfce4/
rm -rf ~/.cache/icon-cache*
xfdesktop --reload
xfce4-panel -r

永久固化（写入 rootfs 开机自启）

在 rootfs 挂载后的 chroot 环境内执行：

# 写入开机自启修复脚本
sudo tee tmp_mnt/etc/xdg/autostart/fix-xfce-cache.desktop > /dev/null <<'EOF'
[Desktop Entry]
Type=Application
Name=Fix Xfce Cache
Exec=/usr/local/bin/fix-xfce-cache.sh
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
EOF

sudo tee tmp_mnt/usr/local/bin/fix-xfce-cache.sh > /dev/null <<'EOF'
#!/bin/bash
# 开机自动修复 Xfce 桌面缓存，防止图标卡死
sleep 5
rm -rf ~/.cache/xfce4/ ~/.cache/icon-cache* 2>/dev/null
pkill -9 xfce4-panel xfdesktop xfce4-screensaver 2>/dev/null || true
sleep 2
xfdesktop --reload &
xfce4-panel -r &
EOF

sudo chmod +x tmp_mnt/usr/local/bin/fix-xfce-cache.sh

# 安全卸载
sudo sync
sudo umount tmp_mnt

写入完成后需重新全量编译 + 打包，使修改生效。

附录：快速操作速查

🚀 标准编译完整流程（首次或结构性修改）

① 安装依赖
   └─ sudo apt install repo git ssh make gcc ... p7zip-full

② 准备根文件系统
   └─ 7z x <rootfs>.7z
   └─ mv <rootfs>.img SDK/prebuilt_rootfs/
   └─ ln -sf <rootfs>.img rk3588_ubuntu_rootfs.img（或 openeuler_rootfs.img）

③ 选择板卡配置
   └─ ./build.sh lunch → 选择对应 defconfig 编号

④ 全量编译
   └─ ./build.sh all  （耗时 40~60 分钟）

⑤ 打包固件
   └─ 已在 ./build.sh all 中自动完成，产物在 output/update/update.img
   └─ 或手动：./build.sh updateimg

⑥ 烧录验证
   └─ RKDevTool 选择 img → MASKROM 模式上电 → 一键烧录

⚡ 快速更新流程（仅改内核/uboot）

① 修改内核或 U-Boot 代码

② 部分编译
   └─ ./build.sh extboot   （仅内核）
   └─ ./build.sh uboot     （仅 U-Boot）

③ 重新打包
   └─ ./build.sh updateimg

④ 烧录验证

🔑 关键命令速记

操作	命令
列出可用配置	`./build.sh lunch`
完整编译	`./build.sh all`
仅编内核	`./build.sh extboot`
仅编 uboot	`./build.sh uboot`
打包固件	`./build.sh updateimg`
清理全部	`./build.sh cleanall`
查看分区表	`./build.sh print-parts`（旧版）/ 查看 parameter 文件
挂载镜像	`sudo mount -o loop <img> tmp_mnt`
卸载镜像	`sudo sync && sudo umount tmp_mnt`

⚠️ 铁律勿忘

#	规则
1	rootfs 结构性修改后，必须全量编译（`./build.sh all`），否则必卡 Logo
2	`system/` 目录缺失，`install_system.sh` 会联网（内网必失败）
3	OpenEuler 镜像内默认无 `/usr/local/bin`，chroot 前须 `mkdir -p`
4	离线环境 `repo sync` 必须加 `-l` 参数（本地模式）
5	卸载镜像前必须 `sync`，防止数据未写入导致镜像损坏
6	SDK 编译必须在 x86_64 宿主机上进行，不能在板子上编译
7	编译全程使用普通用户，不用 root（apt 安装除外）

文档版本：2026-06-15 | 官方参考：Firefly Wiki - 编译 Linux 固件 (内核版本 6.1)