4. RK3588设备树文件结构

RK3588作为瑞芯微旗舰级SoC，其设备树体系庞大且层级分明。理解设备树的文件组织方式，是进行驱动开发、外设适配和系统裁剪的基础。本章将深入剖析RK3588设备树的物理文件结构、逻辑继承关系、overlay动态加载机制以及从源码到二进制dtb的完整编译流程，帮助开发者建立从“看树”到“改树”再到“用树”的系统认知。

上图展示了RK3588设备树从SoC级到板级的完整组织架构与编译链路。下面我们将分层拆解每个环节的具体内容与操作要点。

4.1 设备树文件的三级组织模型

RK3588的设备树文件遵循“SoC通用 → 板级公共 → 板级具体”的三级继承模型。这种设计极大减少了重复代码，使得同一颗SoC可以快速适配多种硬件设计。

4.1.1 SoC级dtsi：芯片能力的完整描述

rk3588.dtsi 是RK3588芯片的“数据手册”设备树版本，由芯片原厂维护。它定义了所有内置控制器的默认状态、寄存器地址、中断号、时钟ID和电源域关系。该文件通常包含以下关键节点：

• CPU集群：4×Cortex-A76 + 4×Cortex-A55，包含核心频率、电压调节器关联、L2/L3缓存属性。
• 总线互联：包括AXI/ACE总线拓扑、NOC（Network on Chip）节点、QoS配置。
• 外设控制器：I2C、SPI、UART、SDMMC、Ethernet MAC、USB 2.0/3.0、PCIe 3.0/2.0、SATA等。
• 显示与多媒体：VOP（Video Output Processor）、DP、HDMI、MIPI DSI/CSI、GPU（Mali-G610）、VPU/JPEG编解码器。
• 系统控制：GIC（通用中断控制器）、定时器、看门狗、DMA控制器、PMU（电源管理单元）。

在 rk3588.dtsi 中，大部分外设节点默认状态为 disabled，仅保留芯片级必需节点（如GIC、定时器）为 okay。板级文件通过 &节点名 引用并修改其 status 属性来启用外设。

4.1.2 板级dtsi与板级dts：从公共到具体

板级dtsi（如 rk3588-evb.dtsi）通常由方案公司或核心板厂商提供，描述某一类参考设计的公共配置。例如，EVB（Evaluation Board）的dtsi会包含：

• DDR容量与型号（通过 memory 节点或 ddr_timing 参数）
• PMIC（如RK806）的I2C地址、各LDO/BUCK输出电压
• 板载网络芯片（如RTL8211F以太网PHY）的复位GPIO与时钟
• 调试串口（通常为UART2）的引脚复用配置

最终的板级dts（如 rk3588-evb1-v10.dts）是编译的入口文件。它通过 #include 指令将上述所有层级文件组合在一起，并添加该特定版本板卡的差异化配置。例如，V1.0版本使用MIPI-DSI屏幕，而V1.1版本改用eDP屏幕，这种差异就在板级dts中通过覆盖 &dsi 或 &edp 节点实现。

4.2 Overlay机制：运行时动态配置

Overlay（设备树覆盖）允许在系统运行时不重新编译内核或dtb，动态加载或卸载外设配置。这在RK3588的AI边缘计算盒子、扩展板卡等场景中非常实用。

4.2.1 Overlay的工作原理

Overlay文件（.dtbo）本质上是一个精简的设备树片段，包含 __overlay__ 和 __symbols__ 节点。内核的 configfs 接口允许用户将dtbo文件写入 /sys/kernel/config/device-tree/overlays/ 目录，内核会动态解析该片段并将其合并到系统主设备树中。

# 加载overlay示例
mkdir -p /sys/kernel/config/device-tree/overlays/my-overlay
cat /path/to/my-overlay.dtbo > /sys/kernel/config/device-tree/overlays/my-overlay/dtbo

# 卸载overlay
rmdir /sys/kernel/config/device-tree/overlays/my-overlay

编译overlay需要在内核源码树中执行：

make ARCH=arm64 dtbs  # 或单独编译
# 对于overlay，使用dtc直接编译：
dtc -@ -I dts -O dtb -o my-overlay.dtbo my-overlay.dts

其中 -@ 参数表示生成符号表（symbols），这是overlay能够引用主设备树节点的关键。

4.2.2 Overlay的适用场景与限制

Overlay并非万能，它适用于以下场景：

• 多配置产品：同一主板，通过加载不同overlay支持不同型号的摄像头模组或显示屏。
• 外设扩展：通过PCIe或USB连接的扩展卡，在插入时动态加载对应驱动配置。
• 调试与原型验证：快速测试新外设的引脚配置，无需反复烧写boot分区。

但需要注意：overlay无法修改已在系统启动早期初始化的节点（如DDR、时钟树），也无法解决硬件设计错误。此外，overlay的加载顺序依赖关系需要谨慎管理，多个overlay同时修改同一节点时，后加载的会覆盖先加载的。

4.3 编译流程与Buildroot集成

在Buildroot构建RK3588系统时，设备树的编译流程是自动化的。理解这一流程有助于排查编译错误和定制设备树。

4.3.1 标准编译链路

设备树从源码到二进制需要经过两个阶段：

1. C预处理器（cpp）：处理 #include、#define、#ifdef 等宏指令。这使得dts文件可以复用dtsi片段，并支持条件编译。例如，rk3588-evb1-v10.dts 中的 #include "rk3588-evb.dtsi" 在此阶段被展开。
2. 设备树编译器（dtc）：将预处理后的dts文件解析为二进制dtb格式。dtc会检查语法错误、重复节点定义、非法属性值等。对于overlay，dtc需要 -@ 参数生成符号表。

在Buildroot中，设备树的编译由内核的构建系统驱动。通常，板级dts文件位于内核源码的 arch/arm64/boot/dts/rockchip/ 目录下。Buildroot通过 BR2_LINUX_KERNEL_INTREE_DTS_NAME 配置项指定要编译的dts文件名（不含.dts后缀）。

# Buildroot配置示例 (make menuconfig)
Kernel  ->  Linux Kernel  ->  Device tree source file names
  (rockchip/rk3588-evb1-v10)  # 填写相对于arch/arm64/boot/dts/的路径

编译完成后，生成的 rk3588-evb1-v10.dtb 会被复制到 images/ 目录，并打包进boot镜像（如 boot.vfat 或 recovery.img）。

4.3.2 自定义设备树的三种方式

开发者通常通过以下三种方式之一来定制设备树：

对于大多数产品开发，推荐使用Buildroot patch方式。在 board/rockchip/rk3588/patches/linux/ 目录下放置针对dts文件的补丁，Buildroot会在解压内核源码后自动应用。

4.4 实战案例：为RK3588定制MIPI-CSI摄像头设备树

假设我们需要在RK3588 EVB板上接入一款OV13850 MIPI-CSI摄像头，并使其在Buildroot系统中正常工作。以下是完整的操作闭环。

4.4.1 背景与初始状态

硬件连接：OV13850通过MIPI CSI-2接口连接到RK3588的CSI端口（对应设备树节点 &csi2_dphy0），使用I2C4总线控制（地址0x10），复位GPIO为GPIO3_B5，电源由LDO3提供（3.3V）。初始系统启动后，v4l2-ctl --list-devices 无法检测到摄像头设备。

4.4.2 分析过程

首先检查I2C总线是否枚举到设备：

i2cdetect -y 4  # 查看I2C4总线上是否有0x10设备
# 输出显示 "UU" 或 "10" 表示设备存在，若为空则检查硬件连接或引脚复用

确认I2C设备存在后，检查内核日志：

dmesg | grep -i ov13850
# 若无任何输出，说明驱动未匹配到设备，问题出在设备树节点配置

查看当前设备树中CSI相关节点的状态：

ls /proc/device-tree/  # 确认csi2_dphy0节点是否存在
cat /proc/device-tree/csi2_dphy0/status  # 若显示disabled，则需启用

4.4.3 实施步骤

在Buildroot的补丁目录创建补丁文件 0001-add-ov13850-camera.patch，内容如下：

--- a/arch/arm64/boot/dts/rockchip/rk3588-evb1-v10.dts
+++ b/arch/arm64/boot/dts/rockchip/rk3588-evb1-v10.dts
@@ -120,6 +120,30 @@
 	};
 };
 
+&i2c4 {
+	status = "okay";
+	pinctrl-names = "default";
+	pinctrl-0 = <&i2c4m2_xfer>;
+	ov13850: ov13850@10 {
+		compatible = "ovti,ov13850";
+		reg = <0x10>;
+		clocks = <&cru CLK_MIPI_CAMERAOUT>;
+		clock-names = "xvclk";
+		pinctrl-names = "default";
+		pinctrl-0 = <&mipim0_camera1_clk>;
+		reset-gpios = <&gpio3 RK_PB5 GPIO_ACTIVE_LOW>;
+		power-supply = <&vcc3v3_ldo3>;
+		port {
+			ov13850_out: endpoint {
+				remote-endpoint = <&csi2_dphy0_input>;
+				data-lanes = <1 2 3 4>;
+			};
+		};
+	};
+};
+
+&csi2_dphy0 {
+	status = "okay";
+	ports {
+		#address-cells = <1>;
+		#size-cells = <0>;
+		port@0 {
+			reg = <0>;
+			csi2_dphy0_input: endpoint@1 {
+				remote-endpoint = <&ov13850_out>;
+				data-lanes = <1 2 3 4>;
+			};
+		};
+	};
+};
+
 &uart2 {
 	status = "okay";
 };

同时，需要确认内核配置中已启用OV13850驱动：

make linux-menuconfig
# Device Drivers -> Multimedia support -> Camera sensor devices
# 启用 CONFIG_VIDEO_OV13850

重新编译并烧录：

make linux-rebuild
make  # 重新生成镜像
# 烧录boot.img到开发板

4.4.4 结果与验证

系统启动后，执行以下命令验证：

v4l2-ctl --list-devices
# 应显示 ov13850 设备节点 /dev/video0
media-ctl -d /dev/media0 -p  # 查看媒体拓扑，确认sensor与ISP连接正确

若仍无法识别，使用 dmesg | grep -i ov13850 查看驱动报错。常见问题包括：reset-gpios 电平极性错误、data-lanes 数量与硬件连接不匹配、时钟频率配置不正确。

4.4.5 复盘与经验

本次案例中，最关键的教训是引脚复用（pinctrl）配置。RK3588的I2C4和CSI时钟有多组引脚复用选项（m0/m1/m2），必须与硬件原理图严格对应。在补丁中我们使用了 &i2c4m2_xfer 和 &mipim0_camera1_clk，这是根据EVB原理图确认的。若复用错误，I2C总线无法通信，摄像头自然无法枚举。

此外，power-supply 属性引用的 &vcc3v3_ldo3 必须在板级dtsi中已定义，否则编译时会报“引用未定义节点”的错误。这提醒我们，在修改设备树前，先通读现有dtsi文件，了解已定义的电源节点和GPIO别名。

4.5 常见误区与总结

在RK3588设备树开发中，以下误区值得特别注意：

• 误区一：直接修改SoC级dtsi。这会导致所有基于该SoC的板卡行为改变，且内核升级时修改会丢失。正确做法是始终在板级dts中通过 &节点 引用覆盖。
• 误区二：忽略status属性。RK3588的dtsi中大部分外设默认 disabled，仅添加节点而不设置 status = "okay" 不会生效。
• 误区三：overlay与主dtb的符号冲突。overlay中引用的节点必须在主dtb中存在且未被 /delete-node/ 删除，否则加载失败。
• 误区四：编译时未启用CONFIG_OF_OVERLAY。内核默认可能未开启overlay支持，需要在 make linux-menuconfig 中确认 Device Tree and Open Firmware support -> Device Tree overlays 已启用。