4. 设备树工具链：dtc编译器、fdtdump、dt-utils工具的使用与调试技巧

设备树从源文件（.dts / .dtsi）到二进制（.dtb），再到内核解析与调试，离不开一套成熟的工具链。本章聚焦三大核心工具：dtc（设备树编译器）、fdtdump（二进制转储工具）以及 dt-utils（用户空间调试套件）。掌握这些工具，是排查中断绑定错误、验证设备树语法、分析硬件拓扑的必备技能。

4.1 dtc 编译器：从 .dts 到 .dtb 的桥梁

dtc（Device Tree Compiler）是设备树工具链的核心。它不仅完成源文件到二进制文件的编译，还支持反编译、语法检查、覆盖（overlay）合并等功能。

4.1.1 基本编译与反编译

4.1.2 编译流程与语法检查

dtc 在编译过程中会执行多轮检查：

• 词法/语法分析： 检查分号、花括号、引号是否匹配，属性值格式是否正确。
• 节点唯一性检查： 确保同一层级下没有重复的节点名称。
• 中断映射检查： 验证 interrupt-parent 引用的节点是否存在，interrupt-cells 数量是否匹配。
• 地址格式检查： 验证 reg 属性中的地址与 #address-cells、#size-cells 是否一致。

# 编译并显示详细警告
dtc -I dts -O dtb -o my_net.dtb my_net.dts -W all -E

# 仅检查语法，不生成 DTB
dtc -I dts -O dtb -o /dev/null my_net.dts -W all

4.1.3 dtc 编译流程 SVG 图

4.2 fdtdump：快速查看 DTB 内部结构

fdtdump 是一个轻量级工具，用于以可读格式转储 DTB 文件的内容。与 dtc 反编译不同，fdtdump 输出的是设备树的扁平化结构，更接近 DTB 在内存中的布局，适合快速查看节点路径和属性值。

4.2.1 基本用法

# 查看 DTB 文件结构
fdtdump /boot/dtb/am335x-boneblack.dtb

# 输出到文件以便分析
fdtdump /boot/dtb/am335x-boneblack.dtb > dtb_dump.txt

# 结合 grep 快速定位中断相关节点
fdtdump /boot/dtb/am335x-boneblack.dtb | grep -A 10 "interrupt"

4.2.2 输出格式解读

fdtdump 的输出包含三个主要部分：

• 头部信息： 显示 magic number（0xD00DFEED）、总大小、版本号、boot_cpuid_phys 等元数据。
• 内存预留块（memreserve）： 列出系统启动时需保留的内存区域。
• 节点树： 以缩进形式展示所有节点及其属性，属性值以十六进制和 ASCII 混合显示。

// fdtdump 输出示例（片段）
/dts-v1/;
// magic:               0xd00dfeed
// totalsize:          0x3b8 (952)
// off_dt_struct:      0x38
// off_dt_strings:     0x2f0
// version:            17

/ {
    model = "TI AM335x BeagleBone Black";
    compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";
    #address-cells = <0x1>;
    #size-cells = <0x1>;
    
    ocp {
        compatible = "simple-bus";
        #address-cells = <0x1>;
        #size-cells = <0x1>;
        ranges;
        
        mac: ethernet@4a100000 {
            compatible = "ti,cpsw";
            reg = <0x4a100000 0x800>;
            interrupts = <0x28 0x29 0x2a>;
            interrupt-parent = <&intc>;
        };
    };
};

4.3 dt-utils：用户空间设备树调试套件

dt-utils 是一组在用户空间操作设备树的工具，由 Pengutronix 维护。它允许开发者在不启动内核的情况下，模拟内核的设备树解析流程，特别适合验证中断映射、地址翻译等复杂逻辑。

4.3.1 核心工具列表

4.3.2 中断绑定调试实战

以下是一个典型的调试流程，用于验证网络设备的中断绑定是否正确：

1. 列出所有节点： dt-list my_net.dtb 确认 ethernet@4a100000 和 intc 节点存在。
2. 获取中断属性： dt-get my_net.dtb /ocp/ethernet@4a100000 interrupts 查看原始中断描述符。
3. 获取中断父节点： dt-get my_net.dtb /ocp/ethernet@4a100000 interrupt-parent 确认 phandle 指向正确的控制器。
4. 验证中断控制器： dt-get my_net.dtb /ocp/interrupt-controller@48200000 #interrupt-cells 确认 cells 数量。
5. 修改并测试： 如果发现中断号错误，使用 dt-set my_net.dtb /ocp/ethernet@4a100000 interrupts 0x2a 0x2b 0x2c 临时修正。

# 完整调试示例
# 1. 列出所有节点
dt-list my_net.dtb

# 2. 获取网络设备的中断属性（原始十六进制）
dt-get my_net.dtb /ocp/ethernet@4a100000 interrupts
# 输出: 0x00000028 0x00000029 0x0000002a

# 3. 获取中断父节点 phandle
dt-get my_net.dtb /ocp/ethernet@4a100000 interrupt-parent
# 输出: 0x00000001

# 4. 查找 phandle=1 的节点
dt-list -p my_net.dtb | grep "phandle=1"
# 输出: /ocp/interrupt-controller@48200000

# 5. 验证该控制器的 #interrupt-cells
dt-get my_net.dtb /ocp/interrupt-controller@48200000 #interrupt-cells
# 输出: 0x00000001  (表示每个中断只用一个 cell)

4.3.3 dt-utils 调试流程 SVG 图

4.4 工具链对比与选择策略

4.5 常见调试场景与避坑指南

• 场景一：中断号偏移 —— 使用 fdtdump 查看 interrupts 属性值，与芯片手册对比。注意 GIC 的中断号通常是 SPI 中断号 + 32（如 SPI 中断 28 在设备树中应写为 60）。
• 场景二：interrupt-parent 指向错误 —— 使用 dt-utils 的 dt-get 获取 phandle，再通过 dt-list -p 反向查找对应节点，确认是否指向了正确的中断控制器。
• 场景三：#interrupt-cells 不匹配 —— 父节点定义 3 cells（如 GICv3 的 PPI/SPI/LPI 标志），但子节点只提供 2 个值。dtc 的 -W all 可以检测此类问题。
• 场景四：overlay 加载失败 —— 编译 overlay 时必须使用 -@ 参数生成符号节点，否则内核无法解析 __fixups__ 表。

# 场景一：验证 GIC 中断号是否正确
# 假设芯片手册说 SPI 中断 28，设备树中应写 28 + 32 = 60
fdtdump my_net.dtb | grep -A 2 "ethernet"
# 输出: interrupts = <0x3c>;  # 0x3c = 60，正确

# 场景三：检查 #interrupt-cells 是否匹配
dtc -I dts -O dtb -o test.dtb test.dts -W all 2>&1 | grep "interrupt"
# 输出: Warning (interrupts_property): /ethernet@4a100000: interrupts property size (8) is too small for #interrupt-cells (12)