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 客户实例的相对路径 |
|---|---|
| 客户产品 defconfig | device/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/ |
| 客户完整内核 defconfig | kernel-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 DTS | kernel-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 fragment | u-boot/configs/rk3506_tb.config |
| 客户 Buildroot defconfig | buildroot/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 软链接。
| 层次 | 典型位置 | 决定内容 |
|---|---|---|
| 产品 defconfig | device/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-Boot | u-boot/configs/ | RK_UBOOT_CFG_FRAGMENTS 指定的板级 fragment |
| Buildroot | buildroot/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
确认以下事实后再构建:
output/defconfig是否是目标产品配置。kernel是否指向目标内核检出目录。- 产品引用的内核 defconfig 和 fragments 是否实际存在于该内核目录。
- 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
随后:
- 在客户 DTS 中只改板级节点,例如
/chosen/bootargs、GPIO、面板、触摸、外设状态。 - 在
kernel/arch/arm/boot/dts/Makefile增加对应.dtb。 - 在产品 defconfig 设置
RK_KERNEL_DTS_NAME,名称不带.dts或.dtb后缀。 - 编译内核并确认目标 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 时:
- 从同 SoC、同启动介质的 fragment 复制。
- 只保留板级需求,例如启动方式、
BOOTDELAY、存储和环境策略。 - 不因 Linux Rootfs 挂载失败而先改 U-Boot;先确认 kernel bootargs、根文件系统格式和内核驱动。
- 仅修改内核/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 格式的确认。
- 产品入口为
device/rockchip/.chips/rk3506/rockchip_rk3506_customer_64m_evb1_defconfig。 - 该文件引用
rk3506-customer_defconfig;对应完整配置文件在kernel-6.1-rk3506-product-64m/arch/arm/configs/。 - 该文件通过
RK_KERNEL_CFG_FRAGMENTS叠加 AP6256 SDIO 片段和 SDK WiFi 片段,不改写客户原始完整内核配置。 - 该文件通过
RK_KERNEL_DTS_NAME选择客户 DTS;DTS 必须在同一内核目录的arch/arm/boot/dts/Makefile中列出 DTB。 - 该文件通过
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。