📚 课程目录第3章设备树绑定文档

3. 设备树绑定文档：理解设备树绑定(Binding)文档的格式与作用，如何查阅官方绑定

3.1 设备树绑定的核心作用

设备树绑定(Binding)是连接硬件描述与内核驱动之间的“契约文档”。它定义了设备树节点中哪些属性是必需的、哪些是可选的、属性值的类型与格式，以及节点与具体驱动程序的对应关系。没有绑定文档，设备树只是一堆无意义的寄存器地址和数字；有了绑定文档，设备树才能被内核正确解析并驱动硬件。

  关键认知： 绑定文档是设备树调试的第一手参考资料。当内核启动过程中某个外设未能正确初始化时，首先应检查设备树节点是否严格遵循了对应的绑定规范。

3.2 绑定文档的标准格式

Linux 内核中的设备树绑定文档遵循统一的格式规范，通常位于内核源码树的 Documentation/devicetree/bindings/ 目录下。每个绑定文档使用 YAML 格式（新标准）或纯文本格式（旧标准）编写。

3.2.1 YAML 格式绑定（推荐）

现代内核（5.x 及以上）逐步采用 YAML 格式，配合 dt-schema 工具可进行自动化校验。一个典型的 YAML 绑定包含以下结构：

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/serial/fsl-imx-uart.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Freescale i.MX UART

maintainers:
  - Kumar Gala <galak@kernel.crashing.org>

properties:
  compatible:
    oneOf:
      - items:
          - enum:
              - fsl,imx53-uart
              - fsl,imx6q-uart
          - const: fsl,imx21-uart

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    minItems: 1
    maxItems: 2

required:
  - compatible
  - reg
  - interrupts

additionalProperties: false

3.2.2 纯文本格式绑定（传统）

旧版绑定文档使用纯文本描述，结构相对松散但仍遵循固定模式：

* Freescale i.MX UART

Required properties:
- compatible : Should be "fsl,imx53-uart", "fsl,imx6q-uart"
- reg : Address and length of the register set
- interrupts : Should contain uart interrupt

Optional properties:
- fsl,uart-has-rtscts : Indicate the uart has RTS and CTS lines
- fsl,dte-mode : Indicate the uart works in DTE mode

Example:
uart1: serial@53fbc000 {
    compatible = "fsl,imx53-uart", "fsl,imx21-uart";
    reg = <0x53fbc000 0x4000>;
    interrupts = <0 31 0x04>;
};

3.3 绑定文档的关键字段解析

字段	含义	调试价值
`compatible`	设备兼容字符串，驱动匹配的关键	拼写错误会导致驱动无法加载
`reg`	寄存器地址与长度	地址冲突或越界会导致系统挂死
`interrupts`	中断号与触发类型	中断号错误导致设备无响应
`clocks`	时钟源引用	时钟缺失导致外设无法工作
`pinctrl-*`	引脚复用配置	引脚冲突导致信号异常
`status`	设备状态（okay/disabled）	状态为 disabled 时设备被跳过

3.4 绑定文档与设备树节点的对应关系

以下 SVG 展示了绑定文档如何约束设备树节点的结构：

3.5 如何查阅官方绑定文档

3.5.1 本地内核源码查阅

在已下载的内核源码树中，绑定文档位于固定路径：

# 查看所有绑定文档
ls Documentation/devicetree/bindings/

# 查找特定设备的绑定
find Documentation/devicetree/bindings/ -name "*uart*"

# 查看具体绑定内容
cat Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml

3.5.2 在线查阅

资源	URL	适用场景
Linux 内核官方仓库	`https://git.kernel.org/`	获取最新绑定文档
DeviceTree 官方规范	`https://devicetree-specification.readthedocs.io/`	理解通用属性定义
Bootlin 设备树数据库	`https://bootlin.com/pub/linux/devicetree/`	快速搜索设备兼容字符串
Elixir Cross Referencer	`https://elixir.bootlin.com/linux/latest/source`	在线浏览绑定与源码

3.6 绑定文档的调试应用

以下 SVG 展示了在调试过程中如何利用绑定文档进行问题定位：

3.7 常见绑定错误与排查方法

实战经验： 以下是在实际调试中遇到的绑定相关高频错误，建议熟记。

错误现象	可能原因	绑定文档排查点
驱动 probe 未调用	compatible 字符串不匹配	核对绑定中的 compatible 枚举值
设备注册失败	缺少 required 属性	检查 required 列表是否全部实现
中断不触发	interrupts 格式错误	确认 cells 数量与中断控制器匹配
时钟频率异常	clocks 引用错误	检查 clock-names 与绑定定义一致
引脚功能异常	pinctrl 配置缺失	确认 pinctrl-0 引用的节点存在

3.8 使用 dt-schema 校验绑定合规性

现代内核开发流程中，可以使用 dt-schema 工具自动校验设备树文件是否符合绑定规范：

# 安装 dt-schema 工具
pip install dtschema

# 校验单个 DTB 文件
dt-validate -s Documentation/devicetree/bindings/ arch/arm/boot/dts/imx6q.dtb

# 校验 DTS 源文件
dt-validate -s Documentation/devicetree/bindings/ arch/arm/boot/dts/imx6q.dts

# 仅检查特定绑定
dt-validate -s Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml \
  arch/arm/boot/dts/imx6q.dts

调试技巧： 在开发阶段，建议将 dt-validate 集成到构建脚本中。每次修改 DTS 后自动运行校验，可以在编译前发现 80% 以上的绑定合规性问题，大幅减少启动阶段的调试时间。

3.9 绑定文档的版本管理

不同内核版本的绑定文档可能存在差异，调试时务必使用与目标内核版本匹配的绑定文档：

内核 4.x 及更早： 主要使用纯文本格式绑定，部分设备缺少完整文档
内核 5.0 - 5.10： 开始引入 YAML 格式，新旧格式并存
内核 5.10 及以上： YAML 格式成为主流，纯文本格式逐步淘汰
内核 6.x： 强制要求新设备使用 YAML 绑定，支持自动化校验