1. 课程导入
在嵌入式与服务器固件开发领域，UEFI（Unified Extensible Firmware Interface）已经成为事实上的启动固件标准，而设备树（Device Tree，DT）则是描述硬件拓扑与资源分配的核心数据结构。当两者相遇，固件工程师面临的不只是“让系统跑起来”，而是要在启动早期把硬件描述准确、完整、可维护地传递给操作系统内核。本课程围绕“UEFI环境下的设备树适配”展开，目标是让学员从概念到实战，掌握一套可复用的工程方法。
一、学习目标：从“能启动”到“可维护”
本课程的学习目标分为三个层次。第一层是理解机制：掌握UEFI启动阶段、设备树二进制格式（DTB）的加载与传递路径、以及UEFI与DT在启动链中的交接点。第二层是掌握方法：能够独立完成设备树源文件（DTS）的裁剪、编译、注入、校验与调试，并处理常见适配问题。第三层是工程化落地：在真实项目中建立版本管理、自动化构建与回归验证流程，使设备树适配不再是“一次性手工活”。
核心能力清单：
- 能说清UEFI启动阶段与DTB传递的时序关系；
- 能读懂并修改DTS/DTB中的节点、属性与phandle引用；
- 能在UEFI Shell或固件菜单中验证DTB是否被正确加载；
- 能定位“内核看不到设备”这类典型适配故障；
- 能设计一套可重复的DT适配与验证流程。
二、核心概念：UEFI、设备树与交接点
UEFI负责硬件初始化、驱动加载和启动操作系统。它通过启动服务（Boot Services）和运行时服务（Runtime Services）向操作系统提供标准接口。设备树则是一种描述硬件的数据结构，以节点和属性的形式表达CPU、内存、总线、外设、中断、时钟、电源域等信息。在ARM、RISC-V等架构中，设备树通常由固件传递给内核，内核据此枚举设备并加载驱动。
两者之间的关键交接点是启动参数传递。UEFI固件在启动内核前，需要将DTB的物理地址写入启动参数结构（如ARM64的x0寄存器或EFI配置表），内核启动后解析DTB并建立设备模型。如果这个交接点出错，内核可能完全看不到某些设备，或者看到错误的资源分配。
另一个核心概念是DTB的加载方式。常见方式包括：固件内置DTB、从存储介质加载DTB、通过UEFI变量指定DTB路径、以及由引导程序（如GRUB、U-Boot）动态注入。不同方式对应不同的适配策略和调试手段。
三、整体框架：从固件到内核的适配链路
设备树适配不是孤立的一步操作，而是一条贯穿固件与内核的链路。我们可以把它拆成五个环节：硬件描述、DTS编写、DTB生成、固件加载、内核解析。每个环节都有对应的输入、输出和验证点。
| 环节 | 输入 | 输出 | 关键验证点 |
|---|---|---|---|
| 硬件描述 | 原理图、芯片手册、板级资源 | 节点与属性清单 | 地址、中断、时钟是否完整 |
| DTS编写 | 节点清单、参考DTS | .dts / .dtsi 文件 | 语法正确、phandle引用有效 |
| DTB生成 | DTS文件、DTC工具 | .dtb 二进制 | 编译无警告、大小合理 |
| 固件加载 | DTB、UEFI启动策略 | DTB地址写入启动参数 | 地址有效、未被覆盖 |
| 内核解析 | 启动参数、DTB | 设备模型、驱动绑定 | dmesg无报错、设备可见 |
四、实战路线图：七步走
为了让学习路径清晰可执行，本课程设计了一条七步实战路线。每一步都对应可操作的命令和可观察的结果。
- 概念对齐：理解UEFI启动阶段、DTB格式、交接点机制。
- 环境搭建：准备QEMU或真实开发板、UEFI固件、DTC工具链、内核源码。
- DTS裁剪：从参考DTS出发，删除无关节点，补充板级差异。
- DTB注入：选择内置、存储介质或UEFI变量方式加载DTB。
- 启动验证：通过UEFI Shell和内核日志确认DTB被正确解析。
- 故障排查：针对“设备缺失”“资源冲突”“驱动不匹配”定位根因。
- 工程化：建立DTS版本管理、自动化编译与回归测试。
建议在每一步都保留可复现的记录：DTS版本、DTC版本、UEFI固件版本、内核版本、启动日志。设备树适配的很多问题，最终都归结为“版本不一致”或“环境差异”。
五、案例场景：一个典型的适配任务
假设我们有一块基于ARM64的开发板，UEFI固件已经能启动到Shell，但进入Linux内核后，以太网、I2C和GPIO设备不可见。排查思路如下：
# 1. 确认DTB是否被加载
UEFI Shell> devtree
# 或查看启动参数中的DTB地址
# 2. 在内核日志中搜索DTB解析信息
dmesg | grep -i "device tree"
dmesg | grep -i "of_"
# 3. 检查DTS中对应节点是否存在
dtc -I dtb -O dts -o current.dts current.dtb
grep -n "ethernet\|i2c\|gpio" current.dts
# 4. 对比参考DTS与当前DTS的差异
diff -u reference.dts current.dts常见根因包括：DTS中节点被误删、reg地址与硬件不符、中断号错误、时钟未使能、phandle引用断裂、DTB加载地址被内核覆盖。通过“先确认DTB是否到达内核，再确认节点内容是否正确”的顺序，可以快速缩小范围。
六、误区与复盘
误区一：把设备树当成“配置文件”随意改。设备树是硬件描述，属性值必须与硬件手册一致，不能凭感觉填写。
误区二：只改DTS不验证DTB。DTS编译成DTB后可能因为语法或引用问题丢失节点，必须用dtc反编译校验。
误区三：忽略UEFI与内核的版本匹配。不同UEFI固件对DTB传递方式的支持不同，升级固件后必须重新验证。
误区四：没有回归测试。一次适配成功不代表后续修改安全，建议把关键设备的可见性写成自动化检查脚本。
复盘时建议回答三个问题：这次适配改动了哪些节点和属性？这些改动对应的硬件依据是什么？如果硬件版本升级，哪些节点需要同步更新？把答案记录下来，就是团队最宝贵的适配知识库。