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

# Locate and modify device trees

Device tree source files for each Qualcomm<sup>®</sup> 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<sup>®</sup> DTS and DTSI files are located in the kernel source tree under:

```text theme={null}
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
[Locate platform DTS files for a target](#locate-platform-dts-files-for-a-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:

```text theme={null}
KERNEL_DEVICETREE = " \
                     qcom/<SoC>-<board>-<variant>.dtb \
                     "
```

<Tabs>
  <Tab title="QCS6490">
    **Table: Qualcomm device tree source — Dragonwing<sup>™</sup> RB3 Gen 2**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/sc7280.dtsi` | The QCS6490 SoC is derived from SC7280 SoC. |
    | `arch/arm64/boot/dts/qcom/qcs6490-rb3gen2.dts` | Device tree source for the QCS6490 Dragonwing™ RB3 Gen 2 Development Kit. |
    | `arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-vision-mezzanine.dts` | QCS6490 Dragonwing™ RB3 Gen 2 vision Mezzanine Development Kit. |
    | `arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-industrial-mezzanine.dts` | QCS6490 Dragonwing™ RB3 Gen 2 industrial Mezzanine Development Kit. |
  </Tab>

  <Tab title="IQ-9075">
    **Table: Qualcomm device tree source — Dragonwing™ IQ-9075**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/lemans.dtsi` | The Dragonwing<sup>™</sup> IQ-9075 SoC is derived from Lemans. |
    | `arch/arm64/boot/dts/qcom/lemans-el2.dtso` | EL2 overlay applied to all IQ-9075 board variants for KVM environments. |
    | `arch/arm64/boot/dts/qcom/lemans-ride-common.dtsi` | Common DTSI for Qualcomm Linux development kits based on Lemans. |
    | `arch/arm64/boot/dts/qcom/qcs9100-ride.dts` and `qcs9100-ride-r3.dts` | Qualcomm Linux development kit for Dragonwing<sup>™</sup> IQ-9075 ride. |
    | `arch/arm64/boot/dts/qcom/lemans-evk.dts` | Qualcomm Linux development kit for the Dragonwing<sup>™</sup> IQ-9075 EVK. |
  </Tab>

  <Tab title="IQ-8275">
    **Table: Qualcomm device tree source — Dragonwing™ IQ-8275**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/qcs8300.dtsi` | The Dragonwing<sup>™</sup> IQ-8275 SoC is derived from QCS8300 (Monaco). |
    | `arch/arm64/boot/dts/qcom/monaco-el2.dtso` | EL2 overlay applied to all IQ-8275 board variants for KVM environments. |
    | `arch/arm64/boot/dts/qcom/qcs8300-ride.dts` | Qualcomm Linux development kit for Dragonwing<sup>™</sup> IQ-8275 ride. |
    | `arch/arm64/boot/dts/qcom/monaco-evk.dts` | Qualcomm Linux development kit for the Dragonwing<sup>™</sup> IQ-8275 EVK. |
    | `arch/arm64/boot/dts/qcom/monaco-staging.dtso` | Staging overlay carrying nodes not yet in the upstream Monaco DTSI. |
    | `arch/arm64/boot/dts/qcom/monaco-evk-camx.dtso` | CAMX camera overlay for the IQ-8275 EVK. |
  </Tab>

  <Tab title="IQ-615">
    **Table: Qualcomm device tree source — Dragonwing™ IQ-615**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/qcs615.dtsi` | Base configuration file for Dragonwing IQ-615 SoC. |
    | `arch/arm64/boot/dts/qcom/qcs615-ride.dts` | Base configuration file for Dragonwing IQ-615 ride. |
  </Tab>

  <Tab title="IQ-X7181">
    **Table: Qualcomm device tree source — Dragonwing™ IQ-X7181**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/hamoa.dtsi` | The Dragonwing<sup>™</sup> IQ-X7181 SoC is derived from Hamoa. |
    | `arch/arm64/boot/dts/qcom/hamoa-iq-x7181-evk.dts` | Qualcomm Linux development kit for the Dragonwing<sup>™</sup> IQ-X7181 EVK. |
    | `arch/arm64/boot/dts/qcom/hamoa-staging.dtso` | Staging overlay carrying nodes not yet in the upstream Hamoa DTSI. |
    | `arch/arm64/boot/dts/qcom/hamoa-evk-camx.dtso` | CAMX camera overlay for the IQ-X7181 EVK. |
  </Tab>

  <Tab title="IQ-X5121">
    **Table: Qualcomm device tree source — Dragonwing™ IQ-X5121**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/purwa.dtsi` | The Dragonwing<sup>™</sup> IQ-X5121 SoC is derived from Purwa. |
    | `arch/arm64/boot/dts/qcom/purwa-iq-x5121-evk.dts` | Qualcomm Linux development kit for the Dragonwing<sup>™</sup> IQ-X5121 EVK. |
    | `arch/arm64/boot/dts/qcom/purwa-staging.dtso` | Staging overlay carrying nodes not yet in the upstream Purwa DTSI. |
    | `arch/arm64/boot/dts/qcom/purwa-evk-camx.dtso` | CAMX camera overlay for the IQ-X5121 EVK. |
  </Tab>

  <Tab title="IQ-2390">
    **Table: Qualcomm device tree source — Dragonwing™ IQ-2390**

    | Device tree source | Details |
    | :-: | :-: |
    | `arch/arm64/boot/dts/qcom/shikra.dtsi` | Base device tree for Dragonwing IQ-2390 SoC. |
    | `arch/arm64/boot/dts/qcom/shikra-cqm-som.dtsi` | Base device tree for CQM variant SoM. |
    | `arch/arm64/boot/dts/qcom/shikra-iqs-som.dtsi` | Base device tree for IQS variant SoM. |
    | `arch/arm64/boot/dts/qcom/shikra-evk.dtsi` | Base device tree for common part of Dragonwing IQ-2390 EVK board. |
    | `arch/arm64/boot/dts/qcom/shikra-iqs-evk.dts` | Board DTS for IQS variant EVK board. |
    | `arch/arm64/boot/dts/qcom/shikra-cqm-evk.dts` | Board DTS for CQM variant EVK board. |
    | `arch/arm64/boot/dts/qcom/shikra-cqs-evk.dts` | Board DTS for CQS variant EVK board. |
  </Tab>
</Tabs>

<Note>
  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`.
</Note>

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:

```dts theme={null}
/* 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:

```dts theme={null}
&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:

```dts theme={null}
&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 theme={null}
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:

```text theme={null}
KERNEL_DEVICETREE = " \
                     qcom/qcs6490-rb3gen2.dtb \
                     qcom/qcs6490-my-board.dtb \
                     "
```

<Note>
  See `meta-qcom/conf/machine/*.conf` for the machine configuration files for
  all supported SoCs.
</Note>

### 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](./device-tree-architecture#fit-based-dtb-packaging).

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

```bitbake theme={null}
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**

| File | Description |
| - | - |
| `dtb-qcs6490-my-board-image.vfat` | VFAT partition image containing `combined-dtb.dtb`. Written to the device DTB partition. |
| `dtb.bin` | Inside the qcomflash tarball. Copy of the VFAT image flashed to the DTB partition. |

To update only the DTB partition during iterative bring-up:

```bash theme={null}
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](https://www.devicetree.org/specifications/) and
[Linux and the Devicetree](https://docs.kernel.org/devicetree/usage-model.html).