版本升级的挑战：内核版本升级带来的设备树ABI变化
说实话，设备树适配这件事，最让人头疼的不是写dts文件本身，而是版本升级。我见过太多团队，内核从4.19升到5.10，板子直接起不来，最后查了三天发现是设备树ABI变了。
为什么会这样？因为设备树本质上是一个固件与内核之间的接口。内核版本一升级，这个接口的约定就可能发生变化。你想想看，Linux内核社区每年合并几万笔补丁，设备树相关的改动少说也有上千笔。这些改动里，有些是新增功能，有些是修复bug，但还有一些——嗯，就是改接口。
设备树ABI到底指什么？
设备树ABI（Application Binary Interface），说白了就是内核期望从设备树里读到什么、怎么读。它包含三个层面：
- 节点路径：比如
/soc/spi@ff110000，这个路径变了，驱动就找不到设备 - 属性名称和格式：比如
clocks属性从<phandle index>变成<phandle index flags> - 属性值的语义：同样的属性名，内核新版本可能对值的解释完全不同
我举个例子。以前有个项目，我们用的 gpio-leds 节点里写的是 gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>。内核从4.14升到5.4之后，这个写法突然不认了。查了半天才发现，新内核要求用 led-gpios 而不是 gpios。就改一个属性名，板子上的LED全不亮了。
核心观点：设备树ABI变化是版本升级中最隐蔽的坑。它不像内核API那样有明确的编译报错，而是直接导致硬件初始化失败，而且错误信息往往非常模糊。
Bindings文档——你的救命稻草
我在刚接触设备树那会儿，其实不太看bindings文档。总觉得“不就是写几个属性嘛，看看别人的dts抄一下就行了”。结果呢？被坑了好几次之后，我养成了一个习惯：每次升级内核，第一件事就是去翻bindings文档的changelog。
Bindings文档是什么？它是内核社区对设备树节点格式的官方规范。每个设备树binding文件都定义了：
- 这个节点必须包含哪些属性（required properties）
- 哪些属性是可选的（optional properties）
- 每个属性的数据类型和取值范围
- 子节点的格式要求
- 兼容性字符串（compatible）的匹配规则
说白了，bindings就是设备树的“API手册”。内核驱动怎么解析设备树，完全按照bindings来写。你写的dts如果不遵守bindings，驱动就读不到正确的值。
我的经验：bindings文档通常放在内核源码的 Documentation/devicetree/bindings/ 目录下。每个子系统一个子目录，比如 i2c/、gpio/、clock/。升级内核后，我建议你重点关注这些目录里的 *.yaml 文件——新版本内核已经全面改用YAML格式描述bindings了。
一个真实的ABI变化案例
我记得有一次，客户从Linux 4.19升级到5.10，板子上的以太网控制器不工作了。错误日志只显示了一句：failed to get phy mode。
我们对比了两个内核版本的bindings文档，发现 ethernet-phy 节点的 phy-mode 属性，在4.19里允许的值是 "rgmii"、"rmii" 这些字符串。但到了5.10，bindings里新增了一个要求：phy-mode 必须配合 phy-handle 使用，而且 phy-mode 的值必须与PHY芯片实际支持的模式一致。
客户的dts里写的是 phy-mode = "rgmii"，但实际PHY芯片只支持 rgmii-id。4.19内核没做严格校验，所以能跑。5.10内核加了校验，直接报错。
你看，这就是bindings文档的重要性。如果没有文档，你根本不知道新内核改了校验逻辑。
版本升级时设备树适配的典型流程
我个人习惯把版本升级的设备树适配分成四个步骤。下面这张图可以帮你理清思路：
Bindings文档的演变趋势
从内核5.0开始，bindings文档经历了一次大迁移——从纯文本格式（.txt）全面转向YAML格式（.yaml）。为什么要改？因为YAML格式可以用工具做自动化校验。
| 对比项 | 旧格式（.txt） | 新格式（.yaml） |
|---|---|---|
| 可读性 | 纯文本描述，依赖人工理解 | 结构化描述，一目了然 |
| 校验能力 | 无自动校验 | 可用 dt-validate 工具自动检查 |
| 属性约束 | 靠文字说明，容易遗漏 | 精确的类型、范围、枚举值约束 |
| 兼容性 | 不同厂商写法不统一 | 统一规范，社区强制要求 |
避坑指南：我曾经遇到一个项目，团队把旧内核的dts直接复制到新内核，编译通过了，但板子启动到一半就挂。后来用 dt-validate 一跑，发现十几个bindings违规。所以我现在强烈建议：每次升级内核后，先用 dt-validate 跑一遍你的dts。这个工具在内核源码的 scripts/dtc/ 目录下，用法很简单：
# 安装依赖
pip install dtschema
# 校验设备树
dt-validate -s /path/to/kernel/Documentation/devicetree/bindings/processed-schema.json your.dts版本升级中常见的ABI变化类型
根据我这几年的经验，内核版本升级带来的设备树ABI变化，大致可以归纳为以下几类：
- 属性名重命名：比如
gpios→led-gpios，clock-frequency→clock-frequency-hz - 属性值格式变化：比如
reg从<addr size>变成<addr size flags> - 节点路径变化：比如
/soc/spi@...改成/spi@... - compatible字符串废弃：旧字符串被标记为 deprecated，必须用新的
- 新增必填属性：以前可选的属性，新版本变成 required
- 属性值取值范围收紧：比如
phy-mode从自由字符串变成枚举值
嗯，这里要注意一点：不是所有变化都会导致编译报错。很多ABI变化是运行时行为差异。比如属性值格式变了，但解析代码做了向后兼容，旧格式也能解析——只是解析结果可能不对。这种问题最难排查。
我的建议
如果你正在做版本升级，我建议你养成三个习惯：
- 升级前：把当前内核的bindings文档做个备份，方便对比
- 升级中：用
git log查看 bindings 目录的变更记录，重点关注Documentation/devicetree/bindings/下的改动 - 升级后：用
dt-validate做全量校验，不要只依赖编译通过
说白了，设备树适配这件事，七分靠规范，三分靠经验。bindings文档就是那个“规范”。你尊重它，它就帮你省时间；你忽视它，它就让你加班。