Skip to main content
Device tree issues frequently appear during platform bring-up. The sections below cover errors from build time through runtime.
For device tree troubleshooting related to the boot architecture and DTB selection algorithm, see Device tree architecture.

​
DTB compilation errors

​
Missing dt-bindings header

Symptom: The kernel build fails with: 
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:
find <kernel_src>/include/dt-bindings -name "*.h" | grep <name>
  1. If the header is missing, either backport it from a newer kernel or replace the #include with the numeric constant it defines.
  2. 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: 
# 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: 
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: 
    # On the host
mount -o loop -t vfat dtb.bin /mnt/
fdtdump /mnt/combined-dtb.bin | grep -i model
    if using FIT-based packaging: 
    # 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: 
qcom,<soc>[-<soc-sku>][-<socver>]-<board>[-<boardrev>]
          [-<peripheral-subtype>][-<storage-type>]
  1. Add or correct the FIT_DTB_COMPATIBLE entry in conf/machine/include/fit-dtb-compatible.inc and rebuild dtb.bin.
  2. Reflash to the dtb_a partition: 
fastboot flash dtb_a dtb.bin
Diagnosis steps:
  1. Collect UEFI serial logs. Identify the Configuration From BoardParam line. For example:
ParseFitDt: Configuration From BoardParam
qcom, qcs6490, socv1.0, iot, r2.0, subtype0, emmc, nand, sdcard, ufs, 4GB, softsku0
  1. Compare the configuration-compatible string against the BoardParam output and identify any mismatched substring.
  2. Decode the FIT image into the ITS file and update the config compatible string to align with the BoardParam value.
  3. 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: 
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: 
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:
grep -rn "<device-name>" arch/arm64/boot/dts/qcom/
  1. Check dmesg for probe errors:
dmesg | grep -i "probe\|defer\|<driver-name>"
  1. 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.
  2. After editing the DTS, rebuild and reflash dtb.bin: 
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): 
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): 
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.
DTB overlay via EFI variable applies to QCS6490, IQ-9075, and IQ-8275 only. IQ-615 EVK uses module-level configuration instead.
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:
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
  1. After rebooting, confirm the overlay was applied from the UEFI serial log:
Variable VendorDtbOverlays read successfully. Data: camx
ProcessQcomRuntimeOverlayRequest: Parsed camx
  1. To clear the overlay and revert to the default DTB:
efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -d
For additional boot failure and serial console troubleshooting, see Troubleshoot kernel issues.