> ## 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.

# Common DT issues & fixes

Device tree issues frequently appear during platform bring-up. The sections below cover errors from build time through runtime.

<Note>
  For device tree troubleshooting related to the boot architecture and DTB
  selection algorithm, see
  [Device tree architecture](./device-tree-architecture#boot-time-dtb-selection-flow).
</Note>

## DTB compilation errors

### Missing dt-bindings header

**Symptom:** The kernel build fails with:

```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
```

**Cause:** A DTS file references a header from `dt-bindings/` that does not
exist at the kernel version being built. This typically happens when a
downstream DTS is based on a newer kernel, or when a new binding header has not
yet been upstreamed.

**Fix:**

1. Confirm the header path exists in the kernel source:

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

2. If the header is missing, either backport it from a newer kernel or replace
   the `#include` with the numeric constant it defines.

3. For Yocto builds, verify the kernel recipe `SRCREV` matches the DTS source
   revision being used.

### DTB not present in FIT image

**Symptom:** The Yocto build completes but the expected DTB is absent from
`dtb.bin`.

**Cause:** The DTB filename is not listed in `KERNEL_DEVICETREE` or
`LINUX_QCOM_KERNEL_DEVICETREE` in the machine configuration.

**Fix:** Add the DTB path to the machine configuration and rebuild:

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

Rebuild and reflash `dtb.bin` to the `dtb_a` partition.

***

## Boot failures

### No DTB loaded due to FIT configuration match failure

**Symptom:** The device fails to boot. UEFI serial log shows:

```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)
```

**Cause:** UEFI iterated all FIT configurations in `dtb.bin` and found no
`compatible` string that matched the hardware identifiers (chip ID, board type,
board revision, peripheral subtype). This happens when:

* The `FIT_DTB_COMPATIBLE` entry is missing or misspelled.
* The hardware board subtype does not match any FIT configuration.
* `dtb.bin` was not reflashed after modifying the machine configuration.

**Fix:**

1. Verify the DTB is included in the packaged `dtb.bin`:

   if using legacy concatenated dtb packaging:

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

   if using FIT-based packaging:

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

   ```
2. Compare the compatible strings present against the hardware IDs the board
   reports. The compatible string format is:

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

3. Add or correct the `FIT_DTB_COMPATIBLE` entry in
   `conf/machine/include/fit-dtb-compatible.inc` and rebuild `dtb.bin`.

4. Reflash to the `dtb_a` partition:

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

**Diagnosis steps:**

1. Collect UEFI serial logs. Identify the Configuration From BoardParam line.
   For example:

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

2. Compare the configuration-compatible string against the BoardParam output and
   identify any mismatched substring.

3. Decode the FIT image into the ITS file and update the config compatible string
   to align with the BoardParam value.

4. If no DTB matches the board’s subtype combination, add the required
   `FIT_DTB_COMPATIBLE` entry and rebuild `dtb.bin`.

### DTB authentication failure

**Symptom:** UEFI serial log shows:

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

**Cause:** The `dtb.bin` image was modified after signing, or a mismatched
`.sgn` file was used.

**Fix:** Use unsigned development firmware, or regenerate `dtb.bin` and the
corresponding signature using the correct signing keys.

### Wrong DTB selected at boot

**Symptom:** The device boots but unexpected peripherals are enumerated, or
`dmesg` shows an unexpected board model:

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

**Cause:** A FIT configuration with an overly generic `compatible` string
matched before the intended one. FIT configurations are evaluated in order
(`conf-1`, `conf-2`, …) and the first match wins.

**Fix:**

1. Identify which configuration was selected by checking the UEFI serial log
   for `FindConfigToBoot`.

2. Make the intended configuration's `compatible` string more specific by
   adding board subtype, revision, or storage-type tokens so it matches before
   the generic entry.

3. Reorder configurations in the `.its` file if necessary: more specific
   entries must appear before generic ones.

***

## Peripheral not probing after boot

**Symptom:** A peripheral is absent from `/dev`, its driver is not in `lsmod`,
or `dmesg` shows a probe failure.

**Cause:** Common causes include:

* The peripheral node is missing from the DTS file.
* The node is disabled (`status = "disabled"`).
* A required clock, regulator, or pinctrl dependency is missing or not enabled.
* The `compatible` string in the DTS does not match the driver's
  `of_device_id` table.

**Fix:**

1. Confirm the device node is present and enabled:

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

2. Check `dmesg` for probe errors:

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

3. If the node shows `probe deferred`, a dependency (clock, power domain,
   pinctrl) is not yet available. Verify all phandle references in the node
   resolve to enabled nodes.

4. After editing the DTS, rebuild and reflash `dtb.bin`:

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

***

## DT changes not reflected on device

**Symptom:** DTS edits have no effect after reboot; the old peripheral
configuration is still active.

**Cause:** The modified DTB was not repackaged into `dtb.bin` and reflashed.
The device continues to boot from the stale `dtb_a` partition.

**Fix (Yocto workflow):**

```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
```

**Fix (standalone workflow):**

```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 not applied

**Symptom:** An expected overlay (for example, the CamX camera overlay) is not
active after reboot. The UEFI log does not mention the overlay name.

<Note>
  DTB overlay via EFI variable applies to QCS6490, IQ-9075, and IQ-8275 only.
  IQ-615 EVK uses module-level configuration instead.
</Note>

**Cause:** The EFI variable `VendorDtbOverlays` was not set, or was set after
the UEFI boot stage had already read it.

**Fix:**

1. Set the EFI variable and reboot:

```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. After rebooting, confirm the overlay was applied from the UEFI serial log:

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

3. To clear the overlay and revert to the default DTB:

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

For additional boot failure and serial console troubleshooting, see
[Troubleshoot kernel issues](./troubleshoot-kernel-issues).