Skip to main content
设备树问题经常在平台启用（bring-up）期间出现。以下各节涵盖了从构建时到运行时的各种错误。
有关与启动架构和 DTB 选择算法相关的设备树故障排除，请参阅 设备树架构。

​
DTB 编译错误

​
缺少 dt-bindings 头文件

**症状：**内核构建失败并显示：
**原因：**某个 DTS 文件引用了 dt-bindings/ 中的头文件，而该头文件在 正在构建的内核版本中不存在。这通常发生在下游 DTS 基于较新的内核，或新的 绑定头文件尚未合入上游时。 修复：
  1. 确认头文件路径存在于内核源码中：
  1. 如果头文件缺失，可以从较新的内核回移（backport）它，或者用它定义的 数值常量替换 #include。
  2. 对于 Yocto 构建，请验证内核配方的 SRCREV 与所使用的 DTS 源码修订 版本相匹配。

​
FIT 镜像中不存在 DTB

**症状：**Yocto 构建完成，但 dtb.bin 中缺少预期的 DTB。 **原因：**machine 配置中的 KERNEL_DEVICETREE 或 LINUX_QCOM_KERNEL_DEVICETREE 未列出该 DTB 文件名。 **修复：**将 DTB 路径添加到 machine 配置并重新构建：
重新构建并将 dtb.bin 重新烧写到 dtb_a 分区。

​
启动失败

​
由于 FIT 配置匹配失败而未加载 DTB

**症状：**设备无法启动。UEFI 串口日志显示：
**原因：**UEFI 遍历了 dtb.bin 中的所有 FIT 配置，未找到与硬件标识符 （芯片 ID、开发板类型、开发板版本、外设子类型）匹配的 compatible 字符串。发生这种情况的原因包括：
  • FIT_DTB_COMPATIBLE 条目缺失或拼写错误。
  • 硬件开发板子类型与任何 FIT 配置都不匹配。
  • 修改 machine 配置后没有重新烧写 dtb.bin。
修复：
  1. 验证 DTB 已包含在打包的 dtb.bin 中： 如果使用传统的拼接式 dtb 打包：
    如果使用基于 FIT 的打包：
  2. 将存在的 compatible 字符串与开发板报告的硬件 ID 进行比较。compatible 字符串格式为：
  1. 在 conf/machine/include/fit-dtb-compatible.inc 中添加或更正 FIT_DTB_COMPATIBLE 条目，并重新构建 dtb.bin。
  2. 重新烧写到 dtb_a 分区：
诊断步骤：
  1. 收集 UEFI 串口日志。找到 Configuration From BoardParam 行。 例如：
  1. 将配置的 compatible 字符串与 BoardParam 输出进行比较，找出任何不匹配的 子字符串。
  2. 将 FIT 镜像解码为 ITS 文件，并更新配置的 compatible 字符串，使其与 BoardParam 值对齐。
  3. 如果没有 DTB 与开发板的子类型组合匹配，请添加所需的 FIT_DTB_COMPATIBLE 条目并重新构建 dtb.bin。

​
DTB 认证失败

**症状：**UEFI 串口日志显示：
原因：dtb.bin 镜像在签名后被修改，或使用了不匹配的 .sgn 文件。 **修复：**使用未签名的开发固件，或使用正确的签名密钥重新生成 dtb.bin 及对应的签名。

​
启动时选择了错误的 DTB

**症状：**设备可以启动，但枚举到了非预期的外设，或 dmesg 显示非预期的 开发板型号：
**原因：**某个具有过于宽泛的 compatible 字符串的 FIT 配置先于预期配置 被匹配。FIT 配置按顺序（conf-1、conf-2、…）评估，第一个匹配即胜出。 修复：
  1. 通过检查 UEFI 串口日志中的 FindConfigToBoot，确定选择了哪个配置。
  2. 通过添加开发板子类型、版本或存储类型标记，使预期配置的 compatible 字符串更加具体，从而使其先于通用条目被匹配。
  3. 必要时，在 .its 文件中重新排列配置顺序：更具体的条目必须出现在 通用条目之前。

​
启动后外设无法探测（probe）

**症状：**某个外设在 /dev 中不存在，其驱动程序不在 lsmod 中，或 dmesg 显示探测失败。 **原因：**常见原因包括：
  • DTS 文件中缺少该外设节点。
  • 节点被禁用（status = "disabled"）。
  • 缺少或未启用所需的时钟、稳压器或 pinctrl 依赖。
  • DTS 中的 compatible 字符串与驱动程序的 of_device_id 表不匹配。
修复：
  1. 确认设备节点存在且已启用：
  1. 检查 dmesg 中的探测错误：
  1. 如果节点显示 probe deferred，说明某个依赖项（时钟、电源域、 pinctrl）尚不可用。请验证节点中的所有 phandle 引用都解析到已启用的 节点。
  2. 编辑 DTS 后，重新构建并重新烧写 dtb.bin：

​
DT 更改未在设备上生效

**症状：**重启后 DTS 编辑没有任何效果；旧的外设配置仍然处于活动状态。 **原因：**修改后的 DTB 没有被重新打包进 dtb.bin 并重新烧写。设备 继续从过期的 dtb_a 分区启动。 修复（Yocto 工作流）：
修复（独立工作流）：

​
DTB overlay 未被应用

**症状：**重启后预期的 overlay（例如 CamX 相机 overlay）未生效。UEFI 日志中没有提到该 overlay 名称。
通过 EFI 变量应用 DTB overlay 仅适用于 QCS6490、IQ-9075 和 IQ-8275。 IQ-615 EVK 使用模块级配置代替。
**原因：**未设置 EFI 变量 VendorDtbOverlays，或者是在 UEFI 启动阶段 已经读取该变量之后才设置的。 修复：
  1. 设置 EFI 变量并重启：
  1. 重启后，从 UEFI 串口日志确认 overlay 已被应用：
  1. 要清除 overlay 并恢复为默认 DTB：
有关其他启动失败和串口控制台故障排除，请参阅 排查内核问题。