企业官网建设流程全解析

很多刚接触Linux驱动开发的人，第一次被“设备树”三个字卡住，多半是因为手上的板子明明能跑，内核也编过了，但外设就是没反应。我也不例外，第一块RK3568板子拿回来，点个GPIO灯都点不亮。后来才明白一个核心事实：在现在的Linux内核驱动开发里，写驱动只是其中一半工作，另一半是写对的设备树。设备树不再是一个可学可不学的知识点，而是驱动代码和物理硬件之间唯一的“接线表”。

这篇东西不打算从头讲一遍《Device Tree Specification》，而是围绕一个实际场景——用一块瑞芯微RK3568开发板，跑Linux或OpenHarmony内核，让驱动正确识别设备树里的硬件资源——把设备树和驱动之间的关系、文件组织、语法习惯、匹配机制、常见坑全部串一遍。适合刚想通“为什么我写的platform_driver不probe”的新手，也适合已经被多份dts吓到、不知道选哪个文件的入坑者。

1. 为什么现在的Linux驱动开发绕不开设备树

1.1 没有设备树的时代：代码里堆硬件描述

在设备树大规模进入ARM Linux内核之前，每来一块新板子，内核里就要新增一个 board-xxx.c 文件，里面用大段C语言硬编码描述这块板子上有什么：内存起始地址、串口地址、GPIO哪个引脚接了什么、I2C总线上挂了几颗芯片。内核维护者每收一个新的支持请求，就要把一堆板级代码塞进arch/arm/mach-xxx目录。

这个做法在板子少的时候还能忍，但ARM生态一旦铺开，问题立刻暴露：外设厂商更新了一颗PMIC，或者开发板从DDR3换到DDR4，都得改C代码、重新编译内核，甚至还要为同SoC不同板卡维护多个boot参数。硬件描述和内核执行逻辑耦合在一起，导致Linux发行版根本没能力一个内核镜像适配一排不同开发板。

1.2 设备树到底干了件什么事

设备树把“这块板子上有什么”从内核源码里彻底剥离开。它以树状结构描述CPU、内存、串口、I2C、GPIO等硬件资源，以及它们的地址、中断号、寄存器偏移、时钟关系，做成一份独立数据文件。内核在启动早期读取这份数据，再据此创建platform设备并触发对应驱动。

换句话说，设备树是硬件的“身份证+体检查表”。驱动不直接写“我在地址0xFE660000”，而是说“我兼容哪个compatible型号”，而板级信息由设备树告诉内核哪里有这个型号。这样内核一份镜像，就能通过更换不同的设备树适配不同板卡，不需要为每块板子重新编译内核。

Linux内核里的OF（Open Firmware）框架就是用来消费这份数据的，CONFIG_OF是必选项。ARM64平台从Linux 3.x后期开始全面依赖设备树，这也是你现在搜RK3568相关代码，看到的全是dts/dtsi的原因。

1.3 设备树和驱动的边界在哪

新手最容易犯的错是把设备树当成一种“驱动配置注解”，试图在设备树里写逻辑、写顺序。但设备树的职责边界非常明确：

• 只描述硬件是什么、在哪里、中断和时钟怎么接；
• 不描述驱动怎么跑、初始化顺序是什么、策略是什么；
• 驱动通过设备树拿资源，但驱动仍然负责内核对象注册、中断处理、文件操作等逻辑。

理解这个边界之后，很多困惑会迎刃而解。比如你发现驱动probe没执行，第一反应不该是去设备树里加“触发标志”，而应该查compatible是否对得上、status是否被禁用、依赖的clk和pinctrl是否被别的设备占用。

2. 从一份dts到内核能读懂的dtb：设备树文件体系与编译链路

2.1 dts、dtsi、dtb、dtc分别是什么

设备树相关文件分四类，搞不清这四者，后面的操作全白搭。

可以这么理解：.dtsi存放“这个SoC有哪些IP、核心板有哪些共同硬件”，.dts只放“这块具体板子上怎么连接、使能哪些外设”。RK3568的公共描述都写在arch/arm64/boot/dts/rockchip/rk3568.dtsi里，而具体开发板文件是rk3568-evb1-ddr4-v10.dts之类。

2.2 Rockchip平台上常见的多级dtsi继承结构

RK3568相关设备树文件多到一眼看不完，但顺着include关系梳理，会发现是清晰的金字塔结构：

/* rk3568-evb1-ddr4-v10.dts */ /dts-v1/; #include "rk3568-evb.dtsi" #include "rk3568-evb1-ddr4-v10.dtsi"

rk3568.dtsi负责描述SoC内部所有外设控制器：UART、I2C、SPI、DWC3 USB、PCIe、GPU、NPU等，默认大部分status为“disabled”。再往上是rk3568-evb.dtsi，描述EVB公共板型使用的PMIC、eMMC、LPDDR/DDR初始化相关节点。到了最终.v10.dtsi，才是这颗板子的具体差异：用了哪种显示接口、哪路以太网PHY。

这种分层的好处是：同一个SoC，一套rk3568.dtsi，换不同的板级dtsi就能衍生出一堆开发板。坏处是：新人看到目录里几十个rk3568-*.dts，根本分不清自己该用哪个。这个问题的解决办法我在第6节专门展开。

2.3 编译与反编译设备树的标准操作

在Linux内核源码树里编译单个设备树：

# ARM64平台 make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- dtbs # 只编一个文件 make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- rk3568-evb1-ddr4-v10.dtb

Rockchip官方SDK常用./make.sh一键打包，底层也会调用内核的dtb目标。如果你的设备树源文件语法有问题，编译器会明确告诉你：syntax error、unexpected character等。遇到这类错误，优先检查最容易被埋掉的结尾分号、逗号、尖括号配对。

反编译dtb是个极其实用的调试技巧。很多情况下，你拿到的是别人做好的boot.img，板上跑的设备树到底长什么样，靠猜没用，直接反编译看：

dtc -I dtb -O dts -o rk3568-decompiled.dts rk3568-evb1-ddr4-v10.dtb

反编译出来的内容会有__symbols__、labels等内部标记，比原始dts更啰嗦，但硬件资源一目了然。改完dts再重新生成dtb，整个过程可逆，完全够日常使用。

2.4 更新设备树后怎么让它生效

dtb编译出来后，有三种落地路径，取决于你的启动方式：

• 传统U-Boot模式：U-Boot从FAT/ext4分区加载boot.img或独立dtb，内核启动参数里有fdtfile或booti命令指定地址；
• Rockchip打包模式：SDK会生成resource.img，里面包含多个dtb，U-Boot根据硬件ID或环境变量选择加载哪一份；
• DTB独立分区：Android/OpenHarmony设备通常有独立的dtbo分区，用来存放dtb以及overlay。

我个人的建议：除非非常明确U-Boot从哪个分区加载设备树，否则不要只改内核里的dts就算完事。改完之后，至少做一次真正的全流程编译并烧录，然后进系统确认运行时设备树已经变化（具体确认命令在第6.3小节）。

3. 节点、属性、引用：读懂设备树必须掌握的语法细节

3.1 一个串口节点拆开看

拿RK3568上的一个UART节点举例，下面是简化和注释过的写法：

uart0: serial@fe660000 { compatible = "rockchip,rk3568-uart", "snps,dw-apb-uart"; reg = <0x0 0xfe660000 0x0 0x100>; interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>; clocks = <&cru uart0_clk>, <&cru uart0_pclk>; clock-names = "baudclk", "apb_pclk"; status = "disabled"; };

逐行拆解一下：

• uart0是标签（label），方便其他文件用&uart0引用；
• serial@fe660000是节点名和单元地址，@后面跟寄存器首地址，主要用于可读性，真正起匹配作用的是compatible；
• compatible是一个字符串数组，第一个值优先匹配，如果驱动不认第一个则尝试第二个，后面的值当成fallback；
• reg表示寄存器地址范围，值个数与#address-cells和#size-cells对应；
• interrupts声明中断号与触发方式，GIC_SPI是dt-bindings头文件里的宏；
• clocks和clock-names只是告诉内核这个设备需要哪几路时钟，具体频率由clk框架根据dts其他节点得出。

3.2 地址、中断、时钟、GPIO这些属性怎么表示

设备树里没有“API”，只有属性。最常用的几类：

/* 地址：address-cells表示地址用几个u32，size-cells表示长度用几个u32 */ #address-cells = <1>; #size-cells = <0>; reg = <0xfe660000 0x100>; /* 中断：先父节点，再子节点，值含义由interrupt-controller节点决定 */ interrupt-parent = <&gic>; interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>; /* GPIO：引脚的控制器引用、引脚号、极性 */ led-gpios = <&gpio4 RK_PC2 GPIO_ACTIVE_LOW>; /* 时钟 */ clocks = <&cru uart0_clk>, <&cru uart0_pclk>; clock-names = "baudclk", "apb_pclk"; /* 引脚复用 */ pinctrl-names = "default"; pinctrl-0 = <&uart0_xfer>;

GPIO在设备树里用&gpio4 RK_PC2这种形式，RK_PC2是Rockchip在dt-bindings/pinctrl/rockchip.h里定义的引脚编号宏，表示GPIO4组C2引脚。要不要加GPIO_ACTIVE_LOW影响的是gpiod_get后的逻辑极性，而不是电气极性。

3.3 用&uart0改状态：增量修改与覆盖

整个设备树描述的是硬件全貌，但某个具体板卡只需要使能其中一部分，这时就在板级dts里引用标签做增量修改：

&uart0 { status = "okay"; pinctrl-names = "default"; pinctrl-0 = <&uart0_xfer>; };

这种写法在实践中最常见。注意几个细节：

• 同一属性不允许在同级节点里重复定义，dts编译器会报错；
• 增量修改通常是覆盖属性值，不是追加，除非属性本身支持收尾拼接；
• 如果SoC级dtsi里是disabled，而板级没写status，就是保持disabled，驱动不会加载；
• 可以覆盖compatible、reg等核心属性，但强烈不建议在板级文件里给SoC节点乱改地址，很容易造成系统级内存映射冲突。

3.4 model和compatible命名规范

根节点里最重要的两个属性：

/ { model = "Rockchip RK3568 EVB1 DDR4 V10 Board"; compatible = "rockchip,rk3568-evb1-ddr4-v10", "rockchip,rk3568"; };

model是一个给人看的名称，不参与匹配。compatible是内核识别板卡身份的关键，它遵循“厂商,型号”的约定，必须全部小写，型号里用数字和字母，不用空格。很多工具和Init脚本会根据根节点compatible判断当前机器是什么设备。

这也呼应了第1节说的解耦思想：内核拿着根节点compatible就能知道自己在哪类产品上运行，从而决定加载哪些board-specific逻辑。需要跑Android还是Debian，都不再是改C代码的问题，而是换一份dts。

4. 驱动里怎么和设备树“对上暗号”：platform_match的完整链路

4.1 设备端：compatible与status扮演的角色

内核启动过程中，遍历设备树的每个节点，会根据节点里的compatible和父总线类型生成对应的platform_device或挂到对应子系统总线。串口、I2C控制器、SPI控制器这类“挂在根上/内部总线”的设备，最终会变成platform_device。I2C子节点则会被i2c总线解析成i2c_client。

这里有个新手容易忽略的关键点：设备树节点只有status = "okay"或status缺省，才会被创建为设备。若是“disabled”，platform_device都不会生成，更别谈probe。所以在设备树里写了节点却不工作，第一件事永远是确认status。

4.2 驱动端：of_match_table与MODULE_DEVICE_TABLE

一个platform_driver想和设备树节点对上，靠的是of_match_table：

#include <linux/mod_devicetable.h> #include <linux/of.h> #include <linux/of_device.h> static const struct of_device_id my_led_of_match[] = { { .compatible = "myvendor,myled" }, { } }; MODULE_DEVICE_TABLE(of, my_led_of_match); static struct platform_driver my_led_driver = { .probe = my_led_probe, .remove = my_led_remove, .driver = { .name = "my_led", .of_match_table = my_led_of_match, }, }; module_platform_driver(my_led_driver);

匹配逻辑其实是逐条比较设备树节点的compatible字符串和of_match_table里的compatible。匹配成功一次，内核就会调用probe，并把对应的device_node指针塞进pdev->dev.of_node。MODULE_DEVICE_TABLE让内核在模块加载时能自动根据设备树找到这个驱动，没有它，即使compatible完全一致，也可能出现设备有了、驱动不加载的怪事。

4.3 probe函数如何拿到树上的资源

设备树匹配成功后的probe函数，是驱动逻辑的真正入口，也是绝大多数“驱动没反应”问题发生的地方：

static int my_led_probe(struct platform_device *pdev) { struct device *dev = &pdev->dev; struct device_node *np = dev->of_node; struct gpio_desc *led_gpio; int ret; led_gpio = devm_gpiod_get(dev, "led", GPIOD_OUT_LOW); if (IS_ERR(led_gpio)) { return PTR_ERR(led_gpio); } gpiod_set_value(led_gpio, 1); ... return 0; }

可以看到，驱动代码里完全没有“RK3568”“GPIO4_C2”这种硬编码，它只按属性名要“led”这个GPIO。至于这个GPIO在哪个控制器、哪个引脚，由设备树决定：

led { compatible = "myvendor,myled"; led-gpios = <&gpio4 RK_PC2 GPIO_ACTIVE_LOW>; status = "okay"; };

这种解耦正是设备树的精髓：同一个驱动，只要设备树里把led-gpios指到不同的控制器引脚，就能驱动不同板卡上的LED，再也不需要为每块板子复制一份带地址的驱动。

4.4 产品里一个实用字符设备驱动的完整示例

讲了原理，给一个综合示例。这个驱动做两件事：probe时读取设备树里的寄存器地址，并申请一个中断；然后把寄存器区域映射为内存访问，向用户态暴露几个寄存器读写接口。具体文件操作略去，重点看资源获取：

static int demo_probe(struct platform_device *pdev) { struct device *dev = &pdev->dev; struct resource *res; void __iomem *base; int irq, ret; res = platform_get_resource(pdev, IORESOURCE_MEM, 0); base = devm_ioremap_resource(dev, res); if (IS_ERR(base)) return PTR_ERR(base); irq = platform_get_irq(pdev, 0); if (irq < 0) return irq; ret = devm_request_irq(dev, irq, demo_isr, 0, dev_name(dev), base); if (ret) return ret; return 0; }

platform_get_resource和platform_get_irq会自动从设备树的reg和interrupts属性解析，用起来比直接of_parse_phandle省心，而且更不易出错。这里refactor一下：不是所有设备资源都只能从设备树拿，但只要是platform设备，这组API就是最高优先级的获取方式。

5. 内核驱动中读取设备树资源的常用API与引用计数

5.1 reg地址、中断号、GPIO三种资源的最短读取路径

日常驱动里最常打交道的三类资源，我总结成一张表，拿来即用：

如果驱动依赖稍晚就绪的资源，比如某个外部时钟还没注册，probe里可以返回-EPROBE_DEFER，内核会过一会重新调用probe。设备一直挂在延迟列表里，所以“probe一点反应都没有”的时候，先去看看延迟表。

5.2 遍历子节点和解析phandle的技巧

有时需要在驱动里主动遍历子节点，比如一个电源管理芯片下面挂多路regulator。惯用写法：

struct device_node *child; int ret; for_each_child_of_node(np, child) { u32 reg_id; ret = of_property_read_u32(child, "reg", &reg_id); if (ret) { of_node_put(child); return ret; } // 用reg_id初始化一路regulator }

解析一个phandle引用的节点，常用of_parse_phandle：

struct device_node *target; target = of_parse_phandle(np, "target-phandle", 0); if (!target) return -EINVAL; // 使用完后必须 of_node_put(target)

很多写内核模块的人容易忽略of_node_put，导致device_node引用计数只增不减，最终表现为/sys/firmware/devicetree下的节点删除后在内存里泄漏，长时间运行系统内存缓慢增长。这个坑在长稳测试里特别容易被定位出来。

5.3 of_node_put和devm_：容易被忽略的两个细节

of_node_put的问题我再强调一遍：of_find_node_by_name、of_parse_phandle、of_get_child_by_name这些API都会拿引用计数，用完必须配对释放。与之相反，devm_系列API由设备生命周期自动管理，比如devm_gpiod_get返回的GPIO描述符、devm_clk_get返回的时钟句柄，都不需要手动释放，probe失败或设备移除时内核会帮你清理。

所以我个人建议：新驱动里尽量用devm_系列 + platform_get_resource/platform_get_irq这套组合，代码短，错误路径也少；只有在需要解析复杂设备树结构时才直接调of_parse_phandle系列，并且每个成功路径后面跟一个错误处理。

另一个细节：err = of_property_read_string(np, "label", &str); 返回0才是成功，不是对值做判空。很多人直接判断str是否为NULL，结果属性不存在时读取的是旧数据，程序行为完全不可控。

6. RK3568那么多设备树文件，到底该选哪一个

6.1 认清命名规律：从SoC到开发板再到定制板

打开arch/arm64/boot/dts/rockchip目录，rk3568开头的dts文件数量会让你怀疑人生。但只要按dtsi继承关系看，选型思路就非常清晰：

• 先确定核心板/SoC型号是RK3568还是RK3566，两者引脚和部分外设不同；
• 再看内存类型：DDR3/DDR4/LPDDR4X，有些BSP会按内存类型分开dts；
• 然后看板级差异：HDMI+LVDS还是HDMI+EDP，双千兆网口还是单网口；
• 最后看PMIC型号，比如RK809或RK817，dts里的regulator节点直接对应。

以EVB1为例，rk3568-evb1-ddr4-v10.dts对应的就是EVB1底板+DDR4内存+V10版本。如果你的板子是第三方做的，厂商会提供自己命名的dts，比如nanopi-r5s、rock-3a。用错文件的后果通常是内核起来但某个外设找不到，或者启动过程中出现严重的时钟/regulator错误。

6.2 OpenHarmony和官方BSP的设备树差异

OpenHarmony在RK3568上移植时，内核虽然是Linux共同分支，但设备树文件可能和Rockchip原厂BSP不是完全同步。OH更强调HDF（Hardware Driver Foundation）框架，外设驱动有一部分走HDF平台，驱动初始化和匹配路径要比标准内核多一步。因此，你如果拿原厂Linux SDK的dts直接灌进OpenHarmony镜像，往往导致display、wifi这类外设不工作；反过来也一样。

所以选设备树之前，先确认你跑的是哪个系统。标准的Linux发行版就选内核仓库里对应的dts，OpenHarmony就用OH SDK内核仓库维护的设备树，不要把两份混着用。这也是社区里关于“OpenHarmony的rk3568有许多设备树到底咋选”这个问题最常见的答案：先看你的内核分支，再看板子的硬件版本，最后看DTB到底打包进了哪个镜像。

6.3 快速定位“我现在跑的是哪份设备树”

板子已经跑起来，但不确定当前用的是哪个dtb，有一堆命令可以确认。我最常用的有两个：

cat /proc/device-tree/model

这条命令直接输出根节点model，一眼就能看出当前设备树是为哪块板子写的。另一个是：

ls /sys/firmware/devicetree/base/

这个目录就是运行时设备树的根节点，里面所有子目录对应dts里的节点，所有小文件对应属性。想确认某个串口节点是否使能，可以直接cat属性文件，比如：

cat /sys/firmware/devicetree/base/serial@fe660000/status

输出empty也是有效结果，代表节点没有写status，默认按okay处理。这些命令在开发和验收环节都能用，比反复看编译日志直观得多。

6.4 不要乱改dtsi的教训

最后说一条最贵的经验：别图省事，直接修改rk3568.dtsi这种SoC级基础文件来适应你的一块板子。一旦改了SoC级文件，其他板卡全部遭殃，调试半天只是在掩盖真正问题。

正确做法永远是：板级差异留在板级dts里。如果你用的第三方核心板没给你公开dts，宁可花时间从反编译产物里提取差量，重新组织成overlay或独立板级dts，也不要污染公共dtsi。SDK升级时最明显的差异就是dtsi被厂商大改，你把修改全部摊在板级文件里，升级内核时冲突会少很多。

7. 设备树排错实录：从启动卡住到外设失灵的分析链路

7.1 第一级排查：内核有没有正确接收dtb

设备树相关的故障，很多能在启动早期就暴露。如果内核启动后串口完全没有打印，先怀疑U-Boot传给内核的dtb是不是正确分区、打包前是不是最新版。常见做法是U-Boot里执行：

printenv fdtfile

Rockchip平台常见的变量是fdtfile或dtb_name。如果这个值指向的dtb与你期望的不一致，改环境变量或resource.img才是正确方向，而不是反复编译内核。

如果U-Boot打印已经出现，但内核在“Machine model: ...”之后卡住，大概率是dtb和内核不匹配，比如ARM32的内核被塞进ARM64的dtb。逐级确认分区镜像与内核arch匹配，是这一级最容易被忽略的检查项。

7.2 第二级排查：设备节点有没有生成platform设备

内核起来后，如果外设完全没有反应，先确认节点是否生成了设备。检查方法：

ls -l /sys/bus/platform/devices/ | grep fe660000

如果没看到serial@fe660000对应的设备目录，说明设备树解析阶段就没把这个节点变成本文4.1节说的platform_device。原因不外乎三类：

• status = "disabled"；
• 父节点的status也是disabled；
• compatible缺失或拼写写错，导致内核不知道挂到哪条总线。

这类问题的排查路径最清晰，从根节点顺着parent一路检查status，基本十有八九能定位。

7.3 第三级排查：驱动probe为什么没被调用

节点和设备都生成了，但驱动没probe，这时看两个地方。第一是/dev下的设备节点是否有生成、/sys/bus/platform/drivers/有没有你的驱动目录。第二是modprobe后看deferred列表：

cat /sys/kernel/debug/devices_deferred

如果设备出现在这个列表里，说明probe被调用过但返回了-EPROBE_DEFER，它依赖的某个资源暂时没准备好。顺着deferred信息里提示的依赖项，去看对应的clock、regulator、interrupt是否已经在设备树里声明并使能。

如果deferred列表是空的，也没有probe报错，那就要查模块到底有没有加载成功。野生做法是dmesg里搜驱动名，不过更靠谱的是：

lsmod | grep my_led

模块没加载，先看MODULE_DEVICE_TABLE和of_match_table是否齐全，这是模块能自动匹配设备树设备的前提，很多人在这踩过坑。

7.4 第四级排查：运行时动态修改设备树验证

有些问题要在运行中反复验证，比如快速测试一个compatible或者GPIO定义，不想每次重新烧boot。设备树overlay就是为这个场景准备的。内核开启CONFIG_OF_OVERLAY后，可以通过configfs加载dtbo：

# 挂载configfs mount -t configfs configfs /sys/kernel/config # 建立overlay目录 mkdir /sys/kernel/config/device-tree/overlays/demo # 把编译好的dtbo写入fdt cat demo.dtbo > /sys/kernel/config/device-tree/overlays/demo/dtbo

加载前先保存旧的设备树基础数据，比如用dtc反编译当前/dtb/下的dtb，加载后再次反编译运行时的设备树快照，多出来的节点就是你的overlay。如果加载出错，dmesg里通常会有__symbols__找不到的错误，说明overlay引用的标签在原设备树里不存在。

动态overlay只适合验证和调试。量产设备绝不应该用overlay方法打补丁，稳健做法是把改好的增量合并进正式dts，再完整走一遍编译和烧录流程。

最后分享一个习惯：每次拿到一块新板子，头20分钟我一定会做三件事——看根节点model、cat /proc/device-tree/model确认设备树；看/sys/bus/platform/devices/目录确认关键外设有没有生成设备；再看一眼/sys/kernel/debug/devices_deferred有没有意外滞留的设备。这三步能过滤掉大部分“硬件没反应”的表面问题，让你把精力真正放到驱动逻辑上。设备树这东西，本质上就是一台硬件的“病历本”，学着读懂它，比盲目改代码靠谱得多。