> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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.bin` 中缺少预期的 DTB。

\*\*原因：\*\*machine 配置中的 `KERNEL_DEVICETREE` 或
`LINUX_QCOM_KERNEL_DEVICETREE` 未列出该 DTB 文件名。

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

```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 配置都不匹配。
* 修改 machine 配置后没有重新烧写 `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` 文件中重新排列配置顺序：更具体的条目必须出现在
   通用条目之前。

***

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

\*\*症状：\*\*某个外设在 `/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)。