📚 课程目录第3章设备树配置基础

3. 设备树配置基础

设备树（Device Tree）是树莓派 Linux 内核描述硬件拓扑的核心机制。MIPI-DSI 显示驱动的正确加载，高度依赖设备树中 DSI 控制器节点、panel 节点以及 compatible 字符串的精确匹配。本节将回顾设备树基本语法，解析 MIPI-DSI 节点结构，并重点说明 panel 节点与驱动的匹配规则。

3.1 设备树语法回顾

设备树使用 .dts（Device Tree Source）文本格式描述硬件。树莓派在启动时，引导程序会将 .dtb（Device Tree Blob）传递给内核。以下是必须掌握的核心语法元素：

语法元素	示例	说明
根节点	`/ { ... };`	设备树的顶层容器，所有设备节点挂载其下
节点定义	`dsi@7e209000 { ... };`	`节点名@基地址`，节点名应与设备类型对应
属性	`compatible = "brcm,bcm2835-dsi";`	键值对，用于驱动匹配；值可为字符串、整数、数组
reg	`reg = <0x7e209000 0x100>;`	描述设备地址范围：起始地址 + 长度
中断	`interrupts = <1 9>;`	指定中断号、触发类型等
时钟	`clocks = <&clk_dsi>;`	引用时钟提供者，驱动通过时钟框架获取频率
状态	`status = "okay";`	控制节点启用（okay）或禁用（disabled）

排查要点： 树莓派设备树采用叠加层（overlay）机制。用户自定义的 panel 节点应放在 overlay 中，避免直接修改主 bcm2711.dtsi。叠加层通过 dtoverlay= 在 config.txt 中加载。

3.2 MIPI-DSI 节点结构

树莓派 BCM2711（Pi 4）的 DSI 控制器节点位于 bcm2711.dtsi 中。一个典型的 DSI 节点包含以下关键部分：

dsi1: dsi@7e209000 {
    compatible = "brcm,bcm2835-dsi";
    reg = <0x7e209000 0x100>;
    interrupts = <1 9>;
    #address-cells = <1>;
    #size-cells = <0>;
    clocks = <&clk_dsi>,
             <&clk_dsi_byte>;
    clock-names = "dsi", "byte";
    status = "disabled";

    ports {
        #address-cells = <1>;
        #size-cells = <0>;

        port@0 {
            reg = <0>;
            dsi1_in: endpoint {
                remote-endpoint = <&vc4_dsi1>;
            };
        };

        port@1 {
            reg = <1>;
            dsi1_out: endpoint {
                remote-endpoint = <&panel_in>;
            };
        };
    };
};

节点结构的关键层级关系如下：

  DSI 节点 → ports → port@0（输入，连接 VC4 图形引擎）→ port@1（输出，连接 panel 节点）

其中 port@1 的 remote-endpoint 必须与 panel 节点中定义的 endpoint 一一对应，这是驱动建立数据通路的关键。

常见错误： 忘记在 DSI 节点中设置 status = "okay"，或 port@1 的 endpoint 引用名称拼写错误，导致内核无法将 DSI 控制器与 panel 连接起来。

3.3 panel 节点与 compatible 匹配

Panel 节点是设备树中描述物理显示面板的部分。驱动通过 compatible 属性查找对应的驱动程序。一个标准的 panel 节点示例如下：

&dsi1 {
    status = "okay";

    panel: panel@0 {
        compatible = "raspberrypi,official-7inch-panel",
                     "ilitek,ili9881c";
        reg = <0>;
        backlight = <&backlight>;
        reset-gpios = <&gpio 17 1>;

        port {
            panel_in: endpoint {
                remote-endpoint = <&dsi1_out>;
            };
        };
    };
};

compatible 匹配规则：

内核驱动使用 of_match_table 定义支持的 compatible 列表。
设备树中的 compatible 字符串按优先级从高到低排列，驱动会依次尝试匹配。
匹配成功时，驱动 probe 函数被调用；匹配失败则节点被忽略。

匹配层级	说明	故障表现
精确匹配	设备树 compatible 与驱动列表中的字符串完全一致	正常加载
模糊匹配	驱动使用 `of_match_node` 进行通配或别名匹配	可能加载，但功能异常
无匹配	设备树 compatible 不在任何驱动的匹配表中	驱动不加载，dmesg 报 `No driver found`

  排查技巧： 使用 dtc -I dtb -O dts /boot/overlays/your-overlay.dtbo 反编译设备树叠加层，检查 compatible 字符串是否与驱动源码中的 of_device_id 表一致。常见错误是字符串大小写或厂商前缀拼写错误。

3.4 常见设备树配置故障

以下是在树莓派 MIPI-DSI 调试中频繁遇到的设备树相关问题：

status 未设置 okay： DSI 控制器或 panel 节点默认 status = "disabled"，需在 overlay 中显式启用。
remote-endpoint 引用断裂： DSI 输出 endpoint 与 panel 输入 endpoint 的 remote-endpoint 未正确交叉引用，导致数据通路无法建立。
GPIO 资源冲突： reset-gpios 或 backlight 引用的 GPIO 已被其他设备占用，导致 panel 无法复位或背光不亮。
时钟依赖缺失： DSI 节点引用的时钟（如 clk_dsi_byte）在时钟控制器中未定义或频率错误。

快速验证方法： 在 /sys/firmware/devicetree/base 下查看设备树展开后的实际节点。例如 cat /sys/firmware/devicetree/base/dsi@7e209000/status 可确认节点是否启用。使用 ls -l /sys/class/drm/ 查看 DRM 设备是否注册成功。