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 不在 dtb.bin 中。 原因： DTB 文件名未列在机器配置的 KERNEL_DEVICETREE 或 LINUX_QCOM_KERNEL_DEVICETREE 中。 修复： 将 DTB 路径添加到机器配置并重新构建：
重新构建并将 dtb.bin 重新刷写到 dtb_a 分区。

​
启动失败

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

症状： 设备无法启动。UEFI 串行日志显示：
原因： UEFI 遍历了 dtb.bin 中的所有 FIT 配置，未找到与硬件标识符（芯片 ID、开发板类型、开发板修订版本、外设子类型）匹配的 compatible 字符串。发生这种情况的原因包括：
  • FIT_DTB_COMPATIBLE 条目缺失或拼写错误。
  • 硬件开发板子类型与任何 FIT 配置都不匹配。
  • 修改机器配置后未重新刷写 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 文件中重新排列配置顺序：更具体的条目必须出现在通用条目之前。

​
启动后外设未探测

症状： 某个外设不在 /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：
有关其他启动失败和串行控制台故障排除，请参阅内核问题排查。