简介面向Linux内核与嵌入式开发学习者讲解设备树Device Tree在启动时提供硬件平台信息、替代内核arch目录中板级细节代码的背景并系统梳理dts语法与内核加载dtb的完整流程。资源为单个PDF约293KB内容涵盖dts文件节点命名规则、compatible与reg等关键字含义以及dtb解析、设备树构建、驱动绑定三个阶段并结合dtsi与dts拆分方式说明SoC厂商与开发板的协作模式。已有661人学习篇幅精炼适合作为入门设备树的快速参考。读者可从中掌握用键值对描述节点、用尖括号表示32位整数等基础写法并理解设备节点如何通过compatible属性匹配platform_driver进而用于RISC-V等新平台驱动开发与启动问题排查。1. 设备树是什么为什么ARM Linux开发绕不开这份文档一块开发板换了个屏幕内核源码里要找平台板级文件改十几处再花二十分钟重新编译整个内核——这是设备树普及之前ARM Linux开发者几乎每周都要面对的翻车现场。设备树Device Tree就是把硬件拓扑、地址、中断、时钟、GPIO这些信息从内核C代码中剥离出来的描述文件编译成二进制后传给内核让同一份内核镜像适配不同硬件。直白理解设备树是写给内核看的硬件说明书。那篇2020年8月的Linux设备树介绍与加载过程分析笔记把从dts编写到内核解析的链路梳理得很清楚这里就顺着这条链路把文件类型、语法、编译、加载、调试讲透。新手能照步骤把第一个dtb跑起来熟手也能在已经乱成一团的设备树调试里找到新的排查抓手。2. 设备树文件家族与基本语法dts、dtsi、dtb谁是谁第一次接触设备树的人十有八九会被几个缩写搞晕dts、dtsi、dtb、dtc、dtbo。其实职责划分很清晰dts是描述单板硬件的源文件dtsi是SoC级公共定义dtb是编译后的二进制产物dtc是编译器本身dtbo是overlay二进制。先把这些概念钉死后面的加载分析才不会乱。2.1 四种文件类型的职责边界与转换关系文件类型格式职责谁在写dts文本单板级硬件描述一棵完整的设备树板级工程师dtsi文本SoC公共外设、时钟、中断定义片段SoC厂商dtb二进制dts经过DTC编译后的扁平化数据编译工具生成dtbo二进制以插件方式叠加进主树的片段需要动态调整时生成转换关系一句话一个dts通过#include引入一个或多个dtsi组合出完整的树状描述DTC编译后变成dtb内核启动时解析dtb还原成内存中的设备树结构。overlay则独立编译成dtbo运行期动态叠加不走编译主树那一步。编写设备树时最常见的做法是从SoC厂商提供的dtsi出发只在自己的dts里填写板级差异部分。厂商把CPU、内存控制器、中断控制器、I2C控制器这些固定外设都放在dtsi里板级工程师只需要关注哪路GPIO接了LED、哪片Flash挂在哪个控制器上。这个拆分逻辑直接决定了维护成本SoC换版本改dtsi单板换外设改dts。如果把板级信息混进dtsi换一个板型就要动公共文件多个项目共享同一个dtsi时冲突会非常频繁。2.2 dts语法起步节点、属性、compatible匹配逻辑一个极小但完整的dts长这样/dts-v1/; #include soc_a7.dtsi / { model FakeBoard-A7 Evaluation Kit; compatible acme,fakeboard-a7, acme,a7-soc; chosen { stdout-path uart1; }; leds { compatible gpio-leds; pinctrl-names default; pinctrl-0 pinctrl_led0; led0 { label heartbeat; gpios gpio1 3 GPIO_ACTIVE_LOW; linux,default-trigger heartbeat; }; }; };拆开看几个关键点。/dts-v1/;是版本声明必须有现代DTC只有见到这个声明才按新版语法解析。#include soc_a7.dtsi复用SoC级定义和C语言的预处理是同一套机制。根节点/下的model和compatible是内核识别板级的入口字段其中compatible的匹配顺序是严格按字符串排列来的内核遍历驱动表时逐个比较不匹配就跳到下一项所以最具体的板级字符串放在最前面是惯例。chosen节点比较特殊它不描述硬件而是传递运行参数。stdout-path指向UART控制台设备内核启动早期就在找这个路径。leds下的led0是具体子节点gpios gpio1 3 GPIO_ACTIVE_LOW这条属性由三部分构成gpio1是phandle引用指向在dtsi里定义过的gpio1控制器节点3是这路GPIO在控制器内的序号GPIO_ACTIVE_LOW是flag宏。这三个值的组合顺序由gpio1节点里的#gpio-cells属性决定SoC不同cell数可能不同照抄别的平台代码时最容易在这里翻车。提示#gpio-cells这类属性描述的是这个控制器期待几个cell不是你在dts里定义的而是SoC厂商在dtsi里定义好的常量。写设备树前先查dtsi里的定义不要凭感觉猜。2.3 地址、中断与pinctrl三类高频属性的写法和语义地址描述是设备树里最基础的硬骨头。典型写法uart1 { compatible arm,pl011; reg 0x02020000 0x1000; interrupts 0 20 4; clocks uart_clk; status okay; };reg 0x02020000 0x1000含义是设备基地址0x02020000地址空间长度0x1000字节。这个二元组格式不是随便定的它取决于总线控制器节点里#address-cells和#size-cells的值。前者为1表示每个地址用一个32位整数后者为1表示每个长度用一个32位整数。如果访问挂在某种复杂总线上的设备看到reg里有三四个数字不要慌父节点的cells定义说了算。中断属性是另一个高频踩坑点。interrupts 0 20 4在三元组格式下含义依次为中断类型0是SPI共享外设中断、中断号20、触发方式4。还有interrupt-parent属性用于指定挂在哪个中断控制器下。很多项目里外设中断不触发最后定位到interrupt-parent没指对或者指到了错误的级联控制器。pinctrl属性把引脚复用状态和设备绑定在一起pinctrl-names default, sleep; pinctrl-0 pinctrl_uart1; pinctrl-1 pinctrl_uart1_sleep;驱动通过pinctrl-names索引对应状态运行时可以动态切换比如进入低功耗前切到sleep状态。这里的pinctrl_uart1是一个在dtsi里定义好的引脚组节点实际描述某组引脚的复用模式和上下拉配置。修改这个引脚的mux功能后必须确认没有其他设备节点也在引用同一组引脚否则两个驱动会互相踩。3. 用DTC把dts编译成dtb最小命令与反编译验证dts写对了不代表设备树就能跑编译这一步的细节同样能决定成败。DTC全称Device Tree Compiler是设备树工具链的核心。这一章讲清楚怎么拿到工具、怎么编译、怎么用反编译验证。3.1 DTC工具链的获取与版本差异DTC不在交叉编译器里默认包含但几乎所有嵌入式Linux开发环境都装了。最常见的三种获取路径一是Linux内核源码自带位于内核源码树scripts/dtc/目录内核的make命令会调用它二是发行版的独立工具包一条命令装完三是自己从上游拉源码编译。版本差异是实际开发中一个隐形的坑。旧版本DTC对某些属性名和宏的处理更宽松新版本更严格比如重复的节点名在旧版本里可能最后一个生效、中间产生警告后照样生成dtb而新版本直接报错停止。用高版本DTC编译旧项目的dts有时候会得到一堆告警处理办法不是急着改dts而是先确认换回项目配套的DTC版本是否告警消失。判断DTC版本对设备树文件的影响最实用的方式是查看告警文本。不同版本对同一条属性给出的诊断措辞和级别不一样。某项目升级DTC后dts里一个未使用的label从unused label变成错误级别导致dtb没法生成最后定位是历史遗留的死代码删掉才通过。3.2 手动编译与内核编译两条路先看手动编译的最小命令# 把dts编译成dtb dtc -I dts -O dtb -o myboard.dtb myboard.dts # 加编译参数输出所有告警信息 dtc -I dts -O dtb -W all -o myboard.dtb myboard.dts # 反编译把dtb还原成dts文本 dtc -I dtb -O dts -o restored.dts myboard.dtb-I指定输入格式dts文本或dtb二进制-O指定输出格式-o指定输出文件名。反编译命令在调试时比想象中更重要从bootloader里抓出来的dtb只有反编译才能看清内核实际拿到的是什么。-W all打开所有告警类别初次编译时加上它能提前发现被静默吞掉的隐患。手动编译适合单文件验证。真实项目里设备树几乎都是在内核构建系统里编译的# 在内核源码树根目录指定架构和dtb目标 make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- myboard.dtb这条命令会加载内核的Kbuild规则自动处理#include的依赖关系并调用与内核匹配的DTC版本。内核里的编译规则还支持多个dtb同时生成一次性把所有板型的dtb都编出来。手动编译的好处是快、直接缺点是容易忽略内核Kbuild里定制的头文件宏和预处理路径。我的个人习惯是先用内核构建系统编译一次确认依赖路径没有问题之后的小改动用dtc单发追求迭代速度。3.3 反编译验证的三个要点dtb编译完成后别急着拷进启动介质先反编译看一眼。三个验证要点每次都值得做。第一确认根节点的model和compatible与预期一致。内核启动时选择machine描述就靠这两个字段拼错一个字母内核就可能落入默认的generic machine外设初始化路径完全不同。第二确认关键外设节点有内容没被预处理吃掉。#include机制的坑在于被包含的dtsi里如果有条件编译块宏定义没传对外设节点就可能整个消失。反编译后的文本里grep不到某个节点说明编译阶段就丢了这和加载阶段的丢失是两种排错路径。第三确认phandle没有被重排成异常值。高版本DTC在编译时会自动分配phandle数值一个稳定隐患是如果dts里手动写了phandle属性但数值与DTC自动生成的冲突最终dtb里的指向可能会错乱。反编译验证的完整流程通常是# 编译 make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- myboard.dtb # 反编译 dtc -I dtb -O dts -o verify.dts myboard.dtb # 检查关键节点 grep -A5 compatible \acme,fakeboard-a7\ verify.dts看到grep结果里的节点和属性都在再落盘到启动分区。这个习惯帮我挡掉了至少三次因为路径搜索顺序问题导致的dtb更新失败。设备树编译的本质可以压缩成一句话DTC只是工具真正的难点在于验证编译产物是否符合预期反编译是廉价且可靠的验证手段。4. 设备树加载过程分析从Bootloader搬运到内核解析的完整链路前面两章解决了怎么写、怎么编的问题。这一章回答加载过程dtb文件从Flash到内存再到内核解析成设备树结构最后匹配驱动每一步做了什么。理解了这条链路很多启动问题就有了明确的排查方向。4.1 Bootloader阶段U-Boot如何搬移和改写dtb以U-Boot为例加载链路的第一步发生在U-Boot命令行或启动脚本里。常见做法是# 从分区或文件系统读入dtb到内存地址 load mmc 0:1 0x88000000 /boot/myboard.dtb # 地址作为参数传给内核 bootm 0x87800000 - 0x88000000内核配置决定它从哪里取设备树。现代U-Boot启动命令通常显式传入dtb地址这个地址就是内核早期拿到硬件描述的唯一入口。U-Boot阶段还会有一类操作用fdt命令修改设备树例如改mac地址、禁用某个节点、调整启动参数fdt addr 0x88000000 fdt set /soc/ethernet mac-address 00:11:22:33:44:55 fdt set /chosen bootargs consolettymxc0,115200 root/dev/mmcblk1p2 rootwaitU-Boot的fdt命令本质是直接改内存里的dtb。这个阶段改写的属性会原样传给内核优先级比dts编译时写的更高。排查设备树问题时第一件事是问这个节点在U-Boot里有没有被fdt命令改过曾经处理过一个启动后网口MAC始终不对的问题dts里明明写的是板级默认值但U-Boot脚本里残留了一条fdt set命令把旧板型的MAC写死了启动脚本里grep不到原因必须记录启动脚本中所有fdt命令的执行顺序才能排掉。U-Boot还有一处关键行为它传给内核的dtb地址必须满足对齐要求。某些内核早期代码会直接对dtb地址做解析如果地址不对齐可能触发段错误或者解析出乱码。所以启动脚本里给dtb分配的加载地址最好与内核约定的加载地址保持一致。4.2 内核启动早期从dtb二进制到device_nodedtb进入内核后加载过程进入最核心的一段。函数调用链如下start_kernel() - setup_arch() - setup_machine_fdt(__atags_pointer) - early_init_dt_scan() - unflatten_device_tree() - __unflatten_device_tree() - scan_node() - populate_node()这一段是设备树加载的黑匣子但拆开看并不复杂。setup_machine_fdt首先核对dtb头部魔数确认这是合法设备树然后扫描根节点和chosen节点提取model、compatible、bootargs等早启动参数。unflatten_device_tree把扁平化的dtb展开成树结构每个节点变成一个struct device_node每个属性变成struct property。populate_node不是一次性创建全部节点而是递归遍历FDT的节点结构逐层创建。这个递归遍历在异常大的设备树或者节点深度过深时会消耗可观的启动时间。某项目尝试在dts里堆了五层以上的嵌套子节点启动时间增加了十几毫秒后来把不必要的中间层节点折叠掉才恢复。FDT在内存中的布局也是一个值得注意的点。dtb内部有若干对齐区段字符串表、结构块、预留内存区依次排列。内核解析时按头部偏移量逐个访问所以对dtb内存对齐的要求在早期尤为严格。一个常见故障现象是内核启动卡在fdt相关的早期panic原因就是U-Boot把dtb加载到了不可执行或者不对齐的地址。4.3 设备与驱动的匹配compatible在何时何地生效设备树展开成树后真正的价值在驱动匹配环节体现。内核中platform_driver与设备的匹配发生在设备模型初始化时流程是of_platform_bus_probe(NULL) - of_platform_default_populate() - of_platform_bus_create() - of_device_is_available() // 检查status属性 - of_platform_device_create_pdata() - of_device_add()of_device_is_available检查节点的status属性设置成disabled的节点在这一步就会被跳过不会创建设备。这里有个经典误区很多人以为只要dts里删掉节点就万事大吉其实status disabled才是推荐做法保留节点但禁用方便后续用overlay或fdt命令重新使能。匹配动作发生在驱动侧。某个驱动注册时带上of_match_table内核按表里的compatible逐项与设备树节点的compatible属性比较。匹配成功的驱动会收到一个platform_device其中resource字段已经由内核从设备树节点的reg和interrupts属性转换好驱动用platform_get_resource就能拿到地址和中断号不必自己解析设备树。有个细节值得注意compatible匹配是精确字符串比较不是前缀或子串匹配。在dts里写acme,fakeboard想匹配驱动表的acme,fakeboard-a7不会成功。dts里写多少个compatible字符串都可以匹配时按顺序试把最具体的板级字符串放最前。加载过程的完整链路串起来看U-Boot负责把dtb从存储介质搬到内存并可能做修改内核早期代码校验并展开成树设备模型按status和compatible驱动匹配。每个环节都有独立的状态确认方法这是后续避坑指南的排查基础。5. 设备树调试避坑指南5个高频问题的现象与解决这一章是多年调试经验里筛选出来的问题清单。每一条都按现象、原因、解决三步展开希望能帮读者少走弯路。5.1 启动卡在No working device tree found内核打印这行日志后停止启动。原因通常是根节点的compatible没有匹配到任何内核支持的machine描述。具体到开发中常见原因有两个dts根节点compatible字符串与内核machine描述表不一致或者U-Boot传入的dtb不是预期的那份。解决步骤先在U-Boot里确认加载地址和分区用fdt命令检查dtb内容再确认内核config里对应的machine描述有没有被打开。有一次排查了整整一天最后发现config里少了某个板级选项内核根本没编译对应的machine支持。5.2 GPIO编号对不上外设操作无响应GPIO操作直接影响外设但编号却对不上。此时要检查dts中的gpios属性看它的格式是否与gpio控制器定义的#gpio-cells一致。比如某个控制器#gpio-cells 2但dts里只写了一个数字编译时不报错内核解析时会取到错误的数据。另一个常见原因是phandle引用错了gpio控制器把A控制器的引脚写成了B控制器的序号。解决步骤是反编译dtb确认实际被内核解析的gpio属性值再从dts源码追查不一致的来源。5.3 改了reg但驱动读到的地址不对修改了dts里某个节点的reg地址驱动仍然在旧地址上操作。遇到这种情况先确认改动后的dtb有没有被正确加载U-Boot里可能缓存了旧dtb。手动编译时更容易踩这个坑改了dts后直接编译生成dtb但启动脚本仍然指向旧分区中的文件。解决方法是每次修改后反编译验证reg字段并检查U-Boot的环境变量是否写死了别的加载路径。5.4 pinctrl状态互踩导致外设失效两个设备节点引用同一组引脚驱动加载时一个使能了某个pinctrl状态另一个又把它改掉外设表现是时好时坏。根本原因是dts中没有做引脚独享检查。解决方法是先全局搜索dtsi和dts里所有引用同一pinctrl_xxx组节点的位置在同一个控制器下同一组引脚只能出现在一个设备的pinctrl属性里。如果确实需要共享引脚应该把该复用配置放到SoC的iomux节点下而不是在多个外设里重复定义。5.5 DTC编译告警与运行结果不符编译通过并生成了dtb但板子上运行结果和dts预期不一致。这种玄学问题常常源于DTC版本差异。不同版本对同一个dts的处理可能不同特别是对重复节点、无效属性和重叠reg的检查严格程度不同。解决方法是记录项目编译环境使用的DTC版本升级工具链后重新编译并对比反编译结果。只要反编译输出稳定可以基本排除编译阶段引入的不确定性。五条经验背后的共同逻辑是不要把运行结果直接归因于设备树玄学。先确认加载路径再确认编译产物最后确认内核匹配逻辑每一步都有对应的排查手段。6. 进阶用device tree overlay实现运行时外设调整前面五章把设备树静态开发和加载过程讲透了。最后一章讲一个能大幅提升调试效率的机制设备树overlay。它允许在系统运行时动态加载一小段设备树片段实现外设节点的启用、禁用或参数修改不用重启内核。6.1 overlay的语法、编译与加载命令overlay的源文件写法与普通dts相似但多了/plugin/;声明而且只能通过引用写目标节点/dts-v1/; /plugin/; ecspi2 { status okay; spidev0 { compatible acme,spidev; reg 0; spi-max-frequency 24000000; }; };这个片段表示在运行中的设备树上找到ecspi2节点把它状态改为可用并在其下追加一个SPI设备子节点。编译方式多一个-参数目的在于生成设备树符号信息让overlay片段能够解析引用的phandledtc -I dts -O dtb - -o spidev-overlay.dtbo spidev-overlay.dts内核支持overlay时通过configfs加载mkdir -p /configfs/device-tree/overlays/spidev cat spidev-overlay.dtbo /configfs/device-tree/overlays/spidev/dtbo加载完成后立即生效验证方式# 确认节点状态已变成okay cat /proc/device-tree/ecspi2/status # 确认子节点已生成 ls /proc/device-tree/ecspi2/spidev0/6.2 overlay的三个典型应用场景与边界实际项目中overlay最典型的应用有三个。一是外设复用切换同一块底板通过不同overlay让同一组引脚工作在不同模式下避免维护多份完整dts带来的重复劳动。二是调试时快速验证怀疑某个外设时序参数不对写一个小overlay改spi-max-frequency加载即改比改完整dts重编译快得多。三是FPGA动态逻辑加载场景FPGA镜像换一版overlay跟着换一版不用动主设备树。overlay也有边界。它不是万能的修改不到内存节点中已经展开的属性依赖内核开启CONFIG_OF_OVERLAY和相关configfs支持叠加顺序错误会导致节点冲突。我的一个教训是在调试U-Boot阶段问题时不建议用overlay因为U-Boot的fdt命令已经可以做同等的事且不受内核overlay路径限制。overlay的价值集中在Linux运行态调试和产品化场景把这句话记住就能在合适的阶段做出合适的选择。设备树开发和调试的整体链路从dtsi做减法、dts做加法开始到DTC编译、反编译验证再到U-Boot加载、内核展开、驱动匹配最后用overlay应对运行态变化是一条完整的方法论。每次遇到问题先定位在哪一环再对症下药比在全部环节里大海捞针高效得多。希望这些经验能帮到正在设备树里排查问题的你。本文还有配套的精品资源点击获取