> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见 DT 问题与修复

设备树问题在平台启用（bring-up）期间经常出现。以下各节涵盖从构建时到运行时的错误。

<Note>
  有关与启动架构和 DTB 选择算法相关的设备树故障排除，请参阅[设备树架构](./device-tree-architecture#boot-time-dtb-selection-flow)。
</Note>

## DTB 编译错误

### 缺少 dt-bindings 头文件

**症状：** 内核构建失败并显示：

```text theme={null}
arch/arm64/boot/dts/qcom/qcm6490-idp.dts:8:10: fatal error:
dt-bindings/iio/qcom,spmi-adc7-pmk8350.h: No such file or directory
```

**原因：** DTS 文件引用了在当前构建的内核版本中不存在的 `dt-bindings/` 头文件。这通常发生在下游 DTS 基于更新的内核，或新的绑定头文件尚未合入上游时。

**修复：**

1. 确认头文件路径存在于内核源代码中：

```bash theme={null}
find <kernel_src>/include/dt-bindings -name "*.h" | grep <name>
```

2. 如果缺少头文件，可以从更新的内核中回移（backport）该文件，或将 `#include` 替换为其定义的数字常量。

3. 对于 Yocto 构建，请验证内核配方的 `SRCREV` 与所使用的 DTS 源代码修订版本匹配。

### FIT 镜像中不存在 DTB

**症状：** Yocto 构建完成，但预期的 DTB 不在 `dtb.bin` 中。

**原因：** DTB 文件名未列在机器配置的 `KERNEL_DEVICETREE` 或 `LINUX_QCOM_KERNEL_DEVICETREE` 中。

**修复：** 将 DTB 路径添加到机器配置并重新构建：

```text theme={null}
# In conf/machine/<soc>-<board>-<variant>.conf
KERNEL_DEVICETREE:append = " qcom/<soc>-<board>.dtb"
```

重新构建并将 `dtb.bin` 重新刷写到 `dtb_a` 分区。

***

## 启动失败

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

**症状：** 设备无法启动。UEFI 串行日志显示：

```text theme={null}
DtPlatformLoadDtb qcs6490-rb3gen2.dtb is loading failed with Status = E
DtPlatformDxeEntryPoint: no DTB blob could be loaded,
defaulting to ACPI (Status == Not Found)
```

**原因：** UEFI 遍历了 `dtb.bin` 中的所有 FIT 配置，未找到与硬件标识符（芯片 ID、开发板类型、开发板修订版本、外设子类型）匹配的 `compatible` 字符串。发生这种情况的原因包括：

* `FIT_DTB_COMPATIBLE` 条目缺失或拼写错误。
* 硬件开发板子类型与任何 FIT 配置都不匹配。
* 修改机器配置后未重新刷写 `dtb.bin`。

**修复：**

1. 验证 DTB 已包含在打包的 `dtb.bin` 中：

   如果使用传统的拼接式 dtb 打包：

   ```bash theme={null}
   # On the host
   mount -o loop -t vfat dtb.bin /mnt/
   fdtdump /mnt/combined-dtb.bin | grep -i model
   ```

   如果使用基于 FIT 的打包：

   ```bash theme={null}
   # On the host
   mount -o loop -t vfat dtb.bin /mnt/
   fdtdump /mnt/qclinux_fit.img | grep -i compatible

   ```
2. 将存在的 compatible 字符串与开发板报告的硬件 ID 进行比较。compatible 字符串格式为：

```text theme={null}
qcom,<soc>[-<soc-sku>][-<socver>]-<board>[-<boardrev>]
          [-<peripheral-subtype>][-<storage-type>]
```

3. 在 `conf/machine/include/fit-dtb-compatible.inc` 中添加或更正 `FIT_DTB_COMPATIBLE` 条目并重新构建 `dtb.bin`。

4. 重新刷写到 `dtb_a` 分区：

```bash theme={null}
fastboot flash dtb_a dtb.bin
```

**诊断步骤：**

1. 收集 UEFI 串行日志。找到 Configuration From BoardParam 行。例如：

```text theme={null}
ParseFitDt: Configuration From BoardParam
qcom, qcs6490, socv1.0, iot, r2.0, subtype0, emmc, nand, sdcard, ufs, 4GB, softsku0
```

2. 将配置的 compatible 字符串与 BoardParam 输出进行比较，找出不匹配的子字符串。

3. 将 FIT 镜像解码为 ITS 文件，并更新配置的 compatible 字符串以与 BoardParam 值保持一致。

4. 如果没有 DTB 与开发板的子类型组合匹配，请添加所需的 `FIT_DTB_COMPATIBLE` 条目并重新构建 `dtb.bin`。

### DTB 认证失败

**症状：** UEFI 串行日志显示：

```text theme={null}
DtPlatformLoadDtb qcs6490-rb3gen2.dtb is loaded
failed to authenticate image !
```

**原因：** `dtb.bin` 镜像在签名后被修改，或使用了不匹配的 `.sgn` 文件。

**修复：** 使用未签名的开发固件，或使用正确的签名密钥重新生成 `dtb.bin` 及相应的签名。

### 启动时选择了错误的 DTB

**症状：** 设备可以启动，但枚举出了意外的外设，或 `dmesg` 显示了意外的开发板型号：

```bash theme={null}
dmesg | grep -i model
```

**原因：** 具有过于宽泛 `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. 确认设备节点存在且已启用：

```bash theme={null}
grep -rn "<device-name>" arch/arm64/boot/dts/qcom/
```

2. 检查 `dmesg` 中的探测错误：

```bash theme={null}
dmesg | grep -i "probe\|defer\|<driver-name>"
```

3. 如果节点显示 `probe deferred`，则表示某个依赖项（时钟、电源域、pinctrl）尚不可用。验证节点中的所有 phandle 引用都解析到已启用的节点。

4. 编辑 DTS 后，重新构建并重新刷写 `dtb.bin`：

```bash theme={null}
fastboot flash dtb_a dtb.bin
fastboot reboot
```

***

## DT 更改未在设备上生效

**症状：** 重启后 DTS 编辑没有任何效果；旧的外设配置仍然生效。

**原因：** 修改后的 DTB 未重新打包到 `dtb.bin` 中并重新刷写。设备继续从过时的 `dtb_a` 分区启动。

**修复（Yocto 工作流）：**

```bash theme={null}
kas shell meta-qcom/ci/<machine.yml>:meta-qcom/ci/qcom-distro.yml
devtool build linux-qcom

cd build/tmp/deploy/images/<Machine>/<Image>-*.rootfs.qcomflash/
fastboot flash dtb_a dtb.bin
fastboot reboot
```

**修复（独立工作流）：**

```bash theme={null}
kmake-image-run make_fitimage.sh \
    --metadata artifacts/qcom-dtb-metadata/qcom-metadata.dts \
    --its artifacts/qcom-dtb-metadata/qcom-next-fitimage.its \
    --kobj kobj \
    --output images

fastboot flash dtb_a images/dtb.bin
fastboot reboot
```

***

## DTB overlay 未应用

**症状：** 预期的 overlay（例如 CamX 摄像头 overlay）在重启后未激活。UEFI 日志未提及该 overlay 名称。

<Note>
  通过 EFI 变量应用 DTB overlay 仅适用于 QCS6490、IQ-9075 和 IQ-8275。IQ-615 EVK 使用模块级配置。
</Note>

**原因：** 未设置 EFI 变量 `VendorDtbOverlays`，或在 UEFI 启动阶段已读取该变量之后才设置。

**修复：**

1. 设置 EFI 变量并重启：

```bash theme={null}
echo -n "camx" > /tmp/overlay
efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays \
    -w -f /tmp/overlay
efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -p
sync && reboot
```

2. 重启后，从 UEFI 串行日志确认 overlay 已应用：

```text theme={null}
Variable VendorDtbOverlays read successfully. Data: camx
ProcessQcomRuntimeOverlayRequest: Parsed camx
```

3. 要清除 overlay 并恢复为默认 DTB：

```bash theme={null}
efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -d
```

有关其他启动失败和串行控制台故障排除，请参阅[内核问题排查](./troubleshoot-kernel-issues)。