Skip to content

build-dtb-image: add FIT DTB image generation mode for multi-DTB selection#121

Open
xinlon-z wants to merge 1 commit intoqualcomm-linux:mainfrom
xinlon-z:fit-dtb-image
Open

build-dtb-image: add FIT DTB image generation mode for multi-DTB selection#121
xinlon-z wants to merge 1 commit intoqualcomm-linux:mainfrom
xinlon-z:fit-dtb-image

Conversation

@xinlon-z
Copy link

@xinlon-z xinlon-z commented Mar 16, 2026

The existing build-dtb-image.sh only supported generating a combined (concatenated) DTB image. This approach does not allow UEFI to dynamically select the correct DTB at boot time based on hardware identity. Depends on PR #122

In the FIT DTB boot model:

  • Multiple DTBs and a qcom-metadata blob are packaged into a single FIT image (qclinux_fit.img).
  • UEFI reads the compatible string from each FIT configuration entry and matches it against the hardware identity (CDT) at boot time to select the correct DTB automatically.

Add --fit-image mode to build-dtb-image.sh to support FIT-based multi-DTB selection at boot time. In this mode, the script:

  • Extracts DTBs from a kernel .deb package or a dtb source directory
  • Clones qcom-dtb-metadata to obtain the its template and compiles qcom-metadata.dtb via dtc
  • Run mkimage to generate qclinux_fit.img (filename required by UEFI)
  • Packs the FIT image into a FAT-formatted bin for flashing to dtb partiton.

Usage example:
Build from kernel deb

sudo ./build-dtb-image.sh \
   --fit-image \
   --kernel-deb linux-kernel-7.0.0-rc2-arm64.deb \
   --out dtb.bin

Build from DTB source code

sudo ./build-dtb-image.sh \
   --fit-image \
   -dtb-src ../../../hamoa_evk/qcom-next/arch/arm64/boot/dts/qcom/ \
   --out dtb.bin

Output example:

$ sudo ./build-dtb-image.sh --fit-image --kernel-deb ../../../linux-kernel-7.0.0-rc2-23104211493-1-arm64.deb --out dtb.bin
[INFO] Extracting kernel .deb to: /tmp/kernel-deb-vX31NQ
[INFO] Using DTB source directory from .deb payload: /tmp/kernel-deb-vX31NQ/lib/firmware/7.0.0-rc2/device-tree
[INFO] FIT image mode enabled.
[INFO] FIT build working directory: /tmp/fit-build-AEC9Fm
[INFO] Cloning qcom-dtb-metadata...
Cloning into '/tmp/fit-build-AEC9Fm/qcom-dtb-metadata'...
remote: Enumerating objects: 216, done.
remote: Counting objects: 100% (92/92), done.
remote: Compressing objects: 100% (37/37), done.
remote: Total 216 (delta 75), reused 61 (delta 55), pack-reused 124 (from 1)
Receiving objects: 100% (216/216), 96.09 KiB | 643.00 KiB/s, done.
Resolving deltas: 100% (101/101), done.
[INFO] Reset qcom-dtb-metadata to commit 5d24fea316a512f85acf7a4528a118ce52223530
HEAD is now at 5d24fea Merge pull request #54 from yijiyang/main
[INFO] Copying DTBs from /tmp/kernel-deb-vX31NQ/lib/firmware/7.0.0-rc2/device-tree ...
[INFO] Compiling qcom-metadata.dts...
[INFO] qcom-metadata.dtb generated:
-rw-r--r-- 1 root root 2.1K Mar 16 19:21 /tmp/fit-build-AEC9Fm/fit_image/qcom-metadata.dtb
[INFO] Running mkimage to generate qclinux_fit.img...
FIT description: Qualcomm FIT Image for DTBs
Created:         Mon Mar 16 19:21:16 2026
 Image 0 (fdt-qcom-metadata.dtb)
  Description:  metadata for multi-DTB selection
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Unknown Image
  Compression:  uncompressed
  Data Size:    2073 Bytes = 2.02 KiB = 0.00 MiB
 Image 1 (fdt-qcm6490-idp.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    142922 Bytes = 139.57 KiB = 0.14 MiB
  Architecture: Unknown Architecture
 Image 2 (fdt-qcs6490-rb3gen2.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    191157 Bytes = 186.68 KiB = 0.18 MiB
  Architecture: Unknown Architecture
 Image 3 (fdt-qcs6490-rb3gen2-vision-mezzanine.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    191922 Bytes = 187.42 KiB = 0.18 MiB
  Architecture: Unknown Architecture
 Image 4 (fdt-qcs6490-rb3gen2-industrial-mezzanine.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    194151 Bytes = 189.60 KiB = 0.19 MiB
  Architecture: Unknown Architecture
 Image 5 (fdt-lemans-evk.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    199488 Bytes = 194.81 KiB = 0.19 MiB
  Architecture: Unknown Architecture
 Image 6 (fdt-qcs9100-ride.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    198616 Bytes = 193.96 KiB = 0.19 MiB
  Architecture: Unknown Architecture
 Image 7 (fdt-qcs9100-ride-r3.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    198638 Bytes = 193.98 KiB = 0.19 MiB
  Architecture: Unknown Architecture
 Image 8 (fdt-qcs8300-ride.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    174051 Bytes = 169.97 KiB = 0.17 MiB
  Architecture: Unknown Architecture
 Image 9 (fdt-monaco-evk.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    177149 Bytes = 173.00 KiB = 0.17 MiB
  Architecture: Unknown Architecture
 Image 10 (fdt-qcs615-ride.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    115667 Bytes = 112.96 KiB = 0.11 MiB
  Architecture: Unknown Architecture
 Image 11 (fdt-sa8775p-ride.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    198166 Bytes = 193.52 KiB = 0.19 MiB
  Architecture: Unknown Architecture
 Image 12 (fdt-sa8775p-ride-r3.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    198184 Bytes = 193.54 KiB = 0.19 MiB
  Architecture: Unknown Architecture
 Image 13 (fdt-hamoa-iot-evk.dtb)
  Description:  unavailable
  Created:      Mon Mar 16 19:21:16 2026
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    250733 Bytes = 244.86 KiB = 0.24 MiB
  Architecture: Unknown Architecture
 Configuration 0 (conf-1)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcm6490-idp.dtb
 Configuration 1 (conf-2)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs6490-rb3gen2.dtb
 Configuration 2 (conf-3)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs6490-rb3gen2-vision-mezzanine.dtb
 Configuration 3 (conf-4)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs6490-rb3gen2-industrial-mezzanine.dtb
 Configuration 4 (conf-5)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-lemans-evk.dtb
 Configuration 5 (conf-6)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-lemans-evk.dtb
 Configuration 6 (conf-7)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs9100-ride.dtb
 Configuration 7 (conf-8)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs9100-ride.dtb
 Configuration 8 (conf-9)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs9100-ride-r3.dtb
 Configuration 9 (conf-10)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs9100-ride-r3.dtb
 Configuration 10 (conf-11)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs8300-ride.dtb
 Configuration 11 (conf-12)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-monaco-evk.dtb
 Configuration 12 (conf-13)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs615-ride.dtb
 Configuration 13 (conf-14)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-qcs615-ride.dtb
 Configuration 14 (conf-15)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-sa8775p-ride.dtb
 Configuration 15 (conf-16)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-sa8775p-ride.dtb
 Configuration 16 (conf-17)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-sa8775p-ride-r3.dtb
 Configuration 17 (conf-18)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-sa8775p-ride-r3.dtb
 Configuration 18 (conf-19)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-hamoa-iot-evk.dtb
 Configuration 19 (conf-20)
  Description:  unavailable
  Kernel:       unavailable
  FDT:          fdt-hamoa-iot-evk.dtb
[INFO] qclinux_fit.img generated:
-rw-r--r-- 1 root root 2.4M Mar 16 19:21 /tmp/fit-build-AEC9Fm/fit_image/out/qclinux_fit.img
/tmp/fit-build-AEC9Fm/fit_image/out/qclinux_fit.img: Device Tree Blob version 17, size=3216, boot CPU=0, string block size=69, DT structure block size=3088
[INFO] Creating FAT image 'dtb.bin' (4 MB)...
4+0 records in
4+0 records out
4194304 bytes (4.2 MB, 4.0 MiB) copied, 0.00235445 s, 1.8 GB/s
[INFO] Using loop device: /dev/loop10
[INFO] Formatting /dev/loop10 as FAT with 4 KiB sector size...
[INFO] Mounting /dev/loop10 at /tmp/dtb-mnt-L9ox6T...
[INFO] Deployed qclinux_fit.img into FAT image.
[INFO] Files in image:
total 2.4M
-rwxr-xr-x 1 root root 2.4M Mar 16 19:21 qclinux_fit.img

…ction

The existing build-dtb-image.sh only supported generating a combined
(concatenated) DTB image. This approach does not allow UEFI to
dynamically select the correct DTB at boot time based on hardware
identity.

Add --fit-image mode to build-dtb-image.sh to support FIT-based
multi-DTB selection at boot time. In this mode, the script:
- Extracts DTBs from a kernel .deb package or a dtb source directory
- Clones qcom-dtb-metadata to obtain the its template and compiles
  qcom-metadata.dtb via dtc
- Run mkimage to generate qclinux_fit.img (filename required by UEFI)
- Packs the FIT image into a FAT-formatted bin for flashing to dtb
  partiton.

Signed-off-by: Xinzheng Long <xinzheng.long@oss.qualcomm.com>
@lool
Copy link

lool commented Mar 16, 2026

NB: I'm not a reviewer here

Generally, this is valuable and I'd like to use this; us there a change we can make the script generic enough that it can be used by people that would use qcom-dtb-metadata? Could we host the script there?

This is getting slightly complex for shell; would it make sense to pivot to Python? I love shell, up to a point :)

@bjordiscollaku
Copy link
Contributor

Did we agree on extending build-dtb-image (qcom-build-utils) to add FIT support? I had created this tool as interim solution to build combined dtb, until FIT support was there from boot team, but the tool to build FIT already exists on kmake image repository.

I also have a fork on kmake-image project, that adds support to build FIT dtb out of the a kernel deb package input (bjordiscollaku/kmake-image@da28ac8), in addition to a kernel source tree; had tested my fork locally and was able to generate FIT image successfully.

Question is, were do we keep this tool?

We have:

  • Metadata coming from qcom-dtb-metadata
  • Tool residing in kmake-image OR build-utils

This is a bit redundant I'd say, it'd be way cleaner to have both metadata and tool in same repo.

@shoudil
Copy link
Contributor

shoudil commented Mar 17, 2026

NB: I'm not a reviewer here

Generally, this is valuable and I'd like to use this; us there a change we can make the script generic enough that it can be used by people that would use qcom-dtb-metadata? Could we host the script there?

This is getting slightly complex for shell; would it make sense to pivot to Python? I love shell, up to a point :)

Hi @lool ,

Not sure if there is plan to merge repo kmake-image and qcom-dtb-metadata into one repo from kernel team ? I checked the two repos, looks image related generation scripts get maintained in kmage-image repo, qcom-dtb-metadata only include the dtb metadata.

I raised one issue for qcom-dtb-metadata, hope there will be some inputs/comments from kernel team.
qualcomm-linux/qcom-dtb-metadata#70

@shoudil
Copy link
Contributor

shoudil commented Mar 17, 2026

Did we agree on extending build-dtb-image (qcom-build-utils) to add FIT support? I had created this tool as interim solution to build combined dtb, until FIT support was there from boot team, but the tool to build FIT already exists on kmake image repository.

I also have a fork on kmake-image project, that adds support to build FIT dtb out of the a kernel deb package input (bjordiscollaku/kmake-image@da28ac8), in addition to a kernel source tree; had tested my fork locally and was able to generate FIT image successfully.

Question is, were do we keep this tool?

We have:

  • Metadata coming from qcom-dtb-metadata
  • Tool residing in kmake-image OR build-utils

This is a bit redundant I'd say, it'd be way cleaner to have both metadata and tool in same repo.

Hey @bjordiscollaku
Could we raise PR for this bjordiscollaku/kmake-image@da28ac8 as well ? if it's fine to merge to kmake-image repo, then we can directly use it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants