1. 课程导入
在嵌入式Linux开发中，设备树（Device Tree）早已不是“可选项”，而是连接硬件描述与内核驱动的关键契约。当产品从一款SoC平台迁移到另一款平台，或从评估板走向自研板卡时，设备树往往成为最先暴露、也最容易被低估的工程风险点。本课程围绕“跨平台迁移”这一真实工程场景，帮助你把零散的DTS语法知识，升级为可复用、可验证、可交付的迁移方法论。
一、学习目标：从“会改DTS”到“能交付迁移方案”
本课程不是单纯的语法手册，而是以迁移工程为主线的能力训练。完成学习后，你应当能够独立完成以下任务：
- 读懂硬件：从原理图、引脚定义、时钟树和电源域中提取设备树所需的硬件信息，而不是盲目复制参考板DTS。
- 掌握结构：理解.dts、.dtsi、.dtb、.dtbo之间的编译关系，以及include层级、覆盖规则和标签引用机制。
- 执行迁移：按照“信息采集—基线建立—差异分析—节点改写—编译验证—上板调试”的流程，完成一次完整的跨平台迁移。
- 定位问题：能够根据内核启动日志、/proc/device-tree、of_node状态和驱动probe结果，判断问题出在设备树、驱动还是硬件。
- 工程化交付：输出可维护的DTS分层结构、迁移检查清单和版本管理策略，避免“改完能跑、换人即崩”。
二、核心价值：为什么跨平台迁移能力如此关键
在实际项目中，设备树迁移的价值体现在三个层面。第一是时间成本：一个没有迁移方法论的工程师，可能在引脚复用、时钟父节点、中断类型和电源域上反复试错，耗费数天甚至数周；而掌握流程的人可以在数小时内建立可验证的基线。第二是质量风险：设备树错误往往不会导致编译失败，而是表现为驱动probe失败、外设时好时坏、休眠唤醒异常，这类问题排查成本极高。第三是团队协作：当DTS按SoC层、板级层、外设层分层组织后，不同成员可以并行维护，减少冲突。
更重要的是，跨平台迁移能力直接决定了产品能否快速切换供应链、复用既有驱动资产、缩短新板卡bring-up周期。在国产SoC快速迭代的背景下，这项能力已经从“加分项”变为“必备项”。
三、整体知识框架：五层能力模型
本课程的知识体系可以归纳为五层：硬件认知层（原理图、时钟、电源、引脚）、语法结构层（DTS/DTSI/DTB、节点、属性、phandle）、绑定规范层（compatible、reg、interrupts、clocks、pinctrl等标准属性）、迁移方法层（差异分析、节点改写、覆盖策略）、验证调试层（编译、反编译、日志分析、上板测试）。这五层不是孤立的，而是从下到上逐层支撑，任何一层缺失都会导致迁移结果不可靠。
四、迁移工程全流程概览
上图右侧给出了迁移工程的标准流程。需要强调的是，这个流程不是线性的，而是带有反馈迭代的闭环。实际项目中最常见的错误是“跳过基线建立，直接改DTS”，结果一旦启动失败，无法判断是原DTS问题还是修改引入的问题。正确做法是：先让参考DTS在目标板上编译通过并尽可能启动到控制台，形成可启动基线，然后以最小改动逐步逼近目标硬件。
在信息采集阶段，重点获取以下内容：SoC型号与封装、DDR容量与位宽、启动介质、时钟源、电源域、引脚复用表、中断控制器类型、外设地址映射。这些信息决定了设备树中memory、chosen、clocks、pinctrl、interrupt-controller等关键节点的写法。
# 典型迁移工作目录结构
project-dts/
├── soc/
│ ├── soc-vendor-a.dtsi # SoC层公共描述
│ └── soc-vendor-b.dtsi
├── board/
│ ├── board-a.dts # 板级差异
│ └── board-b.dts
├── peripheral/
│ ├── i2c-sensors.dtsi # 外设层
│ └── spi-flash.dtsi
└── Makefile
# 编译与反编译检查
dtc -I dts -O dtb -o board-b.dtb board-b.dts
dtc -I dtb -O dts -o board-b.dts board-b.dtb五、典型场景与常见误区
假设你正在将一款基于A厂商SoC的工业网关迁移到B厂商SoC。参考板使用I2C连接温度传感器，目标板改为SPI接口；参考板使用固定时钟，目标板使用PLL分频；参考板的中断为高电平触发，目标板为下降沿触发。这些差异如果只改compatible而不改interrupts、clocks和pinctrl，驱动即使probe成功，功能也会异常。
| 迁移对象 | 常见误区 | 正确做法 |
|---|---|---|
| compatible | 直接照抄参考板字符串 | 按“厂商,型号”规范匹配驱动，必要时增加fallback |
| reg | 地址和长度写错或漏写 | 对照SoC手册核对基地址与范围，注意地址单元数 |
| interrupts | 忽略触发类型和父中断控制器 | 确认interrupt-parent和触发标志，与硬件一致 |
| clocks | 只写clock-frequency不写clock引用 | 使用phandle引用时钟源，确保时钟树完整 |
| pinctrl | 引脚复用组名照搬 | 按目标SoC的pinmux定义重新配置，验证电平 |
| status | 忘记使能或误关节点 | 明确okay/disabled，避免“默认关闭”陷阱 |
六、本课程的学习路径建议
建议按照“先建立整体框架，再深入语法细节，最后回到迁移实战”的路径学习。前期重点理解五层能力模型和迁移流程，中期掌握DTS语法、绑定规范和编译工具链，后期通过多个真实迁移案例反复练习差异分析和问题定位。每学完一个模块，都应当回到“我能否独立完成一次迁移”这个问题上检验自己。
设备树跨平台迁移不是一门“背语法”的课程，而是一门“做工程”的课程。它要求你同时具备硬件阅读能力、内核驱动认知和系统化验证思维。当你能够把一块新板卡的设备树从零写到稳定运行，并且能清楚解释每一个节点的来源和依据时，你就真正掌握了这项能力。