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

# Build & deploy DTBs

After modifying a DTS file, rebuild the affected DTBs, deploy them to the target device, and confirm the correct device tree was loaded at boot.

## Build DTBs with Yocto

DTBs are built automatically as part of a full Yocto image build. To rebuild
only the device trees after a DTS change without a full image rebuild:

1. Enter a kas shell:

```bash theme={null}
kas shell meta-qcom/ci/<SoC>-<board>.yml:meta-qcom/ci/qcom-distro.yml
```

2. Force the kernel recipe to recompile (picks up DTS changes):

```bash theme={null}
bitbake -c compile -f linux-qcom
```

3. Rebuild the device image to repackage the updated DTBs into `dtb.bin`:

```bash theme={null}
bitbake qcom-multimedia-image
```

Output DTB files are placed under `tmp/deploy/images/<machine>/dtbs/`.

### Deploy DTBs to the device

After a full Yocto build, flash the complete image to update all partitions
including the DTB partition:

```bash theme={null}
cd build/tmp/deploy/images/<Machine>/<Image>-*.rootfs.qcomflash/
fastboot flash dtb_a dtb.bin
fastboot reboot
```

## Build DTBs standalone (without Yocto)

When using the `kmake` standalone workflow, build only the device trees with:

```bash theme={null}
kmake O=../kobj ARCH=arm64 dtbs
```

The resulting `.dtb` and `.dtbo` files are placed in
`../kobj/arch/arm64/boot/dts/qcom/`.

### Package multiple dtbs as FIT image

To package them into a flashable `dtb.bin` FIT image, use `make_fitimage.sh`
from the [qcom-dtb-metadata](https://github.com/qualcomm-linux/qcom-dtb-metadata)
repository (requires the `kmake-image` Docker toolchain):

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

### Package dtb as single default image

To include your dtb as single and default device tree blob to be picked by uefi
during boot, use `generate_boot_bins.sh` to package dtb.bin, passing explicitly
your dtb to it.

```bash theme={null}
kmake-image-run generate_boot_bins.sh dtb
  --input <path/to/your-custom-dtb> \
  --output image/
```

For full standalone setup instructions, see
[Build the kernel without Yocto](./build-kernel-standalone).

For `kmake-image` utilities refer its [project readme](https://github.com/qualcomm-linux/kmake-image/).

### Deploy DTBs to the device

After generating `dtb.bin` with `make_fitimage.sh` that packages multiple dtbs
or `generate_boot_bins.sh` that packages single dtb:

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

<Note>
  Flash both `efi.bin` and `dtb.bin` together after a kernel or DTS change to
  keep the kernel and device tree in sync. See
  [Install & boot the kernel](./install-and-boot-the-kernel#deploy-kernel-artifacts)
  for the full incremental flash sequence.
</Note>

## Validate DTB selection at boot

After the device reboots, confirm the expected device tree was loaded.

**Check the loaded compatible string:**

```bash theme={null}
cat /proc/device-tree/compatible
```

The output should match the `compatible` string of your board DTS. For example,
for a QCS6490 RB3 Gen 2:

```text theme={null}
qcom,qcs6490-rb3gen2
qcom,qcs6490
```

**Inspect the full device tree at runtime:**

```bash theme={null}
dtc -I fs /proc/device-tree 2>/dev/null | head -30
```

**Check the board model from dmesg:**

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

If the wrong DTB was selected or the device fails to boot, see
[Common DT issues & fixes](./common-dt-issues).