Skip to main content
Device tree source files for each Qualcomm® Linux board are present in arch/arm64/boot/dts/qcom/ and follow a two-tier SoC/board structure. The following provides the platform details, the corresponding device trees, and common customization patterns for platform bring-up.

​
Device tree source location

All Qualcomm® DTS and DTSI files are located in the kernel source tree under: 
arch/arm64/boot/dts/qcom/
The file naming convention follows the same <SoC>-<board>-<variant> pattern used by Yocto machine configurations. For the list of DTS files by target, see Platform DTS files by target below.

​
Locate platform DTS files for a target

The KERNEL_DEVICETREE variable in conf/machine/<SoC>-<board>-<variant>.conf selects which DTBs are built and packaged: 
KERNEL_DEVICETREE = " \
                     qcom/<SoC>-<board>-<variant>.dtb \
                     "
Table: Qualcomm device tree source — Dragonwing™ RB3 Gen 2
Device tree sourceDetails
arch/arm64/boot/dts/qcom/sc7280.dtsiThe QCS6490 SoC is derived from SC7280 SoC.
arch/arm64/boot/dts/qcom/qcs6490-rb3gen2.dtsDevice tree source for the QCS6490 Dragonwing™ RB3 Gen 2 Development Kit.
arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-vision-mezzanine.dtsQCS6490 Dragonwing™ RB3 Gen 2 vision Mezzanine Development Kit.
arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-industrial-mezzanine.dtsQCS6490 Dragonwing™ RB3 Gen 2 industrial Mezzanine Development Kit.
In kernel v6.19 and later, SoC DTSI names are updated to reflect actual SoC names: sc7280.dtsi → kodiak.dtsi, qcs8300.dtsi → monaco.dtsi, qcs615.dtsi → talos.dtsi.
Device tree files suffixed with el2 support Linux running at exception Level 2 (EL2) for KVM. Use EL2-specific DTBs only when Linux must operate as a KVM hypervisor.

​
Common customization patterns

Common customization with device trees are listed below.

​
Enable or disable a peripheral node

To enable a node that is declared but disabled in the SoC DTSI: 
/* In your board DTS, override the status property */
&uart5 {
    status = "okay";
};
To disable a node enabled by the SoC DTSI, mark it’s status disabled: 
&gpu {
    status = "disabled";
};

​
Add a new peripheral

To add a new device node or extend an existing bus node in the board DTS, follow corresponding device tree binding guidance. As an example add following for an i2c device: 
&i2c2 {
    status = "okay";

    sensor@48 {
        compatible = "ti,tmp102";
        reg = <0x48>;
    };
};
Always include the required clock, pinctrl, and power-domain references with the device node. Missing dependencies cause probe deferrals at boot.

​
Add a new DTB to the kernel build

To integrate a new platform device tree into the kernel build, add an entry to the Qualcomm Makefile: 
diff --git a/arch/arm64/boot/dts/qcom/Makefile b/arch/arm64/boot/dts/qcom/Makefile
--- a/arch/arm64/boot/dts/qcom/Makefile
+++ b/arch/arm64/boot/dts/qcom/Makefile
+dtb-$(CONFIG_ARCH_QCOM)        += qcs6490-my-board.dtb
 dtb-$(CONFIG_ARCH_QCOM)        += qcs6490-rb3gen2.dtb

​
Include the DTB in the machine configuration

Update meta-qcom/conf/machine/qcs6490-rb3gen2-core-kit.conf to include the new device tree blob: 
KERNEL_DEVICETREE = " \
                     qcom/qcs6490-rb3gen2.dtb \
                     qcom/qcs6490-my-board.dtb \
                     "
See meta-qcom/conf/machine/*.conf for the machine configuration files for all supported SoCs.

​
Configure DTB boot selection

By default (QCOM_DTB_DEFAULT = "multi-dtb"), the build produces a FIT image that contains all DTBs. At boot, UEFI selects the matching DTB by comparing the board’s hardware compatible string with entries in fit-dtb-compatible.inc. For more information, see Device tree architecture. FIT-based selection doesn’t work in following scenarios:
  • Your board’s compatible string has no matching entry in FIT_DTB_COMPATIBLE.
  • You are bringing up a new board and the firmware metadata doesn’t describe your compatible string in qcom-metadata.dtb.
  • You need to unconditionally force a specific DTB, regardless of what the firmware reports.
In these cases, override QCOM_DTB_DEFAULT in your machine configuration file (for example, meta-qcom/conf/machine/my-board.conf): 
QCOM_DTB_DEFAULT = "qcs6490-my-board"
KERNEL_DEVICETREE = "qcs6490-my-board.dtb"
qcs6490-my-board is the DTB stem, which is the filename without the .dtb extension. Setting QCOM_DTB_DEFAULT to any value other than “multi-dtb” disables FIT image generation; the build produces only a single VFAT image for the specified DTB. After a successful build, the following DTB-related files appear under build/tmp/deploy/images/<MACHINE>/: Table: Build artifacts when QCOM_DTB_DEFAULT is set
FileDescription
dtb-qcs6490-my-board-image.vfatVFAT partition image containing combined-dtb.dtb. Written to the device DTB partition.
dtb.binInside the qcomflash tarball. Copy of the VFAT image flashed to the DTB partition.
To update only the DTB partition during iterative bring-up: 
fastboot flash dtb_a dtb.bin
fastboot reboot
UEFI selects <SoC>-my-board.dtb from the FIT image on the next boot. For more information, see The Devicetree Specification and Linux and the Devicetree.