1. 设备树DTS到底解决了什么问题从一次外设点不亮的排查说起先讲个我自己的经历。去年刚接触OpenHarmony开发板时拿了一块RK3568的开发板按照官方文档编译完镜像烧进去系统起来了但串口控制台死活没有输出。查了半小时最后发现是uboot传参里的dtb文件名和板子实际型号对不上导致内核启动阶段根本没匹配到对应的设备树。这种问题在OpenHarmony开发里太常见了——板子拿到了镜像能烧但外设全看设备树脸色。这也是我这篇教程要解决的第一个问题不懂设备树你连系统怎么找到你的硬件都不知道。设备树Device Tree简称DTS在OpenHarmony系统里的角色简单说就是一份给内核看的“硬件说明书”。Linux/OpenHarmony内核是个通用软件它不知道自己跑在哪块板子上CPU是什么型号、内存多大、I2C总线上挂了几个传感器、GPIO哪个引脚控制LED——这些信息全都写在设备树里。内核启动时读取这份说明书才知道怎么初始化硬件。相比传统的LinuxOpenHarmony对设备树的依赖其实有过之而无不及。因为OpenHarmony要支持多种芯片平台RK、HiSilicon、Allwinner等还要兼顾标准系统和小型系统硬件差异比单纯某个Linux发行版大得多。而设备树恰恰是屏蔽这种差异的关键机制。很多刚接触OpenHarmony的开发者尤其是以前主要做单片机或者裸机开发的对设备树的态度都是“能用就行改坏了再说”。但实际开发中你遇到的外设不识别、驱动加载失败、GPIO冲突、甚至系统启动崩溃十有八九都跟设备树配置有关。如果你打算深度玩OpenHarmony硬件开发设备树是绕不过去的第一道关。这篇教程我会从设备树的核心概念开始讲然后结合RK3568平台最常见的“多设备树选择”问题做一次完整的实操排查再讲怎么从零写一个设备树节点、怎么编译验证最后聊一聊DTS背后的编译机制和一些进阶玩法。内容比较多但保证每一段都是能直接用到实战里的。2. 设备树的三个核心概念DTS、DTC、DTB以及它们和OpenHarmony的关系2.1 一份设备树源文件的完整构成先看一个最简的设备树源文件示例感受一下语法风格/dts-v1/; / { model OpenHarmony RK3566 Evaluation Board; compatible rockchip,rk3566, rockchip,rk3568; chosen { stdout-path uart2; }; memory10000000 { device_type memory; reg 0x10000000 0x80000000; }; leds { compatible gpio-leds; work_led: led0 { label work; gpios gpio0 RK_PB2 GPIO_ACTIVE_HIGH; }; }; uart2: serialfe650000 { compatible rockchip,rk3568-uart, snps,dw-apb-uart; reg 0xfe650000 0x100; interrupts GIC_SPI 253 IRQ_TYPE_LEVEL_HIGH; clocks cru SCLK_UART2, cru PCLK_UART2; clock-names baudclk, apb_pclk; status okay; }; uart2 { status okay; }; };这份文件里涵盖了设备树的核心语法点/dts-v1/;版本声明固定写法表示使用设备树v1语法。/ { ... }根节点所有设备节点都在它下面代表整个硬件平台。model板子型号描述字符串用来在日志里标识这块板子。compatible兼容性标识内核/驱动靠它匹配节点和驱动。这个属性是设备树里最关键的属性后面专门讲。chosen特殊节点用于传递内核启动参数比如stdout-path指定控制台串口。memory内存节点reg属性描述内存起始地址和大小。RK3568的内存基地址是0x10000000这在Rockchip平台上是个典型值。leds自定义节点比如这里用gpio-leds驱动来描述一个工作指示灯。gpios属性里引用了gpio0这个外部节点。2.2 DTS到DTB的编译过程设备树源文件.dts不能直接被内核读取需要编译成二进制格式的DTBDevice Tree Blob。这个编译工作由一个叫DTCDevice Tree Compiler的工具完成命令很简单dtc -I dts -O dtb -o rk3568-evb.dtb rk3568-evb.dts在OpenHarmony的编译体系里你通常不需要手动执行dtc命令。标准系统的编译脚本会遍历kernel/linux/arch/arm64/boot/dts/rockchip/目录下的所有dts文件自动编译生成对应的dtb。你只需要在编译配置里指定目标板子的dts文件名就行。**为什么需要转换成DTB而不是直接读DTS**一个原因是二进制格式更紧凑内核解析更快另一个原因是DTS源文件里允许包含#include等预处理指令经过C预处理器展开后的完整源文件才能编译成DTB。在OpenHarmony源码里很多dts文件开头都有类似这样的写法#include rk3568.dtsi #include rk3568-evb.ddr4-2rank-32bit-1044m.dtsi这里.dtsi就是设备树头文件类似C语言里的.h用来放SoC通用定义和板级公共配置。实际编译时预处理器会先把这些include展开形成一份完整的dts内容再交给dtc编译。2.3 DTB在系统启动流程中的传递路径搞清楚DTB的传递路径是理解“为什么编译了dtb还要单独烧录”的关键。OpenHarmony标准系统RK3568平台的典型启动流程是U-Boot启动读取分区表从boot分区加载内核镜像boot.img。U-Boot加载DTB从resource分区RK3568平台习惯或boot分区的dtb区域读取dtb文件到内存。U-Boot传参把dtb所在内存地址通过寄存器r2传给内核同时通过bootargs里的root等参数告诉内核根文件系统在哪。内核解析DTB内核启动时解析dtb遍历所有节点和驱动注册表中的compatible属性做匹配匹配成功的驱动就会执行probe函数初始化硬件。这个链路里最容易出问题的是第2步。RK3568的U-Boot会尝试从指定位置加载*.dtb文件如果你的板子上烧录的dtb文件名和U-Boot配置的不一样——比如U-Boot期待的是rk3568-evb1-ddr4-v10.dtb你烧的却是rk3568-evb.dtb——那就是我文章开头说的那种情况系统起得来但外设全乱套。OpenHarmony的kernel镜像里其实打包了多个dtb在kernel/linux/arch/arm64/boot/dts/rockchip/目录下你会发现同一颗RK3568芯片衍生出了十几个甚至几十个dts文件有rk3568-evb1-ddr4-v10.dts、rk3568-evb2-lpddr4-v10.dts、rk3568-evb6-lpddr4x-v10.dts等等。这就是热搜词里“openharmony的rk3568有许多设备树到底咋选”这个问题的由来。这个问题的标准排查链路我放在第4章专门讲。2.4 compatible属性设备树和驱动之间的“接头暗号”如果说设备树是一台电话交换机那compatible属性就是每个分机的号码。内核里的platform_driver通过of_match_table和节点compatible属性做字符串匹配匹配成功才绑定。以RK3568的串口驱动为例设备树里写compatible rockchip,rk3568-uart, snps,dw-apb-uart;内核驱动里写static const struct of_device_id dw8250_of_match[] { { .compatible snps,dw-apb-uart }, { .compatible rockchip,rk3568-uart }, {} };匹配规则是从左到右遍历设备树里的compatible字符串列表只要有一个字符串和驱动里的of_device_id表匹配上驱动就接管这个设备。因此设备树里compatible写成rockchip,rk3568-uart, snps,dw-apb-uart的意思是优先用瑞芯微的专用驱动如果有的话否则退回到通用的Synopsys DesignWare UART驱动。实战建议在你新增一个外设节点时compatible的值最好从要用的驱动源码里抄而不是自己凭空编一个。查代码的时候搜索of_device_id结构体数组看驱动支持哪些字符串。这一步能避免大量“驱动加载了但设备没匹配上”的诡异问题。3. 设备树的继承与叠加机制从SoC通用定义到板级定制的完整链路3.1 dtsi公共文件与dts板级文件的拆分逻辑我见过不少新手拿到的第一个开发板是RK3568然后打开rk3568-evb.dts一看好几百行立马头大。但你看懂了拆分逻辑之后会觉得这套体系其实非常优雅。设备树从设计上就分了两层SoC层级在rk3568.dtsi里定义这颗芯片本身拥有的所有硬件资源比如CPU核心、GIC中断控制器、CRU时钟模块、I2C/SPI/UART控制器、DDR控制器等。这些资源在同一颗芯片上不管做什么板子都一样所以放在公共文件里用rk3568.dtsi统一描述。板级层级在rk3568-evb.dts里只关心这块具体的开发板用到了哪些外设、怎么连的。比如EVB板子上挂了哪个型号的eMMC、用的DDR是哪种、WiFi芯片挂在哪个SDIO口、GPIO怎么复用等。这种拆分带来一个好处同一颗SoC的开发板dtsi文件基本不用动只需要根据板子改dts。RK3568的EVB系列开发板几十个型号底层的rk3568.dtsi是同一份。实际上OpenHarmony的RK3568相关dts通常还会再引入一层内存相关的dtsi比如#include rk3568-evb.dtsi #include rk3568-evb-ddr4-2rank-32bit-1044m.dtsi内存参数容量、rank数、位宽不同对应的初始化参数也不同。这也解释了为什么同一个evb板子会有ddr4-2rank-32bit-1044m、lpddr4-2rank-32bit-936m等多个变体——内存芯片规格不同设备树描述就要跟着变。3.2 根节点、子节点和引用节点设备树里的“文件系统”设备树的节点结构很像文件系统的目录树根节点/相当于根目录。每个节点相当于一个目录或文件。节点可以有子节点也可以有属性键值对。属性值类型包括字符串、字符串列表、32位整数数组...、64位整数数组...加#address-cells定义、二进制数据。节点引用的语法理解起来也不难uart2 { status okay; };这里的uart2表示引用之前定义过的uart2: serialfe650000节点。这个写法的本质是在原来的节点上追加或修改属性而不是重新创建一个节点。所以上面的写法等同于在uart2节点里加上status okay。这种“先定义后修改”的模式在板级dts里特别多。SoC级dtsi里把某个外设默认设为status disabled因为不是每块板子都会用到所有外设板级dts里再通过xxx { status okay; }把它打开。如果你在调试某个外设时发现驱动不工作优先检查status属性——这是我在支持开发者时遇到最高频的问题之一。再看gpios gpio0 RK_PB2 GPIO_ACTIVE_HIGH这个属性。尖括号里由三个值组成gpio0表示引用gpio0节点实际上引用的是某个GPIO控制器的phandle设备树内部用数字标识节点的引用关系RK_PB2是GPIO组和引脚编号RK_PB2就是GPIO0组的B2号引脚换算成数字在内核头文件里定义GPIO_ACTIVE_HIGH表示高电平有效。这类宏定义在dts里可以直接用因为编译设备树时C预处理器会先展开这些宏定义它们通常来自include/dt-bindings/gpio/gpio.h等路径。3.3 节点命名规则后面的地址到底是什么设备树节点的命名有规范节点名单元地址。比如cpu0CPU核心0serialfe650000UART控制器寄存器基地址在0xfe650000i2cfe5a0000I2C控制器后面的地址通常是该设备在总线上的寄存器基地址或者片选地址用于区分同类型的不同实例。如果节点没有地址比如根节点就不带。这个命名规则看着简单但有一个常见误区节点名不参与compatible匹配系统真正认的是compatible属性和节点的reg地址。也就是说你可以把serialfe650000改名为my_uartfe650000驱动照样能工作虽然强烈不建议这么干因为驱动匹配靠的是compatible。3.4 地址编码规则address-cells和size-cells设备树的reg属性用来描述设备的地址空间信息但是“地址”是多少位、“长度”是多少位得由父节点的#address-cells和#size-cells属性来声明。看一个典型例子soc { #address-cells 1; #size-cells 1; uart0: serialfe650000 { reg 0xfe650000 0x100; }; };#address-cells 1表示reg里地址用一个32位整数描述#size-cells 1表示reg里长度用一个32位整数描述。所以reg 0xfe650000 0x100的意思是寄存器基地址是0xfe650000寄存器区域大小是0x100字节。如果某个总线下挂的设备地址是64位的就要设置#address-cells 2。忘记调整address-cells导致设备地址解析错误是另一个比较容易踩的坑。RK3568的pinctrl节点里大量用到这类地址描述如果地址解析不对GPIO复用和引脚配置就会乱套。4. RK3568平台多设备树的选型排查OpenHarmony启动时dtb到底该烧哪一份4.1 问题现场同一个镜像烧进不同板子外设行为完全不同热搜词里那个“openharmony的rk3568有许多设备树到底咋选”的问题我几乎在每次OpenHarmony硬件适配培训里都会被问到。典型的场景是这样的从官方下载了RK3568标准系统的镜像烧录到EVB1开发板上系统能正常启动。但同一份镜像烧到自己画的板子上或者另一款EVB型号的板子上可能系统起不来或者起来了但是以太网不通、HDMI不显示、触摸屏不响应。原因非常明确系统启动时加载的dtb只包含了一种板级配置而不同板子的外设连接、GPIO复用、内存配置不一样这份配置无法同时兼容所有硬件。你需要的不是“换一个神奇镜像”而是“找到和自己板子匹配的那份dtb”。4.2 U-Boot的dtb搜索规则与RK3568的多dtb打包机制要解决选型问题先要知道U-Boot是怎么找到dtb的。RK3568平台上OpenHarmony的U-Boot默认会去resource分区加载*.dtb文件。这个resource分区是一个FAT格式的小分区专门存放开机需要用到的资源文件包括dtb、logo图片等。烧录工具烧镜像时会把编译产物里的多个dtb文件拷贝进resource分区的dtb/子目录里。U-Boot的rockchip_read_dtb_file逻辑大致是读取resource分区里dtb/目录下的所有文件列表。遍历每个文件名的前缀和编译时写入U-Boot环境变量或头信息里的“板级标识”通常是dts文件名中的板子型号字符串做模糊匹配。匹配成功就加载这份dtb到内存传给内核。问题就出在匹配规则是“模糊”的比如板级标识设置的是rk3568-evb1-ddr4-v10那它可能会匹配上rk3568-evb1-ddr4-v10.dtb也可能会匹配不上而是匹配到前面字符串相同的另一个文件。实际看日志时你会在串口控制台看到类似Failed to find devicetree for ...或Found DTB at ...的信息。这些日志就是排查的关键线索。4.3 排查链路从串口日志到dtb文件名的完整而实操的排查路径我在实际项目里总结了一套排查步骤照着走基本能定位90%的多dtb不匹配问题。第一步确认当前系统实际加载的dtb串口控制台U-Boot阶段输入printenv dtb_name或者看启动日志里类似这样的一行Trying to find DTB in resource partition: dtb/rk3568-evb1-ddr4-v10.dtb, trying 3 times...如果dtb_name是空或者和你的板子不符可以手动指定setenv dtb_name dtb/rk3568-evb1-ddr4-v10.dtb saveenv reset第二步从resource分区读取实际文件列表在U-Boot里执行mmc dev 0 fatls mmc 0:1 dtb注意设备号和分区号根据你的存储介质调整可能是mmc 0:1也可能是mtd 0之类RK3568一般以eMMC的mmc0为主如果dtb/目录下有多个文件直接对比你的板型和文件名找最接近的那个。第三步在dts源码里核对板级差异找到和你的板子最接近的dts文件后打开源码重点对比以下内容model和compatible板子型号标识是否符合。内存dtsiDDR容量、rank、位宽是否和你的硬件一致。比如你板上用的是2GB LPDDR4但dts引入的是4GB DDR4配置那系统虽然能启动但可用的内存可能只有一半甚至启动卡死。外设的status板子上实际存在的硬件在dts里是不是status okay。比如你的板子引出了以太网口但dts里对应节点是disabled网口肯定不工作。第四步修改dts并重新编译烧录核心思路不要试图去改U-Boot匹配逻辑直接在源码层面把dts改成和你板子一致然后重新编译dtb烧进resource分区。在OpenHarmony标准系统的dts目录通常是kernel/linux/arch/arm64/boot/dts/rockchip/下找到你的板型dts或者直接以某个现有的dts为模板复制一个新文件做板级定制。例如cp rk3568-evb1-ddr4-v10.dts my-board.dts然后修改my-board.dts里的model、内存配置、外设status等在编译配置里加上这个新dts的编译目标重新编译生成my-board.dtb烧录进resource分区。4.4 一份排查记录表格快速对照你的问题场景这里整理一份我在支持开发者时常用的对照表方便快速定位问题方向。启动现象可能原因优先排查项完全没有启动日志DTB没加载或加载失败U-Boot停在加载阶段resource分区是否有dtb、dtb_name是否配置正确启动到内核早期卡死DTB里的内存配置和实际DDR不匹配核对引入的DDR dtsi参数系统能启动但某外设不工作dts里外设节点是disabled或者compatible不匹配检查外设节点status、GPIO复用配置系统启动但识别不到eMMC/SD卡存储控制器节点配置不正确或引脚复用冲突检查sdmmc/sdio相关节点和pinctrl显示正常但触摸无反应I2C地址不对或者GPIO中断号配置错误核对触摸屏节点的i2c地址和中断引脚能进系统但串口控制台无输出chosen节点的stdout-path指向错误串口检查stdout-path引用的串口节点是否存在且okay4.5 我自己总结的选型经验在RK3568多设备树选型上我的实操经验是不要迷信“官方默认”三个字一定要根据自己板子的硬件配置做核对。即使是同一款EVB板不同批次可能内存芯片换了型号对应的内存初始化参数dtsi也可能要变。再有就是每次只改一个变量。比如你想适配一块新板子先以官方最接近的dts为底子只改内存配置启动确认正常后再逐个打开外设节点。一次改一堆节点出了问题你根本不知道是哪个改动导致的。5. 手写一个设备树节点从GPIO点灯到I2C传感器全过程的实战拆解5.1 新增一个GPIO控制节点的完整步骤光说不练假把式。这一节我带大家从零写一个设备树节点实现一个最基础的功能控制板子上的一个LED灯。先看最终要加到板级dts里的节点内容pinctrl { leds { work_led_gpio: work-led-gpio { rockchip,pins 0 RK_PB2 RK_FUNC_GPIO pcfg_pull_none; }; }; }; / { leds { compatible gpio-leds; work_led: led-0 { label work; gpios gpio0 RK_PB2 GPIO_ACTIVE_HIGH; linux,default-trigger heartbeat; }; }; };分解一下这个节点做了哪些事第一部分pinctrl引脚复用pinctrl节点下定义了一个work-led-gpio子节点表示要把GPIO0组的B2引脚复用为GPIO功能。rockchip,pins 0 RK_PB2 RK_FUNC_GPIO pcfg_pull_none里四个参数分别是bank号0、引脚号RK_PB2、功能复用选择RK_FUNC_GPIO表示作为普通GPIO用、上下拉配置无上下拉。如果不做这个复用配置内核可能不知道这个引脚当前应该是什么功能。pinctrl这种写法是向已有的pinctrl节点追加子节点。板级dts里通常都有现成的pinctrl追加块你可以在里面增加自己的子节点也可以新建一个pinctrl块编译器会把它们合并。第二部分gpio-leds设备节点compatible gpio-leds是内核里的标准LED驱动匹配后会自动注册一个LED设备。gpios属性描述了具体的GPIO引脚和有效电平linux,default-trigger heartbeat表示把这个LED作为心跳灯使用。这个节点写好后编译烧录系统启动后你会看到控制台里出现leds: work设备节点对应/sys/class/leds/work路径可以通过echo 255 /sys/class/leds/work/brightness控制亮度echo heartbeat /sys/class/leds/work/trigger切换触发模式。5.2 挂一个I2C设备以温湿度传感器为例GPIO之后上一个稍微复杂点的例子在I2C总线上挂载一个SHT30温湿度传感器。首先在dts里找到I2C总线的节点通常在rk3568.dtsi里已经有定义比如i2c1: i2cfe5a0000 { compatible rockchip,rk3568-i2c, rockchip,rk3399-i2c; reg 0xfe5a0000 0x1000; interrupts GIC_SPI 248 IRQ_TYPE_LEVEL_HIGH; #address-cells 1; #size-cells 0; status disabled; };板级dts里通過i2c1打开它并挂载SHT30子节点i2c1 { status okay; clock-frequency 400000; sht3044 { compatible sensirion,sht3x; reg 0x44; status okay; }; };几个关键点clock-frequency 400000设置I2C时钟频率为400kHz快速模式。如果传感器不支持这个频率可以改为100000。sht3044子节点名44是7位I2C地址的十六进制表示不带读写位。reg 0x44I2C设备地址。这里的reg代表设备在总线上的地址不是寄存器地址因为父节点i2c1的#size-cells 0所以只有一个描述地址的整数。compatible要和驱动里定义的一致。SHT30在Linux内核里的驱动compatible通常是sensirion,sht3x。我把这个节点加进dts后重新编译烧录系统启动日志里会多出类似这样的内容i2c 1: adapter at 0xfe5a0000 sht3x 1-0044: sensor connected如果你在/sys/bus/i2c/devices/1-0044/下看到节点说明挂载成功可以直接用内核提供的接口或者自己写个应用读取温湿度。5.3 那些只有踩过坑才知道的注意事项注意1I2C设备地址不要搞错位数。reg 0x44里的0x44是7位地址但有些传感器手册上写的是8位地址比如0x88需要把最低位去掉。I2C 8位地址0x88右移一位就是7位地址0x44。这是传感器dts适配里最常见的错之一。**注意2pinctrl配置不是可选项。**GPIO和I2C节点都依赖pinctrl配置才能正确工作因为SoC的同一个引脚往往有多路复用功能。如果I2C引脚的复用模式不对总线上的波形就是乱的。升级内核版本后pinctrl配置格式可能变化所以看旧代码改dts时一定要确认pinctrl子节点写法是否对应当前内核版本。**注意3status属性的“默认值”陷阱。**很多外设节点在dtsi里默认是disabled这是为了省电和避免引脚冲突。如果你发现驱动已经probe了但设备没信号先检查status有没有被正确设置为okay。另外还要区分节点的status和子设备的status两者是独立的。**注意4时钟相关的属性别乱抄。**I2C、UART这类高速外设通常需要配置时钟源和频率比如clocks cru SCLK_UART2。如果你从一个芯片型号抄到另一个芯片型号时钟ID很可能对不上。RK3568的时钟定义都在include/dt-bindings/clock/rk3568-cru.h里抄之前先去这个文件里确认宏存在。6. dtb的编译位置、内核配置项与resource分区烧录的实操说明6.1 OpenHarmony标准系统里dts文件放在哪里很多从纯Linux转过来的同学习惯在Linux内核源码目录里找dts文件。OpenHarmony标准系统也是这个思路但路径稍有不同。以RK3568为例OpenHarmony标准系统的内核代码在kernel/linux/目录下实际dts文件位置大约在kernel/linux/arch/arm64/boot/dts/rockchip/具体文件名就是rk3568-evb1-ddr4-v10.dts这类。注意OpenHarmony不同版本3.2、4.0、4.1等的路径可能略有差异但基本都在同样的目录结构下。如果你用的是DevEco Studio或者hb工具构建的latest版本可以在源码根目录执行find . -path *boot/dts/rockchip/rk3568*.dts | head -20直接定位到所有RK3568相关dts文件。6.2 手动编译dtb的命令与一键脚本在OpenHarmony源码环境下手动编译单个dtb可以用cd kernel/linux make ARCHarm64 rockchip_linux_defconfig make ARCHarm64 dtbs这会编译所有设备树。如果只想编译某一个make ARCHarm64 rk3568-evb1-ddr4-v10.dtb编译产物在arch/arm64/boot/dts/rockchip/rk3568-evb1-ddr4-v10.dtb。如果只是验证语法不依赖内核配置可以用dtc单独编译./scripts/dtc/dtc -I dts -O dtb -o test.dtb my-board.dts注意OpenHarmony内核源码里自带了dtc工具scripts/dtc/dtc不用额外安装。6.3 烧录到resource分区的方法编译好的dtb要放到resource分区才能被U-Boot找到。常见做法有两种方法一重新打包整个镜像在OpenHarmony构建系统里resource分区的镜像一般叫resource.img打包时会把vendor或特定目录下的dtb文件收集进去。具体脚本路径在build系统中通常在device/board/rockchip/下。修改dts后重新执行构建resource.img会自动更新。方法二直接更新已烧录板子上的resource分区如果你不想重新打包整个系统镜像可以用RKDevTool等烧录工具单独烧写resource分区。在工具里选择resource分区的镜像文件路径比如out/.../resource.img单独烧写该分区即可。也可以用U-Boot的命令把新的dtb写入fatwrite mmc 0:1 $loadaddr dtb/rk3568-evb1-ddr4-v10.dtb 0x100000x10000是文件大小要根据实际大小调整这里只是示例。6.4 dtb反编译遇到问题时的“x光机”调试dtb问题时反编译工具能帮你确认实际烧进板子的内容。这是我最常用的排错手段之一。dtc -I dtb -O dts -o dump.dts rk3568-evb1-ddr4-v10.dtb或者从板子上把dtb dump出来再反编译# 在U-Boot里先把dtb读入内存再用fatwrite导出 mmc read 0x10000000 0x4000 0x1000 fatwrite mmc 0:1 0x10000000 current.dtb 0x1000然后在主机上反编译dtc -I dtb -O dts -o current.dts current.dtb查看current.dts里的实际配置就能确认烧进去的dtb是不是你想要的那份。我已经不止一次靠这招发现板子上烧的dtb和源码目录里的最新dts根本不是同一个版本这是工作量白费的最常见来源。7. 编译背后的机制C预处理器、DTC工具链和dtb的运行时行为7.1 设备树编译的完整流水线很多人以为dts到dtb就是dtc一步完成其实中间还夹着一层C预处理。OpenHarmony/Linux内核编译dts时实际执行的命令大致是cpp -nostdinc -I include -I arch/arm64/boot/dts -undef -D__DTS__ -x assembler-with-cpp rk3568-evb1-ddr4-v10.dts | dtc -I dts -O dtb -o rk3568-evb1-ddr4-v10.dtb这一步解释了很多现象宏定义直接在dts里用比如GIC_SPI 248 IRQ_TYPE_LEVEL_HIGH里的GIC_SPI和IRQ_TYPE_LEVEL_HIGH都来自头文件。#include能包含其他dtsi因为cpp先处理。#define、#undef等预处理指令在dts里有效。有了这层机制你可以在dts里定义宏来简化重复内容比如#define LED_ON GPIO_ACTIVE_HIGH #define LED_OFF GPIO_ACTIVE_LOW7.2 DTC的语法检查能力和它不管的事DTC会做以下检查节点/属性基本语法错误引用节点xxx是否存在于当前展开后的树里重复定义检查允许追加属性但有些重复会报错但它不会检查compatible字符串是否在内核驱动中存在——编译期完全不会报错运行期才体现为设备不工作寄存器地址是否和真实硬件一致中断号是否正确这一个特点特别重要。也就是说“编译通过”只代表语法没毛病不代表设备树配置是对的。设备树级别的错误往往要到运行时才暴露所以每次改完dts都要做好运行验证不能因为编译过了就掉以轻心。7.3 内核里“未匹配到节点”会发生什么当内核解析dtb时如果某个外设节点的compatible没有匹配到任何驱动它不会报错只是静默地跳过这个节点。所以你在dmesg里看不到任何错误提示但设备就是不工作。从调试角度看常用的办法是ls /sys/firmware/devicetree/base/这个目录直接以文件形式暴露了当前系统实际使用的设备树内容。比如你想确认某个节点是否存在cat /sys/firmware/devicetree/base/leds/work_led/label如果输出work说明节点确实在起作用。如果No such file or directory说明当前系统加载的dtb里根本没有这个节点——那就要回头检查dtb选型和编译烧录链路了。7.4 一个实战中常见的“编译过了但不匹配”场景假设你在dts里加了一个新的I2C传感器节点compatible写的是sensirion,sht3x但内核配置里没开启SHT3X驱动CONFIG_SHT3X不是y也不是m那么即使设备树完全正确驱动也不存在设备节点不会注册。这个问题的排查方式需要同时检查内核.config里有没有CONFIG_SHT3Xydts的compatible和驱动源码里的of_device_id是否一致设备是否真的连接在正确的I2C总线上设备树本身不是万能的它只解决了“硬件怎么描述”的问题驱动编不编译是另一回事。调试时要把这两条线分开考虑别在设备树问题上卡死了结果发现是内核配置没开。8. 覆盖与叠加DTS Overlay机制及OpenHarmony/嵌入式场景的进阶玩法8.1 什么是DTS Overlay它解决什么痛点设备树Overlay是一种“运行时修改设备树”的机制。普通设备树在编译时是静态的板子一个样。Overlay则允许你编译一个补丁式的dtbo文件在系统启动时动态叠加到主设备树上——不需要重新编译整个内核也不需要重新烧录resource分区只需要加载dtbo文件。典型应用场景包括扩展板适配主板上跑的是标准镜像接上一块定制的扩展板比如一个音频子板只需要在启动时加载对应的dtbo不用改主板镜像。原型快速验证改一处外设配置就烧一次resource分区效率太低用dtbo可以在几分钟内完成验证。多配置切换同一块主板上今天接A传感器、明天接B传感器可以通过加载不同dtbo来切换不用维护多套完整dts。在OpenHarmony里U-Boot已经支持在启动阶段加载boot分区或者指定分区下的*.dtbo文件并自动叠加。但系统里的支持程度看具体版本和板型RK3568等主流平台在较新版本里已经能用。8.2 Overlay的语法与编译方法Overlay的语法本质还是设备树只是要在头部做一些特殊声明然后用/plugin/标识这是一个插件格式/dts-v1/; /plugin/; / { fragment0 { target i2c1; __overlay__ { #address-cells 1; #size-cells 0; my_sensor48 { compatible my-vendor,my-sensor; reg 0x48; }; }; }; };这里的fragment0是一个修改片段target i2c1表示要修改的目标节点__overlay__里的内容会叠加到目标节点内。编译方法和普通dts类似但要加-选项告诉dtc生成overlay需要的符号信息dtc - -I dts -O dtb -o my-overlay.dtbo my-overlay.dts注意文件名后缀用dtboU-Boot识别overlay文件时也会依据后缀。8.3 手动加载验证Overlay的两种方法如果你用的是OpenHarmony标准系统可以在系统跑起来后在U-Boot阶段设置setenv overlay_files dtb/my-overlay.dtbo saveenv然后在U-Boot启动时输出日志里应该能看到类似Overlay DTB: dtb/my-overlay.dtbo applied successfully另一种方法是直接在Linux运行时用configfs临时加载如果内核开启了CONFIG_OF_OVERLAYmkdir /configfs/device-tree/overlays/my-overlay cat my-overlay.dtbo /configfs/device-tree/overlays/my-overlay/dtbo加载后立即生效不需要重启。想卸载就rmdir /configfs/device-tree/overlays/my-overlay虽然运行时加载很爽但在嵌入式量产场景里我一般不建议依赖它。因为运行时加载的overlay状态不固化在分区里一旦系统重启就丢失了而且如果overlay之间有资源冲突加载顺序不同可能导致完全不同的结果调试成本会变大。overlay更适合开发调试和扩展板适配产品固化还是应该把配置直接编进主dts。8.4 设备树“叠加”和“覆盖”的边界叠加overlay是把内容合并到目标节点里属性值以overlay为准但已有节点依然保留。覆盖override则是指重新定义整个节点使原节点内容失效。/plugin/做的主要是叠加而顶层dts里的xxx { ... }实际上也是一种编译期的“部分覆盖”。理解这个区别对调试有帮助如果overlay的目标是某个已有节点而该节点的子节点数量、reg属性等已存在叠加时需要确认是否真的“叠加上了”而不是“没变化”或者“整段报错”。遇到这类问题最靠谱的办法还是第6.4节讲的反编译大法把叠加后的最终dtb反编译出来看一遍眼见为实。9. x86平台上的OpenHarmony设备树一个另类的实战观察9.1 x86的固件接口和设备树为什么“不对味”热搜词里有一条“电脑版x86 openharmony”这个方向现在其实越来越受关注。大家印象里的x86电脑是UEFI/ACPI那一套和嵌入式设备树完全是两个世界。但OpenHarmony要支持x86_64尤其是PC级设备启动过程中依然会用到设备树或者说至少要有一个基础的设备树来完成内核启动阶段的信息传递。x86平台的OpenHarmony内核启动方式通常是Uboot引导加上dtb传参的模式。但x86平台本身硬件枚举方式PCI枚举、ACPI和设备树是两套体系所以设备树在x86上更多是起“引导壳”的作用描述内存布局、作为启动参数载体、指定串口控制台等。外设的实际初始化大部分时候还是交给PCI子系统去处理。这意味着你在x86版OpenHarmony上调试时不太会遇到“某外设需要改dts才能用”的情况除非是很特殊的嵌入式外设大部分设备识别走的是PCI/ACPI通道。所以x86的dts文件往往非常精简可能只有几十行。9.2 x86平台设备树里都有什么拿一个x86 OpenHarmony开发环境举例dts文件一般包含这么几块/dts-v1/; / { model OpenHarmony x86_64 PC; compatible intel,generic, x86; #address-cells 2; #size-cells 2; memory1000000 { device_type memory; reg 0x0 0x01000000 0x0 0x80000000; }; chosen { stdout-path uart0; bootargs root/dev/sda2 consolettyS0,115200 consoletty0; }; uart0: ns165503f8 { compatible ns16550a; reg 0x0 0x3f8 0x0 0x8; }; };注意这里#address-cells和#size-cells都是2因为x86是64位地址空间要描述超过4GB的内存必须用两个32位整数拼一个64位地址。很多从ARM转向x86的开发者第一次见到reg 0x0 0x01000000 0x0 0x80000000会懵其实就是64位地址表示法的具体体现。9.3 对x86平台的一点个人看法如果你是从嵌入式转过来玩x86版OpenHarmony别把设备树当成主要矛盾x86世界的重点在于UEFI引导、grub配置、根文件系统分区布局和显卡驱动适配。设备树在x86上更像一个“辅助道具”而不是像ARM那样决定外设生死的核心配置。换个角度看恰恰因为x86平台设备树简单用来练习设备树语法、理解节点结构、跑一遍dtc编译流程反而非常合适。我建议刚入门OpenHarmony设备树的同学可以先在x86模拟环境或实体机上把dts编译、反编译、uboot传参这套流程跑通再回到RK3568等ARM平台上做外设适配思路会清晰很多。10. 最后的一点个人经验学好设备树等于掌握了OpenHarmony硬件适配的“通行证”设备树DTS看似只是内核启动阶段的一个配置数据但它是OpenHarmony所有硬件适配工作的地基。无论是RK3568开发板的外设点亮、新板型的bring-up、还是扩展板的快速适配最终都要落实到设备树的增删改查上。从学习路径上看我的建议是先掌握基础语法和节点概念然后在自己的开发板上做“增量实验”——每次只添加一个节点比如先GPIO点灯、再挂I2C传感器、再尝试添加音频Codec或者LCD屏。不要怕烧板子纯软件层面的dts修改最多导致系统启动异常重新烧录就能恢复。调试工具方面除了编译/反编译工具我建议随时把三个东西放在手边串口控制台日志看U-Boot和内核启动信息、/sys/firmware/devicetree/base目录运行时查看实际生效的设备树内容、以及dmesg查驱动probe的踪迹。这三样组合起来能应对绝大多数设备树相关问题。最后想提醒一件事设备树本身只是一份“静态描述”它不会主动拉起驱动驱动也不会因为设备树描述错误而报警——所有问题都是静默的、温和的但也因此容易被忽视。维护好你的设备树版本、每次修改都留好记录、改完就验证这些看似笨拙的习惯恰恰是设备树开发最可靠的方法论。
1. 设备树DTS到底解决了什么问题从一次外设点不亮的排查说起先讲个我自己的经历。去年刚接触OpenHarmony开发板时拿了一块RK3568的开发板按照官方文档编译完镜像烧进去系统起来了但串口控制台死活没有输出。查了半小时最后发现是uboot传参里的dtb文件名和板子实际型号对不上导致内核启动阶段根本没匹配到对应的设备树。这种问题在OpenHarmony开发里太常见了——板子拿到了镜像能烧但外设全看设备树脸色。这也是我这篇教程要解决的第一个问题不懂设备树你连系统怎么找到你的硬件都不知道。设备树Device Tree简称DTS在OpenHarmony系统里的角色简单说就是一份给内核看的“硬件说明书”。Linux/OpenHarmony内核是个通用软件它不知道自己跑在哪块板子上CPU是什么型号、内存多大、I2C总线上挂了几个传感器、GPIO哪个引脚控制LED——这些信息全都写在设备树里。内核启动时读取这份说明书才知道怎么初始化硬件。相比传统的LinuxOpenHarmony对设备树的依赖其实有过之而无不及。因为OpenHarmony要支持多种芯片平台RK、HiSilicon、Allwinner等还要兼顾标准系统和小型系统硬件差异比单纯某个Linux发行版大得多。而设备树恰恰是屏蔽这种差异的关键机制。很多刚接触OpenHarmony的开发者尤其是以前主要做单片机或者裸机开发的对设备树的态度都是“能用就行改坏了再说”。但实际开发中你遇到的外设不识别、驱动加载失败、GPIO冲突、甚至系统启动崩溃十有八九都跟设备树配置有关。如果你打算深度玩OpenHarmony硬件开发设备树是绕不过去的第一道关。这篇教程我会从设备树的核心概念开始讲然后结合RK3568平台最常见的“多设备树选择”问题做一次完整的实操排查再讲怎么从零写一个设备树节点、怎么编译验证最后聊一聊DTS背后的编译机制和一些进阶玩法。内容比较多但保证每一段都是能直接用到实战里的。2. 设备树的三个核心概念DTS、DTC、DTB以及它们和OpenHarmony的关系2.1 一份设备树源文件的完整构成先看一个最简的设备树源文件示例感受一下语法风格/dts-v1/; / { model OpenHarmony RK3566 Evaluation Board; compatible rockchip,rk3566, rockchip,rk3568; chosen { stdout-path uart2; }; memory10000000 { device_type memory; reg 0x10000000 0x80000000; }; leds { compatible gpio-leds; work_led: led0 { label work; gpios gpio0 RK_PB2 GPIO_ACTIVE_HIGH; }; }; uart2: serialfe650000 { compatible rockchip,rk3568-uart, snps,dw-apb-uart; reg 0xfe650000 0x100; interrupts GIC_SPI 253 IRQ_TYPE_LEVEL_HIGH; clocks cru SCLK_UART2, cru PCLK_UART2; clock-names baudclk, apb_pclk; status okay; }; uart2 { status okay; }; };这份文件里涵盖了设备树的核心语法点/dts-v1/;版本声明固定写法表示使用设备树v1语法。/ { ... }根节点所有设备节点都在它下面代表整个硬件平台。model板子型号描述字符串用来在日志里标识这块板子。compatible兼容性标识内核/驱动靠它匹配节点和驱动。这个属性是设备树里最关键的属性后面专门讲。chosen特殊节点用于传递内核启动参数比如stdout-path指定控制台串口。memory内存节点reg属性描述内存起始地址和大小。RK3568的内存基地址是0x10000000这在Rockchip平台上是个典型值。leds自定义节点比如这里用gpio-leds驱动来描述一个工作指示灯。gpios属性里引用了gpio0这个外部节点。2.2 DTS到DTB的编译过程设备树源文件.dts不能直接被内核读取需要编译成二进制格式的DTBDevice Tree Blob。这个编译工作由一个叫DTCDevice Tree Compiler的工具完成命令很简单dtc -I dts -O dtb -o rk3568-evb.dtb rk3568-evb.dts在OpenHarmony的编译体系里你通常不需要手动执行dtc命令。标准系统的编译脚本会遍历kernel/linux/arch/arm64/boot/dts/rockchip/目录下的所有dts文件自动编译生成对应的dtb。你只需要在编译配置里指定目标板子的dts文件名就行。**为什么需要转换成DTB而不是直接读DTS**一个原因是二进制格式更紧凑内核解析更快另一个原因是DTS源文件里允许包含#include等预处理指令经过C预处理器展开后的完整源文件才能编译成DTB。在OpenHarmony源码里很多dts文件开头都有类似这样的写法#include rk3568.dtsi #include rk3568-evb.ddr4-2rank-32bit-1044m.dtsi这里.dtsi就是设备树头文件类似C语言里的.h用来放SoC通用定义和板级公共配置。实际编译时预处理器会先把这些include展开形成一份完整的dts内容再交给dtc编译。2.3 DTB在系统启动流程中的传递路径搞清楚DTB的传递路径是理解“为什么编译了dtb还要单独烧录”的关键。OpenHarmony标准系统RK3568平台的典型启动流程是U-Boot启动读取分区表从boot分区加载内核镜像boot.img。U-Boot加载DTB从resource分区RK3568平台习惯或boot分区的dtb区域读取dtb文件到内存。U-Boot传参把dtb所在内存地址通过寄存器r2传给内核同时通过bootargs里的root等参数告诉内核根文件系统在哪。内核解析DTB内核启动时解析dtb遍历所有节点和驱动注册表中的compatible属性做匹配匹配成功的驱动就会执行probe函数初始化硬件。这个链路里最容易出问题的是第2步。RK3568的U-Boot会尝试从指定位置加载*.dtb文件如果你的板子上烧录的dtb文件名和U-Boot配置的不一样——比如U-Boot期待的是rk3568-evb1-ddr4-v10.dtb你烧的却是rk3568-evb.dtb——那就是我文章开头说的那种情况系统起得来但外设全乱套。OpenHarmony的kernel镜像里其实打包了多个dtb在kernel/linux/arch/arm64/boot/dts/rockchip/目录下你会发现同一颗RK3568芯片衍生出了十几个甚至几十个dts文件有rk3568-evb1-ddr4-v10.dts、rk3568-evb2-lpddr4-v10.dts、rk3568-evb6-lpddr4x-v10.dts等等。这就是热搜词里“openharmony的rk3568有许多设备树到底咋选”这个问题的由来。这个问题的标准排查链路我放在第4章专门讲。2.4 compatible属性设备树和驱动之间的“接头暗号”如果说设备树是一台电话交换机那compatible属性就是每个分机的号码。内核里的platform_driver通过of_match_table和节点compatible属性做字符串匹配匹配成功才绑定。以RK3568的串口驱动为例设备树里写compatible rockchip,rk3568-uart, snps,dw-apb-uart;内核驱动里写static const struct of_device_id dw8250_of_match[] { { .compatible snps,dw-apb-uart }, { .compatible rockchip,rk3568-uart }, {} };匹配规则是从左到右遍历设备树里的compatible字符串列表只要有一个字符串和驱动里的of_device_id表匹配上驱动就接管这个设备。因此设备树里compatible写成rockchip,rk3568-uart, snps,dw-apb-uart的意思是优先用瑞芯微的专用驱动如果有的话否则退回到通用的Synopsys DesignWare UART驱动。实战建议在你新增一个外设节点时compatible的值最好从要用的驱动源码里抄而不是自己凭空编一个。查代码的时候搜索of_device_id结构体数组看驱动支持哪些字符串。这一步能避免大量“驱动加载了但设备没匹配上”的诡异问题。3. 设备树的继承与叠加机制从SoC通用定义到板级定制的完整链路3.1 dtsi公共文件与dts板级文件的拆分逻辑我见过不少新手拿到的第一个开发板是RK3568然后打开rk3568-evb.dts一看好几百行立马头大。但你看懂了拆分逻辑之后会觉得这套体系其实非常优雅。设备树从设计上就分了两层SoC层级在rk3568.dtsi里定义这颗芯片本身拥有的所有硬件资源比如CPU核心、GIC中断控制器、CRU时钟模块、I2C/SPI/UART控制器、DDR控制器等。这些资源在同一颗芯片上不管做什么板子都一样所以放在公共文件里用rk3568.dtsi统一描述。板级层级在rk3568-evb.dts里只关心这块具体的开发板用到了哪些外设、怎么连的。比如EVB板子上挂了哪个型号的eMMC、用的DDR是哪种、WiFi芯片挂在哪个SDIO口、GPIO怎么复用等。这种拆分带来一个好处同一颗SoC的开发板dtsi文件基本不用动只需要根据板子改dts。RK3568的EVB系列开发板几十个型号底层的rk3568.dtsi是同一份。实际上OpenHarmony的RK3568相关dts通常还会再引入一层内存相关的dtsi比如#include rk3568-evb.dtsi #include rk3568-evb-ddr4-2rank-32bit-1044m.dtsi内存参数容量、rank数、位宽不同对应的初始化参数也不同。这也解释了为什么同一个evb板子会有ddr4-2rank-32bit-1044m、lpddr4-2rank-32bit-936m等多个变体——内存芯片规格不同设备树描述就要跟着变。3.2 根节点、子节点和引用节点设备树里的“文件系统”设备树的节点结构很像文件系统的目录树根节点/相当于根目录。每个节点相当于一个目录或文件。节点可以有子节点也可以有属性键值对。属性值类型包括字符串、字符串列表、32位整数数组...、64位整数数组...加#address-cells定义、二进制数据。节点引用的语法理解起来也不难uart2 { status okay; };这里的uart2表示引用之前定义过的uart2: serialfe650000节点。这个写法的本质是在原来的节点上追加或修改属性而不是重新创建一个节点。所以上面的写法等同于在uart2节点里加上status okay。这种“先定义后修改”的模式在板级dts里特别多。SoC级dtsi里把某个外设默认设为status disabled因为不是每块板子都会用到所有外设板级dts里再通过xxx { status okay; }把它打开。如果你在调试某个外设时发现驱动不工作优先检查status属性——这是我在支持开发者时遇到最高频的问题之一。再看gpios gpio0 RK_PB2 GPIO_ACTIVE_HIGH这个属性。尖括号里由三个值组成gpio0表示引用gpio0节点实际上引用的是某个GPIO控制器的phandle设备树内部用数字标识节点的引用关系RK_PB2是GPIO组和引脚编号RK_PB2就是GPIO0组的B2号引脚换算成数字在内核头文件里定义GPIO_ACTIVE_HIGH表示高电平有效。这类宏定义在dts里可以直接用因为编译设备树时C预处理器会先展开这些宏定义它们通常来自include/dt-bindings/gpio/gpio.h等路径。3.3 节点命名规则后面的地址到底是什么设备树节点的命名有规范节点名单元地址。比如cpu0CPU核心0serialfe650000UART控制器寄存器基地址在0xfe650000i2cfe5a0000I2C控制器后面的地址通常是该设备在总线上的寄存器基地址或者片选地址用于区分同类型的不同实例。如果节点没有地址比如根节点就不带。这个命名规则看着简单但有一个常见误区节点名不参与compatible匹配系统真正认的是compatible属性和节点的reg地址。也就是说你可以把serialfe650000改名为my_uartfe650000驱动照样能工作虽然强烈不建议这么干因为驱动匹配靠的是compatible。3.4 地址编码规则address-cells和size-cells设备树的reg属性用来描述设备的地址空间信息但是“地址”是多少位、“长度”是多少位得由父节点的#address-cells和#size-cells属性来声明。看一个典型例子soc { #address-cells 1; #size-cells 1; uart0: serialfe650000 { reg 0xfe650000 0x100; }; };#address-cells 1表示reg里地址用一个32位整数描述#size-cells 1表示reg里长度用一个32位整数描述。所以reg 0xfe650000 0x100的意思是寄存器基地址是0xfe650000寄存器区域大小是0x100字节。如果某个总线下挂的设备地址是64位的就要设置#address-cells 2。忘记调整address-cells导致设备地址解析错误是另一个比较容易踩的坑。RK3568的pinctrl节点里大量用到这类地址描述如果地址解析不对GPIO复用和引脚配置就会乱套。4. RK3568平台多设备树的选型排查OpenHarmony启动时dtb到底该烧哪一份4.1 问题现场同一个镜像烧进不同板子外设行为完全不同热搜词里那个“openharmony的rk3568有许多设备树到底咋选”的问题我几乎在每次OpenHarmony硬件适配培训里都会被问到。典型的场景是这样的从官方下载了RK3568标准系统的镜像烧录到EVB1开发板上系统能正常启动。但同一份镜像烧到自己画的板子上或者另一款EVB型号的板子上可能系统起不来或者起来了但是以太网不通、HDMI不显示、触摸屏不响应。原因非常明确系统启动时加载的dtb只包含了一种板级配置而不同板子的外设连接、GPIO复用、内存配置不一样这份配置无法同时兼容所有硬件。你需要的不是“换一个神奇镜像”而是“找到和自己板子匹配的那份dtb”。4.2 U-Boot的dtb搜索规则与RK3568的多dtb打包机制要解决选型问题先要知道U-Boot是怎么找到dtb的。RK3568平台上OpenHarmony的U-Boot默认会去resource分区加载*.dtb文件。这个resource分区是一个FAT格式的小分区专门存放开机需要用到的资源文件包括dtb、logo图片等。烧录工具烧镜像时会把编译产物里的多个dtb文件拷贝进resource分区的dtb/子目录里。U-Boot的rockchip_read_dtb_file逻辑大致是读取resource分区里dtb/目录下的所有文件列表。遍历每个文件名的前缀和编译时写入U-Boot环境变量或头信息里的“板级标识”通常是dts文件名中的板子型号字符串做模糊匹配。匹配成功就加载这份dtb到内存传给内核。问题就出在匹配规则是“模糊”的比如板级标识设置的是rk3568-evb1-ddr4-v10那它可能会匹配上rk3568-evb1-ddr4-v10.dtb也可能会匹配不上而是匹配到前面字符串相同的另一个文件。实际看日志时你会在串口控制台看到类似Failed to find devicetree for ...或Found DTB at ...的信息。这些日志就是排查的关键线索。4.3 排查链路从串口日志到dtb文件名的完整而实操的排查路径我在实际项目里总结了一套排查步骤照着走基本能定位90%的多dtb不匹配问题。第一步确认当前系统实际加载的dtb串口控制台U-Boot阶段输入printenv dtb_name或者看启动日志里类似这样的一行Trying to find DTB in resource partition: dtb/rk3568-evb1-ddr4-v10.dtb, trying 3 times...如果dtb_name是空或者和你的板子不符可以手动指定setenv dtb_name dtb/rk3568-evb1-ddr4-v10.dtb saveenv reset第二步从resource分区读取实际文件列表在U-Boot里执行mmc dev 0 fatls mmc 0:1 dtb注意设备号和分区号根据你的存储介质调整可能是mmc 0:1也可能是mtd 0之类RK3568一般以eMMC的mmc0为主如果dtb/目录下有多个文件直接对比你的板型和文件名找最接近的那个。第三步在dts源码里核对板级差异找到和你的板子最接近的dts文件后打开源码重点对比以下内容model和compatible板子型号标识是否符合。内存dtsiDDR容量、rank、位宽是否和你的硬件一致。比如你板上用的是2GB LPDDR4但dts引入的是4GB DDR4配置那系统虽然能启动但可用的内存可能只有一半甚至启动卡死。外设的status板子上实际存在的硬件在dts里是不是status okay。比如你的板子引出了以太网口但dts里对应节点是disabled网口肯定不工作。第四步修改dts并重新编译烧录核心思路不要试图去改U-Boot匹配逻辑直接在源码层面把dts改成和你板子一致然后重新编译dtb烧进resource分区。在OpenHarmony标准系统的dts目录通常是kernel/linux/arch/arm64/boot/dts/rockchip/下找到你的板型dts或者直接以某个现有的dts为模板复制一个新文件做板级定制。例如cp rk3568-evb1-ddr4-v10.dts my-board.dts然后修改my-board.dts里的model、内存配置、外设status等在编译配置里加上这个新dts的编译目标重新编译生成my-board.dtb烧录进resource分区。4.4 一份排查记录表格快速对照你的问题场景这里整理一份我在支持开发者时常用的对照表方便快速定位问题方向。启动现象可能原因优先排查项完全没有启动日志DTB没加载或加载失败U-Boot停在加载阶段resource分区是否有dtb、dtb_name是否配置正确启动到内核早期卡死DTB里的内存配置和实际DDR不匹配核对引入的DDR dtsi参数系统能启动但某外设不工作dts里外设节点是disabled或者compatible不匹配检查外设节点status、GPIO复用配置系统启动但识别不到eMMC/SD卡存储控制器节点配置不正确或引脚复用冲突检查sdmmc/sdio相关节点和pinctrl显示正常但触摸无反应I2C地址不对或者GPIO中断号配置错误核对触摸屏节点的i2c地址和中断引脚能进系统但串口控制台无输出chosen节点的stdout-path指向错误串口检查stdout-path引用的串口节点是否存在且okay4.5 我自己总结的选型经验在RK3568多设备树选型上我的实操经验是不要迷信“官方默认”三个字一定要根据自己板子的硬件配置做核对。即使是同一款EVB板不同批次可能内存芯片换了型号对应的内存初始化参数dtsi也可能要变。再有就是每次只改一个变量。比如你想适配一块新板子先以官方最接近的dts为底子只改内存配置启动确认正常后再逐个打开外设节点。一次改一堆节点出了问题你根本不知道是哪个改动导致的。5. 手写一个设备树节点从GPIO点灯到I2C传感器全过程的实战拆解5.1 新增一个GPIO控制节点的完整步骤光说不练假把式。这一节我带大家从零写一个设备树节点实现一个最基础的功能控制板子上的一个LED灯。先看最终要加到板级dts里的节点内容pinctrl { leds { work_led_gpio: work-led-gpio { rockchip,pins 0 RK_PB2 RK_FUNC_GPIO pcfg_pull_none; }; }; }; / { leds { compatible gpio-leds; work_led: led-0 { label work; gpios gpio0 RK_PB2 GPIO_ACTIVE_HIGH; linux,default-trigger heartbeat; }; }; };分解一下这个节点做了哪些事第一部分pinctrl引脚复用pinctrl节点下定义了一个work-led-gpio子节点表示要把GPIO0组的B2引脚复用为GPIO功能。rockchip,pins 0 RK_PB2 RK_FUNC_GPIO pcfg_pull_none里四个参数分别是bank号0、引脚号RK_PB2、功能复用选择RK_FUNC_GPIO表示作为普通GPIO用、上下拉配置无上下拉。如果不做这个复用配置内核可能不知道这个引脚当前应该是什么功能。pinctrl这种写法是向已有的pinctrl节点追加子节点。板级dts里通常都有现成的pinctrl追加块你可以在里面增加自己的子节点也可以新建一个pinctrl块编译器会把它们合并。第二部分gpio-leds设备节点compatible gpio-leds是内核里的标准LED驱动匹配后会自动注册一个LED设备。gpios属性描述了具体的GPIO引脚和有效电平linux,default-trigger heartbeat表示把这个LED作为心跳灯使用。这个节点写好后编译烧录系统启动后你会看到控制台里出现leds: work设备节点对应/sys/class/leds/work路径可以通过echo 255 /sys/class/leds/work/brightness控制亮度echo heartbeat /sys/class/leds/work/trigger切换触发模式。5.2 挂一个I2C设备以温湿度传感器为例GPIO之后上一个稍微复杂点的例子在I2C总线上挂载一个SHT30温湿度传感器。首先在dts里找到I2C总线的节点通常在rk3568.dtsi里已经有定义比如i2c1: i2cfe5a0000 { compatible rockchip,rk3568-i2c, rockchip,rk3399-i2c; reg 0xfe5a0000 0x1000; interrupts GIC_SPI 248 IRQ_TYPE_LEVEL_HIGH; #address-cells 1; #size-cells 0; status disabled; };板级dts里通過i2c1打开它并挂载SHT30子节点i2c1 { status okay; clock-frequency 400000; sht3044 { compatible sensirion,sht3x; reg 0x44; status okay; }; };几个关键点clock-frequency 400000设置I2C时钟频率为400kHz快速模式。如果传感器不支持这个频率可以改为100000。sht3044子节点名44是7位I2C地址的十六进制表示不带读写位。reg 0x44I2C设备地址。这里的reg代表设备在总线上的地址不是寄存器地址因为父节点i2c1的#size-cells 0所以只有一个描述地址的整数。compatible要和驱动里定义的一致。SHT30在Linux内核里的驱动compatible通常是sensirion,sht3x。我把这个节点加进dts后重新编译烧录系统启动日志里会多出类似这样的内容i2c 1: adapter at 0xfe5a0000 sht3x 1-0044: sensor connected如果你在/sys/bus/i2c/devices/1-0044/下看到节点说明挂载成功可以直接用内核提供的接口或者自己写个应用读取温湿度。5.3 那些只有踩过坑才知道的注意事项注意1I2C设备地址不要搞错位数。reg 0x44里的0x44是7位地址但有些传感器手册上写的是8位地址比如0x88需要把最低位去掉。I2C 8位地址0x88右移一位就是7位地址0x44。这是传感器dts适配里最常见的错之一。**注意2pinctrl配置不是可选项。**GPIO和I2C节点都依赖pinctrl配置才能正确工作因为SoC的同一个引脚往往有多路复用功能。如果I2C引脚的复用模式不对总线上的波形就是乱的。升级内核版本后pinctrl配置格式可能变化所以看旧代码改dts时一定要确认pinctrl子节点写法是否对应当前内核版本。**注意3status属性的“默认值”陷阱。**很多外设节点在dtsi里默认是disabled这是为了省电和避免引脚冲突。如果你发现驱动已经probe了但设备没信号先检查status有没有被正确设置为okay。另外还要区分节点的status和子设备的status两者是独立的。**注意4时钟相关的属性别乱抄。**I2C、UART这类高速外设通常需要配置时钟源和频率比如clocks cru SCLK_UART2。如果你从一个芯片型号抄到另一个芯片型号时钟ID很可能对不上。RK3568的时钟定义都在include/dt-bindings/clock/rk3568-cru.h里抄之前先去这个文件里确认宏存在。6. dtb的编译位置、内核配置项与resource分区烧录的实操说明6.1 OpenHarmony标准系统里dts文件放在哪里很多从纯Linux转过来的同学习惯在Linux内核源码目录里找dts文件。OpenHarmony标准系统也是这个思路但路径稍有不同。以RK3568为例OpenHarmony标准系统的内核代码在kernel/linux/目录下实际dts文件位置大约在kernel/linux/arch/arm64/boot/dts/rockchip/具体文件名就是rk3568-evb1-ddr4-v10.dts这类。注意OpenHarmony不同版本3.2、4.0、4.1等的路径可能略有差异但基本都在同样的目录结构下。如果你用的是DevEco Studio或者hb工具构建的latest版本可以在源码根目录执行find . -path *boot/dts/rockchip/rk3568*.dts | head -20直接定位到所有RK3568相关dts文件。6.2 手动编译dtb的命令与一键脚本在OpenHarmony源码环境下手动编译单个dtb可以用cd kernel/linux make ARCHarm64 rockchip_linux_defconfig make ARCHarm64 dtbs这会编译所有设备树。如果只想编译某一个make ARCHarm64 rk3568-evb1-ddr4-v10.dtb编译产物在arch/arm64/boot/dts/rockchip/rk3568-evb1-ddr4-v10.dtb。如果只是验证语法不依赖内核配置可以用dtc单独编译./scripts/dtc/dtc -I dts -O dtb -o test.dtb my-board.dts注意OpenHarmony内核源码里自带了dtc工具scripts/dtc/dtc不用额外安装。6.3 烧录到resource分区的方法编译好的dtb要放到resource分区才能被U-Boot找到。常见做法有两种方法一重新打包整个镜像在OpenHarmony构建系统里resource分区的镜像一般叫resource.img打包时会把vendor或特定目录下的dtb文件收集进去。具体脚本路径在build系统中通常在device/board/rockchip/下。修改dts后重新执行构建resource.img会自动更新。方法二直接更新已烧录板子上的resource分区如果你不想重新打包整个系统镜像可以用RKDevTool等烧录工具单独烧写resource分区。在工具里选择resource分区的镜像文件路径比如out/.../resource.img单独烧写该分区即可。也可以用U-Boot的命令把新的dtb写入fatwrite mmc 0:1 $loadaddr dtb/rk3568-evb1-ddr4-v10.dtb 0x100000x10000是文件大小要根据实际大小调整这里只是示例。6.4 dtb反编译遇到问题时的“x光机”调试dtb问题时反编译工具能帮你确认实际烧进板子的内容。这是我最常用的排错手段之一。dtc -I dtb -O dts -o dump.dts rk3568-evb1-ddr4-v10.dtb或者从板子上把dtb dump出来再反编译# 在U-Boot里先把dtb读入内存再用fatwrite导出 mmc read 0x10000000 0x4000 0x1000 fatwrite mmc 0:1 0x10000000 current.dtb 0x1000然后在主机上反编译dtc -I dtb -O dts -o current.dts current.dtb查看current.dts里的实际配置就能确认烧进去的dtb是不是你想要的那份。我已经不止一次靠这招发现板子上烧的dtb和源码目录里的最新dts根本不是同一个版本这是工作量白费的最常见来源。7. 编译背后的机制C预处理器、DTC工具链和dtb的运行时行为7.1 设备树编译的完整流水线很多人以为dts到dtb就是dtc一步完成其实中间还夹着一层C预处理。OpenHarmony/Linux内核编译dts时实际执行的命令大致是cpp -nostdinc -I include -I arch/arm64/boot/dts -undef -D__DTS__ -x assembler-with-cpp rk3568-evb1-ddr4-v10.dts | dtc -I dts -O dtb -o rk3568-evb1-ddr4-v10.dtb这一步解释了很多现象宏定义直接在dts里用比如GIC_SPI 248 IRQ_TYPE_LEVEL_HIGH里的GIC_SPI和IRQ_TYPE_LEVEL_HIGH都来自头文件。#include能包含其他dtsi因为cpp先处理。#define、#undef等预处理指令在dts里有效。有了这层机制你可以在dts里定义宏来简化重复内容比如#define LED_ON GPIO_ACTIVE_HIGH #define LED_OFF GPIO_ACTIVE_LOW7.2 DTC的语法检查能力和它不管的事DTC会做以下检查节点/属性基本语法错误引用节点xxx是否存在于当前展开后的树里重复定义检查允许追加属性但有些重复会报错但它不会检查compatible字符串是否在内核驱动中存在——编译期完全不会报错运行期才体现为设备不工作寄存器地址是否和真实硬件一致中断号是否正确这一个特点特别重要。也就是说“编译通过”只代表语法没毛病不代表设备树配置是对的。设备树级别的错误往往要到运行时才暴露所以每次改完dts都要做好运行验证不能因为编译过了就掉以轻心。7.3 内核里“未匹配到节点”会发生什么当内核解析dtb时如果某个外设节点的compatible没有匹配到任何驱动它不会报错只是静默地跳过这个节点。所以你在dmesg里看不到任何错误提示但设备就是不工作。从调试角度看常用的办法是ls /sys/firmware/devicetree/base/这个目录直接以文件形式暴露了当前系统实际使用的设备树内容。比如你想确认某个节点是否存在cat /sys/firmware/devicetree/base/leds/work_led/label如果输出work说明节点确实在起作用。如果No such file or directory说明当前系统加载的dtb里根本没有这个节点——那就要回头检查dtb选型和编译烧录链路了。7.4 一个实战中常见的“编译过了但不匹配”场景假设你在dts里加了一个新的I2C传感器节点compatible写的是sensirion,sht3x但内核配置里没开启SHT3X驱动CONFIG_SHT3X不是y也不是m那么即使设备树完全正确驱动也不存在设备节点不会注册。这个问题的排查方式需要同时检查内核.config里有没有CONFIG_SHT3Xydts的compatible和驱动源码里的of_device_id是否一致设备是否真的连接在正确的I2C总线上设备树本身不是万能的它只解决了“硬件怎么描述”的问题驱动编不编译是另一回事。调试时要把这两条线分开考虑别在设备树问题上卡死了结果发现是内核配置没开。8. 覆盖与叠加DTS Overlay机制及OpenHarmony/嵌入式场景的进阶玩法8.1 什么是DTS Overlay它解决什么痛点设备树Overlay是一种“运行时修改设备树”的机制。普通设备树在编译时是静态的板子一个样。Overlay则允许你编译一个补丁式的dtbo文件在系统启动时动态叠加到主设备树上——不需要重新编译整个内核也不需要重新烧录resource分区只需要加载dtbo文件。典型应用场景包括扩展板适配主板上跑的是标准镜像接上一块定制的扩展板比如一个音频子板只需要在启动时加载对应的dtbo不用改主板镜像。原型快速验证改一处外设配置就烧一次resource分区效率太低用dtbo可以在几分钟内完成验证。多配置切换同一块主板上今天接A传感器、明天接B传感器可以通过加载不同dtbo来切换不用维护多套完整dts。在OpenHarmony里U-Boot已经支持在启动阶段加载boot分区或者指定分区下的*.dtbo文件并自动叠加。但系统里的支持程度看具体版本和板型RK3568等主流平台在较新版本里已经能用。8.2 Overlay的语法与编译方法Overlay的语法本质还是设备树只是要在头部做一些特殊声明然后用/plugin/标识这是一个插件格式/dts-v1/; /plugin/; / { fragment0 { target i2c1; __overlay__ { #address-cells 1; #size-cells 0; my_sensor48 { compatible my-vendor,my-sensor; reg 0x48; }; }; }; };这里的fragment0是一个修改片段target i2c1表示要修改的目标节点__overlay__里的内容会叠加到目标节点内。编译方法和普通dts类似但要加-选项告诉dtc生成overlay需要的符号信息dtc - -I dts -O dtb -o my-overlay.dtbo my-overlay.dts注意文件名后缀用dtboU-Boot识别overlay文件时也会依据后缀。8.3 手动加载验证Overlay的两种方法如果你用的是OpenHarmony标准系统可以在系统跑起来后在U-Boot阶段设置setenv overlay_files dtb/my-overlay.dtbo saveenv然后在U-Boot启动时输出日志里应该能看到类似Overlay DTB: dtb/my-overlay.dtbo applied successfully另一种方法是直接在Linux运行时用configfs临时加载如果内核开启了CONFIG_OF_OVERLAYmkdir /configfs/device-tree/overlays/my-overlay cat my-overlay.dtbo /configfs/device-tree/overlays/my-overlay/dtbo加载后立即生效不需要重启。想卸载就rmdir /configfs/device-tree/overlays/my-overlay虽然运行时加载很爽但在嵌入式量产场景里我一般不建议依赖它。因为运行时加载的overlay状态不固化在分区里一旦系统重启就丢失了而且如果overlay之间有资源冲突加载顺序不同可能导致完全不同的结果调试成本会变大。overlay更适合开发调试和扩展板适配产品固化还是应该把配置直接编进主dts。8.4 设备树“叠加”和“覆盖”的边界叠加overlay是把内容合并到目标节点里属性值以overlay为准但已有节点依然保留。覆盖override则是指重新定义整个节点使原节点内容失效。/plugin/做的主要是叠加而顶层dts里的xxx { ... }实际上也是一种编译期的“部分覆盖”。理解这个区别对调试有帮助如果overlay的目标是某个已有节点而该节点的子节点数量、reg属性等已存在叠加时需要确认是否真的“叠加上了”而不是“没变化”或者“整段报错”。遇到这类问题最靠谱的办法还是第6.4节讲的反编译大法把叠加后的最终dtb反编译出来看一遍眼见为实。9. x86平台上的OpenHarmony设备树一个另类的实战观察9.1 x86的固件接口和设备树为什么“不对味”热搜词里有一条“电脑版x86 openharmony”这个方向现在其实越来越受关注。大家印象里的x86电脑是UEFI/ACPI那一套和嵌入式设备树完全是两个世界。但OpenHarmony要支持x86_64尤其是PC级设备启动过程中依然会用到设备树或者说至少要有一个基础的设备树来完成内核启动阶段的信息传递。x86平台的OpenHarmony内核启动方式通常是Uboot引导加上dtb传参的模式。但x86平台本身硬件枚举方式PCI枚举、ACPI和设备树是两套体系所以设备树在x86上更多是起“引导壳”的作用描述内存布局、作为启动参数载体、指定串口控制台等。外设的实际初始化大部分时候还是交给PCI子系统去处理。这意味着你在x86版OpenHarmony上调试时不太会遇到“某外设需要改dts才能用”的情况除非是很特殊的嵌入式外设大部分设备识别走的是PCI/ACPI通道。所以x86的dts文件往往非常精简可能只有几十行。9.2 x86平台设备树里都有什么拿一个x86 OpenHarmony开发环境举例dts文件一般包含这么几块/dts-v1/; / { model OpenHarmony x86_64 PC; compatible intel,generic, x86; #address-cells 2; #size-cells 2; memory1000000 { device_type memory; reg 0x0 0x01000000 0x0 0x80000000; }; chosen { stdout-path uart0; bootargs root/dev/sda2 consolettyS0,115200 consoletty0; }; uart0: ns165503f8 { compatible ns16550a; reg 0x0 0x3f8 0x0 0x8; }; };注意这里#address-cells和#size-cells都是2因为x86是64位地址空间要描述超过4GB的内存必须用两个32位整数拼一个64位地址。很多从ARM转向x86的开发者第一次见到reg 0x0 0x01000000 0x0 0x80000000会懵其实就是64位地址表示法的具体体现。9.3 对x86平台的一点个人看法如果你是从嵌入式转过来玩x86版OpenHarmony别把设备树当成主要矛盾x86世界的重点在于UEFI引导、grub配置、根文件系统分区布局和显卡驱动适配。设备树在x86上更像一个“辅助道具”而不是像ARM那样决定外设生死的核心配置。换个角度看恰恰因为x86平台设备树简单用来练习设备树语法、理解节点结构、跑一遍dtc编译流程反而非常合适。我建议刚入门OpenHarmony设备树的同学可以先在x86模拟环境或实体机上把dts编译、反编译、uboot传参这套流程跑通再回到RK3568等ARM平台上做外设适配思路会清晰很多。10. 最后的一点个人经验学好设备树等于掌握了OpenHarmony硬件适配的“通行证”设备树DTS看似只是内核启动阶段的一个配置数据但它是OpenHarmony所有硬件适配工作的地基。无论是RK3568开发板的外设点亮、新板型的bring-up、还是扩展板的快速适配最终都要落实到设备树的增删改查上。从学习路径上看我的建议是先掌握基础语法和节点概念然后在自己的开发板上做“增量实验”——每次只添加一个节点比如先GPIO点灯、再挂I2C传感器、再尝试添加音频Codec或者LCD屏。不要怕烧板子纯软件层面的dts修改最多导致系统启动异常重新烧录就能恢复。调试工具方面除了编译/反编译工具我建议随时把三个东西放在手边串口控制台日志看U-Boot和内核启动信息、/sys/firmware/devicetree/base目录运行时查看实际生效的设备树内容、以及dmesg查驱动probe的踪迹。这三样组合起来能应对绝大多数设备树相关问题。最后想提醒一件事设备树本身只是一份“静态描述”它不会主动拉起驱动驱动也不会因为设备树描述错误而报警——所有问题都是静默的、温和的但也因此容易被忽视。维护好你的设备树版本、每次修改都留好记录、改完就验证这些看似笨拙的习惯恰恰是设备树开发最可靠的方法论。
