3. 设备树绑定文档：内核Documentation/devicetree/bindings目录结构、如何阅读绑定文档、编写自定义绑定

设备树绑定文档（Device Tree Binding Document）是内核官方定义的“硬件描述规范说明书”。它规定了某个IP或设备在设备树中应该怎么写、有哪些属性、哪些是必须的、哪些是可选的。对于驱动开发者来说，绑定文档就是设备树与驱动之间的“契约”。

3.1 内核绑定文档目录结构

内核源码树中的 Documentation/devicetree/bindings/ 目录按照设备类型和厂商进行组织。其结构清晰，便于开发者快速定位。

目录结构遵循以下规则：

• 顶层目录：按设备类型分类，如 arm/、clock/、gpio/、i2c/、spi/、net/、sound/、display/ 等。
• 厂商子目录：在类型目录下，通常有 vendor/ 子目录，存放具体厂商的绑定文件。
• 文件格式：新内核（5.x+）统一使用 .yaml 格式（基于 json-schema 的 YAML 绑定）。旧内核可能还有 .txt 格式的纯文本绑定。

3.2 如何阅读绑定文档

以 Documentation/devicetree/bindings/gpio/gpio-controller.yaml 为例，展示如何解析一个标准的 YAML 绑定文件。

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

title: GPIO Controller

maintainers:
  - Linus Walleij <linus.walleij@linaro.org>

description: |
  This binding describes a generic GPIO controller.
  Each GPIO controller must have a "gpio-controller" property.

properties:
  compatible:
    description: Compatible string for the GPIO controller.
    items:
      - enum:
          - brcm,bcm2835-gpio
          - nvidia,tegra20-gpio
          - ti,omap4-gpio

  reg:
    description: Address and length of the register map.
    maxItems: 1

  gpio-controller:
    description: Boolean property indicating this node is a GPIO controller.
    type: boolean

  "#gpio-cells":
    description: Number of cells in a GPIO specifier.
    enum: [1, 2]
    default: 2

required:
  - compatible
  - reg
  - gpio-controller
  - "#gpio-cells"

additionalProperties: false

examples:
  - |
    gpio@50000000 {
        compatible = "brcm,bcm2835-gpio";
        reg = <0x50000000 0x1000>;
        gpio-controller;
        #gpio-cells = <2>;
    };

阅读绑定文档的关键步骤：

1. 查看 title 和 description：了解该绑定描述的是什么设备。
2. 检查 compatible 列表：确认你的设备是否在支持的兼容字符串列表中。
3. 分析 properties 段：区分哪些是 required（必须）属性，哪些是 optional（可选）属性。
4. 理解属性类型：boolean（布尔）、uint32（32位整数）、string（字符串）、phandle（句柄）等。
5. 参考 examples 段：示例代码展示了完整的设备树节点写法，是最直接的参考。

3.3 编写自定义绑定

当你需要为新的硬件设备编写驱动时，必须同时编写对应的绑定文档。以下是编写自定义绑定的标准流程和规范。

3.3.1 绑定文件模板

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/misc/my-custom-device.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: My Custom Device

maintainers:
  - Your Name <your.email@example.com>

description: |
  This binding describes a custom device that does XYZ.
  It uses MMIO registers and generates interrupts.

properties:
  compatible:
    description: Compatible string for the device.
    items:
      - const: vendor,my-custom-device

  reg:
    description: Register map base address and size.
    maxItems: 1

  interrupts:
    description: Interrupt number for the device.
    maxItems: 1

  clock-names:
    description: Names of the clocks.
    items:
      - const: bus
      - const: core

  clocks:
    description: Phandles to the clocks.
    minItems: 2
    maxItems: 2

  vendor-specific-prop:
    description: A vendor-specific property (example).
    $ref: /schemas/types.yaml#/definitions/uint32
    default: 0x100

required:
  - compatible
  - reg
  - interrupts

additionalProperties: false

examples:
  - |
    my-device@40000000 {
        compatible = "vendor,my-custom-device";
        reg = <0x40000000 0x1000>;
        interrupts = <0 42 4>;
        clocks = <&clkc 15>, <&clkc 16>;
        clock-names = "bus", "core";
        vendor-specific-prop = <0x200>;
    };

3.3.2 编写步骤

3.3.3 验证绑定文件

内核提供了专门的工具来验证绑定文件的正确性：

# 验证单个绑定文件
make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/misc/my-custom-device.yaml

# 验证所有绑定文件（耗时较长）
make dt_binding_check

# 验证设备树源文件是否匹配绑定
make dtbs_check DT_SCHEMA_FILES=my-custom-device.yaml

3.3.4 绑定文档与驱动的对应关系

3.3.5 绑定文档编写规范总结

• 命名规范：文件名使用 vendor,device.yaml 格式，如 ti,am335x-uart.yaml。
• 兼容性：如果设备有多个版本，使用 enum 列出所有兼容字符串。
• 属性复用：尽量复用内核已有的属性定义（如 reg、interrupts），避免重复发明轮子。
• 文档完整性：每个属性都要有 description，说明其作用和取值范围。
• 示例有效性：examples 中的代码必须能通过 dtbs_check 验证。