快速开始 / TSENGCHEN BLOG

RK3xxx-SDK-Target-Switch-and-Config-Guide

08_QuickStart · 第 12 / 13 篇

RK3xxx SDK 目标切换与配置新增指南

本文说明 Rockchip RK3xxx Linux SDK 中产品配置、内核、设备树、U-Boot 与 Buildroot 的关系,以及切换或新增配置时的安全流程。

适用范围:含 .repo、顶层 build.sh、device/rockchip/.chips/ 与多个 kernel-* 检出目录的 RK3xxx Linux SDK。本文以 /home/user/SDK/rk3xxx 的脚本行为为例;操作前必须以当前 SDK 实际文件为准。

1. 路径约定与 RK3506 实例

下文所有路径都相对 SDK 根目录 <SDK>;本文实例中 <SDK> 为 /home/user/SDK/rk3xxx。不要把 kernel-* 目录名、output/.kernel 或旧构建日志当作当前选择的唯一依据。

用途RK3506 客户实例的相对路径
客户产品 defconfigdevice/rockchip/.chips/rk3506/rockchip_rk3506_customer_64m_evb1_defconfig
64MiB 产品基线device/rockchip/.chips/rk3506/rockchip_rk3506_64M_evb1_defconfig
客户内核检出kernel-6.1-rk3506-product-64m/
客户完整内核 defconfigkernel-6.1-rk3506-product-64m/arch/arm/configs/rk3506-customer_defconfig
AP6256 SDIO 片段kernel-6.1-rk3506-product-64m/arch/arm/configs/rk3506-customer-ap6256-sdio.config
SDK WiFi 片段kernel-6.1-rk3506-product-64m/arch/arm/configs/rk3506-wifibt.config
客户 UBIFS DTSkernel-6.1-rk3506-product-64m/arch/arm/boot/dts/rk3506g-evb1-v10-customer-ubifs.dts
DTB 编译列表kernel-6.1-rk3506-product-64m/arch/arm/boot/dts/Makefile
U-Boot fragmentu-boot/configs/rk3506_tb.config
客户 Buildroot defconfigbuildroot/configs/rockchip_rk3506_customer_64m_ubifs_defconfig
客户 Buildroot 输出目录buildroot/output/rockchip_rk3506_customer_64m_evb1/rockchip_rk3506_customer_64m_ubifs/
SPI NAND 分区表device/rockchip/.chips/rk3506/parameter-128M.txt

2. 配置层次

SDK 的构建目标由多层配置共同决定,不能只切换 kernel 软链接。

层次典型位置决定内容
产品 defconfigdevice/rockchip/.chips/<chip>/<product>_defconfig选择内核配置、DTS、U-Boot fragment、Buildroot 基础配置、Rootfs 类型、分区表等
SDK 解析配置output/.config产品 defconfig 加通用默认值后的实际构建输入;不应长期手工修改
内核源码选择kernel 软链接、output/.kernel当前实际参与构建的 kernel-* 目录
内核配置kernel/arch/<arch>/configs/RK_KERNEL_CFG 指定的 defconfig 与 RK_KERNEL_CFG_FRAGMENTS 指定的片段
设备树kernel/arch/<arch>/boot/dts/RK_KERNEL_DTS_NAME 指定的 DTB
U-Bootu-boot/configs/RK_UBOOT_CFG_FRAGMENTS 指定的板级 fragment
Buildrootbuildroot/configs/RK_BUILDROOT_BASE_CFG 对应的 rockchip_<base>_defconfig
分区表device/rockchip/.chips/<chip>/parameter*.txt各镜像分区位置和最大容量

产品 defconfig 是入口。内核、DTS、Rootfs 和 U-Boot 必须与同一个产品 defconfig 的选择保持匹配。

3. 构建前确认当前目标

在 SDK 根目录执行:

cd /home/user/SDK/rk3xxx
readlink -f device/rockchip/.chip output/defconfig kernel
cat output/.kernel

grep -E '^(RK_DEFCONFIG|RK_KERNEL_CFG|RK_KERNEL_CFG_FRAGMENTS|RK_KERNEL_DTS_NAME|RK_UBOOT_CFG_FRAGMENTS|RK_BUILDROOT_BASE_CFG|RK_PARAMETER)=' output/.config

确认以下事实后再构建:

  1. output/defconfig 是否是目标产品配置。
  2. kernel 是否指向目标内核检出目录。
  3. 产品引用的内核 defconfig 和 fragments 是否实际存在于该内核目录。
  4. DTS、U-Boot fragment、Buildroot defconfig、parameter 文件是否存在。

4. 切换产品 defconfig

使用 build.sh 切换,不要手工改 output/defconfig 或 .chip 软链接。

./build.sh <chip>:<product_defconfig>

例如:

./build.sh rk3506:rockchip_rk3506_customer_64m_evb1_defconfig

切换后重新检查 output/.config。该动作会持久更新 SDK 的当前产品选择。

5. 切换指定内核

先切换产品 defconfig,再选择内核。SDK 支持以下形式:

./build.sh kernel-<kernel-directory-suffix>

例如切换到目录 kernel-6.1-rk3506-product-64m:

./build.sh kernel-6.1-rk3506-product-64m

该命令会更新 kernel 软链接及 output/.kernel,随后构建所选内核。

不要只执行 ./build.sh kernel 来完成首次切换。SDK 会优先使用 output/.kernel 中记录的上一次内核版本,可能继续构建旧内核。

6. 新增客户产品 defconfig

推荐从最接近的已存在产品 defconfig 复制,不修改通用产品文件。

cd /home/user/SDK/rk3xxx
cp device/rockchip/.chips/rk3506/rockchip_rk3506_64M_evb1_defconfig \
  device/rockchip/.chips/rk3506/rockchip_rk3506_customer_64m_evb1_defconfig

在新文件中按产品需求修改选择项,例如:

RK_KERNEL_CFG="rk3506-customer_defconfig"
RK_KERNEL_CFG_FRAGMENTS="rk3506-customer-ap6256-sdio.config rk3506-wifibt.config"
RK_KERNEL_DTS_NAME="rk3506g-evb1-v10-customer-ubifs"
RK_UBOOT_CFG_FRAGMENTS="rk3506_tb"
RK_BUILDROOT_BASE_CFG="rk3506_customer_64m_ubifs"
RK_PARAMETER="parameter-128M.txt"

这些名称必须分别在内核、U-Boot、Buildroot 与 chip 配置目录中存在。不要把其他产品(例如 DSMC 产品)的 fragment 与不同内核检出目录混用。

7. 从客户内核 .config 新增内核配置

客户提供的完整 .config 可以作为客户内核 defconfig 的来源:

cp /path/to/customer.config \
  kernel-6.1-rk3506-product-64m/arch/arm/configs/rk3506-customer_defconfig

若产品增加了客户 .config 未包含、但硬件明确需要的功能,使用独立 fragment,不直接修改客户原始文件。例如 AP6256 使用 SDIO:

# rk3506-customer-ap6256-sdio.config
CONFIG_MMC=y
CONFIG_MMC_QUEUE_DEPTH=1
CONFIG_MMC_DW=y
CONFIG_MMC_DW_ROCKCHIP=y

在产品 defconfig 的 RK_KERNEL_CFG_FRAGMENTS 中引用该 fragment。这样可以保留客户原始 .config 的可追溯性,同时把产品硬件差异明确隔离。

每次新增 fragment 后,检查其符号是否在目标内核的 Kconfig 中存在,并执行:

./build.sh kernel-<target-kernel>

8. 新增客户 DTS

不要修改 SoC 公共 .dtsi,也不要为了一个客户改动直接修改通用板级 DTS。应从最接近的板级 DTS 复制出客户 DTS,仅修改硬件差异,并加入 DTB 构建列表。

cp kernel/arch/arm/boot/dts/rk3506g-evb1-v10.dts \
  kernel/arch/arm/boot/dts/rk3506g-evb1-v10-customer.dts

随后:

  1. 在客户 DTS 中只改板级节点,例如 /chosen/bootargs、GPIO、面板、触摸、外设状态。
  2. 在 kernel/arch/arm/boot/dts/Makefile 增加对应 .dtb。
  3. 在产品 defconfig 设置 RK_KERNEL_DTS_NAME,名称不带 .dts 或 .dtb 后缀。
  4. 编译内核并确认目标 DTB 已生成。

Rootfs 格式必须与 bootargs 和内核文件系统驱动一致。例如 rootfstype=ubifs 需要 UBI/UBIFS 支持和 UBIFS 根文件系统;root=/dev/ubiblock0_0 rootfstype=squashfs 需要 UBI block 与 SquashFS 支持。

9. 新增或切换 U-Boot 配置

产品 defconfig 用 RK_UBOOT_CFG_FRAGMENTS 选择 U-Boot fragment。

RK_UBOOT_CFG_FRAGMENTS="rk3506_tb"

新增 fragment 时:

  1. 从同 SoC、同启动介质的 fragment 复制。
  2. 只保留板级需求,例如启动方式、BOOTDELAY、存储和环境策略。
  3. 不因 Linux Rootfs 挂载失败而先改 U-Boot;先确认 kernel bootargs、根文件系统格式和内核驱动。
  4. 仅修改内核/DTS/Rootfs 时,不需要重新编译 U-Boot;完整 update.img 打包仍可能包含已有 U-Boot 镜像,刷写前须确认分区范围。

10. 新增 Buildroot 配置和裁剪 Rootfs

从最接近的 Buildroot defconfig 复制:

cp buildroot/configs/rockchip_rk3506_64M_defconfig \
  buildroot/configs/rockchip_rk3506_customer_64m_ubifs_defconfig

产品 defconfig 中设置:

RK_BUILDROOT_BASE_CFG="rk3506_customer_64m_ubifs"

删除软件包后,Buildroot 增量构建不会自动移除旧 target/ 文件。必须清理对应产品专用输出目录再重建:

make -C buildroot/output/<product>/<buildroot-config> clean
./build.sh rootfs

不要清理 dl/,不要删除其他产品的 Buildroot 输出目录。

根文件系统镜像必须小于 parameter 文件中 rootfs 分区大小。打包前检查:

stat -c '%s %n' output/buildroot/images/rootfs.*
grep 'CMDLINE:.*rootfs' device/rockchip/.chips/rk3506/parameter*.txt

11. RK3506 客户配置完整实例

以下实例展示“客户完整内核 .config + AP6256 WiFi + SPI NAND 64MiB Rootfs”的相对位置和操作顺序。它不替代对客户原理图、触摸型号、4G 模组型号和实际 Rootfs 格式的确认。

  1. 产品入口为 device/rockchip/.chips/rk3506/rockchip_rk3506_customer_64m_evb1_defconfig。
  2. 该文件引用 rk3506-customer_defconfig;对应完整配置文件在 kernel-6.1-rk3506-product-64m/arch/arm/configs/。
  3. 该文件通过 RK_KERNEL_CFG_FRAGMENTS 叠加 AP6256 SDIO 片段和 SDK WiFi 片段,不改写客户原始完整内核配置。
  4. 该文件通过 RK_KERNEL_DTS_NAME 选择客户 DTS;DTS 必须在同一内核目录的 arch/arm/boot/dts/Makefile 中列出 DTB。
  5. 该文件通过 RK_BUILDROOT_BASE_CFG 选择 buildroot/configs/rockchip_rk3506_customer_64m_ubifs_defconfig;其输出目录名称由产品 defconfig 和 Buildroot 配置共同组成。

从 SDK 根目录执行的完整命令如下:

cd /home/user/SDK/rk3xxx

# 先选择产品,避免沿用 DSMC 或其他产品的内核 fragments。
./build.sh rk3506:rockchip_rk3506_customer_64m_evb1_defconfig

# 明确选择内核检出,避免沿用 output/.kernel 的旧记录。
./build.sh kernel-6.1-rk3506-product-64m

# 若已删除 Buildroot 包,先清理本产品专用输出,再构建 Rootfs。
make -C buildroot/output/rockchip_rk3506_customer_64m_evb1/rockchip_rk3506_customer_64m_ubifs clean
./build.sh rootfs
./build.sh updateimg

构建前确认引用关系:

grep -E '^(RK_KERNEL_CFG|RK_KERNEL_CFG_FRAGMENTS|RK_KERNEL_DTS_NAME|RK_UBOOT_CFG_FRAGMENTS|RK_BUILDROOT_BASE_CFG|RK_PARAMETER)=' \
  device/rockchip/.chips/rk3506/rockchip_rk3506_customer_64m_evb1_defconfig

readlink -f kernel output/defconfig

12. 推荐构建顺序

配置切换完成后按以下顺序构建:

./build.sh <chip>:<product_defconfig>
./build.sh kernel-<target-kernel>
./build.sh rootfs
./build.sh updateimg

只改 DTS 或内核配置时,至少重建 kernel。只改 Buildroot 软件包时,至少 clean 对应 Buildroot 输出并重建 rootfs。仅在修改 U-Boot 或需要生成完整升级包时重建或打包相应镜像。

13. 常见错误

产品 defconfig 与内核目录不匹配

现象:

No configuration exists for this target on this architecture

原因:当前产品 defconfig 引用了目标内核目录不存在的 fragment。例如 DSMC 产品引用 rk3506-dsmc.config,但目标内核目录没有该文件。

处理:先重新选择正确产品 defconfig,再选择对应内核目录;不要复制缺失 fragment 作为临时修复。

WiFi 外部模块 modpost 缺少 SDIO 符号

现象:bcmdhd.ko 报 sdio_claim_host、sdio_register_driver 或 rockchip_wifi_power 未定义。

原因:产品启用了 AP6256,但内核关闭了 MMC/SDIO 或 Rockchip WiFi 支持。

处理:保留客户基础内核配置,使用产品专用 SDIO fragment,并叠加 SDK 的 WiFi fragment;重新编译内核后再构建 Rootfs。

Rootfs 超出分区大小

现象:

rootfs.img's size exceed parameter's rootfs partition size limit

原因:Rootfs 镜像大于 parameter 文件中 rootfs 分区,或关闭软件包后旧 target 文件仍存在。

处理:先确认镜像大小;关闭无关测试、调试、音频或蓝牙包后,对该产品专用 Buildroot 输出执行 make clean 并重建。未经产品确认不要通过缩小 userdata 来扩大 rootfs 分区。

14. 最小交付检查

git -C device/rockchip diff --check
git -C kernel-6.1-rk3506-product-64m diff --check
git -C buildroot diff --check

readlink -f output/defconfig kernel
grep -E '^(RK_KERNEL_CFG|RK_KERNEL_CFG_FRAGMENTS|RK_KERNEL_DTS_NAME|RK_UBOOT_CFG_FRAGMENTS|RK_BUILDROOT_BASE_CFG|RK_PARAMETER)=' output/.config

记录实际选择的产品 defconfig、内核目录、DTS、Rootfs 类型、分区表、构建命令和镜像大小。刷写 update.img 前确认其分区清单,避免覆盖未备份的 userdata 或客户 U-Boot。

08_QuickStart · 文档目录
上一篇RK3588_RK1828_Pcie_LLM_Quick_Start下一篇SDK-Git-Workflow