[PATCH v3 6/7] doc: document mkimage fatfs type and Qualcomm multi-DTB
Aswin Murugan
aswin.murugan at oss.qualcomm.com
Fri Apr 17 14:09:50 CEST 2026
Update doc/mkimage.1 to document the new fatfs image type,
the --fat-* long options, a fatfs entry in the CONFIGURATION
section, and two usage examples.
Add doc/board/qualcomm/multi_dtb.rst describing the
Qualcomm FIT-based multi-DTB packaging workflow for
Snapdragon platforms. The document covers:
- FIT ITS configuration and compatible string matching
- QCOM metadata binary format and identifier properties
- Guidelines for adding new socver/boardrev entries
- Step-by-step image creation using mkimage -T fatfs
Update doc/board/qualcomm/index.rst to include the new
multi_dtb page in the toctree.
Signed-off-by: Aswin Murugan <aswin.murugan at oss.qualcomm.com>
---
doc/board/qualcomm/index.rst | 1 +
doc/board/qualcomm/multi_dtb.rst | 352 +++++++++++++++++++++++++++++++
doc/mkimage.1 | 103 +++++++++
3 files changed, 456 insertions(+)
create mode 100644 doc/board/qualcomm/multi_dtb.rst
diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst
index 3238a68e859..fe4a4aecd60 100644
--- a/doc/board/qualcomm/index.rst
+++ b/doc/board/qualcomm/index.rst
@@ -10,6 +10,7 @@ Qualcomm
debugging
dragonboard410c
dragonwing
+ multi_dtb
rb3gen2
iq8
phones
diff --git a/doc/board/qualcomm/multi_dtb.rst b/doc/board/qualcomm/multi_dtb.rst
new file mode 100644
index 00000000000..fa9252ce1c4
--- /dev/null
+++ b/doc/board/qualcomm/multi_dtb.rst
@@ -0,0 +1,352 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Qualcomm FIT-Based Multi-DTB Support
+=====================================
+
+Overview
+--------
+
+Qualcomm supports multiple SoCs and boards within a single software release
+binary, which requires packaging all corresponding Device Tree Blobs (DTBs)
+into a single image. To ensure the appropriate DTB(O)s are selected for each
+platform, a mechanism for dynamic device tree selection is necessary.
+
+The Flattened Image Tree (FIT) format is a standard file format for packaging
+images widely used in the community. U-Boot leverages this format to facilitate
+DTB selection and meet platform-specific requirements. The appropriate DTB
+selected for the platform by U-Boot is passed to the OS at boot time.
+
+Terminology
+-----------
+
+- **FIT**: Flattened Image Tree
+- **DT**: Device Tree
+- **FDT**: Flattened Device Tree
+- **.its**: Image Tree Source
+- **.dtb**: Device Tree Blob
+
+References:
+
+- https://docs.u-boot.org/en/latest/usage/fit/index.html
+- https://fitspec.osfw.foundation/
+
+Design
+------
+
+The FIT-based approach, commonly adopted within the U-Boot community, offers a
+standardized solution for multi-DTB packaging. This design is the first
+implementation utilizing FIT to facilitate DT selection from a multi-DTB
+binary.
+
+FIT provides a flexible and extensible format to support multiple components
+(device tree, kernel image, ramdisk). It also supports multiple configurations
+so that the same FIT can be used to boot multiple platforms, with some
+components in common (e.g., kernel) and some specific to that platform (e.g.,
+device tree). The Flattened Image Tree Specification (FITSpec) suggests the
+image selection mechanism.
+
+Detailed Description
+^^^^^^^^^^^^^^^^^^^^
+
+1. In the FIT ITS file, each configuration comprises a compatible string along
+ with a declaration for the base DT blob and the overlays in sequence. A few
+ such configuration node examples are provided in the .its tree format below.
+
+2. This implementation uses a metadata binary structured in DT format for
+ selecting the appropriate configuration. A node, named
+ ``fdt-qcom-metadata.dtb``, for the metadata binary is provided under the
+ ``images`` node in the FIT tree with type ``qcom_metadata``.
+
+3. The compatible string suffixes in the FIT tree can be put in any order, but
+ the node corresponding to each suffix must be present in the
+ ``qcom-dtb-metadata`` binary. If any new suffix is introduced, it must be
+ added to the metadata (refer to ``qcom-dtb-metadata.dts`` below this
+ section). The new suffix sub-node must be added under the relevant node.
+
+ Suggested pattern::
+
+ <soc>-<soc-sku>-<socver>-<board>-<boardrev>-<board-subtype-peripheral-subtype>-<board-subtype-storage-type>-<board-subtype-memory-size>-<softsku>-<oem>
+
+4. Each of the suffixes inside the compatible string must be an exact match for
+ a DTB to be selected. Upon any mismatch, a configuration is rejected and the
+ search moves ahead with other available configurations.
+
+5. The compatible string that gets matched has its corresponding DTB(O)s
+ selected for boot.
+
+FIT ITS Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+Each configuration in the FIT ITS file comprises a compatible string along
+with a declaration for the base DT blob and overlays in sequence. Example::
+
+ config-1 {
+ compatible = "qcom,soc";
+ fdt = "fdt-soc-v2.dtb";
+ };
+
+ config-2 {
+ compatible = "qcom,soc-socv1.0";
+ fdt = "fdt-soc-v1.dtb";
+ };
+
+Refer: https://github.com/qualcomm-linux/qcom-dtb-metadata/blob/main/qcom-fitimage.its
+
+DTB Metadata Description and Parsing
+--------------------------------------
+
+The QCOM metadata supports the following DT nodes: ``soc``, ``soc-sku``,
+``socver``, ``board``, ``boardrev``, ``board-subtype-peripheral-subtype``,
+``board-subtype-storage-type``, ``board-subtype-memory-size``, ``softsku``
+and ``oem``. Sub-nodes of the respective type can be added under each node.
+
+The SoC specific identifiers are encapsulated in DT properties named
+``msm-id`` and ``socver-id``.
+
+Identifier Properties
+^^^^^^^^^^^^^^^^^^^^^
+
+- **msm-id** ``<u32>``: Each sub-node under the ``soc`` node must contain an
+ ``msm-id`` property. Bits 0-15 of the 32-bit value represent the chip
+ identifier; the remaining bits are reserved.
+
+ Each sub-node under the ``soc-sku`` node should contain an ``msm-id``
+ property. Bits 20-21 represent the package-id, bits 16-19 represent the
+ foundry-id; the remaining bits are ignored.
+
+- **socver-id** ``<u32>``: Each sub-node under the ``socver`` node should
+ contain a ``socver-id`` property. Bits 0-3 represent the chip minor version,
+ bits 4-7 represent the chip major version; the remaining bits are reserved.
+
+- **board-id** ``<u32>``: Each sub-node under the ``board`` node must contain
+ a ``board-id`` property. Bits 0-7 represent the board type; the remaining
+ bits are reserved.
+
+- **boardrev-id** ``<u32>``: Each sub-node under the ``boardrev`` node must
+ contain a ``boardrev-id`` property. Bits 0-3 represent the board minor
+ version, bits 4-7 represent the board major version; the remaining bits are
+ reserved.
+
+- **board-subtype** ``<u32>``: Each sub-node under the
+ ``board-subtype-peripheral-subtype``, ``board-subtype-storage-type`` and
+ ``board-subtype-memory-size`` nodes should contain a ``board-subtype``
+ property.
+
+ - Under ``board-subtype-peripheral-subtype``: bits 0-7 represent the
+ peripheral-based subtype; the remaining bits are ignored.
+ - Under ``board-subtype-storage-type``: bits 12-14 represent the storage
+ type; the remaining bits are ignored.
+ - Under ``board-subtype-memory-size``: bits 8-11 represent the memory size;
+ the remaining bits are ignored.
+
+- **oem-id** ``<u32>``: Each sub-node under the ``oem`` node must contain an
+ ``oem-id`` property. The ``oem-id`` represents the OEM and is added by the
+ OEM for selection of their board-specific DT.
+
+- **softsku-id** ``<u32>``: Each sub-node under the ``softsku`` node must
+ contain a ``softsku-id`` property. The ``softsku-id`` represents the software
+ SKU and is added for soft SKU (license) based selection of DT.
+
+The ``msm-id`` and ``socver-id`` are compared with the chip identifier value
+read from the SoC.
+
+The ``board-id``, ``boardrev-id``, ``board-subtype-peripheral-subtype`` and
+``oem-id`` are compared with the hardware description values (Configuration
+Data Table - CDT) flashed on the board's persistent memory.
+
+The ``board-subtype-storage-type`` is compared with the board's boot device
+type detected by U-Boot.
+
+The ``board-subtype-memory-size`` is compared with the board's DDR size
+detected by U-Boot.
+
+Refer: https://github.com/qualcomm-linux/qcom-dtb-metadata/blob/main/qcom-metadata.dts
+
+Guidelines for socver and boardrev
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- For any platform, the configuration entry with the shortest compatible string
+ (containing only the ``soc`` and ``board`` fields) must always reference the
+ latest hardware (SoC / board) version.
+
+- When adding support for a new hardware version that requires a separate DTB,
+ update the ``fdt`` property in the configuration with the shortest compatible
+ string so that it points to the DTB of the latest hardware version. If the
+ previously supported latest hardware version must continue to be used, add a
+ new ``socver``/``boardrev`` entry in the metadata DTS for the earlier
+ hardware. Additionally, add a new configuration entry in the FIT ITS that
+ corresponds to the platform compatible with the newly added
+ ``socver``/``boardrev``.
+
+- Consider the following example: The "soc" platform supports two chip versions
+ — socv1.0 and socv1.1 — and both versions share the same DTB (soc-v1.dtb).
+
+ FIT ITS::
+
+ config-1 {
+ compatible = "qcom,soc";
+ fdt = "fdt-soc-v1.dtb";
+ };
+
+ Now a new chip version socv2.0 is introduced, which requires a new DTB
+ (soc-v2.dtb). The older chip versions must continue to be supported.
+
+ Updated FIT ITS::
+
+ config-1 {
+ compatible = "qcom,soc";
+ fdt = "fdt-soc-v2.dtb";
+ };
+
+ config-2 {
+ compatible = "qcom,soc-socv1.0";
+ fdt = "fdt-soc-v1.dtb";
+ };
+
+ config-3 {
+ compatible = "qcom,soc-socv1.1";
+ fdt = "fdt-soc-v1.dtb";
+ };
+
+ Updated Metadata DTS::
+
+ socv1.0 {
+ socver-id = <0x10>;
+ };
+
+ socv1.1 {
+ socver-id = <0x11>;
+ };
+
+- If older hardware requires a separate DT and is not currently supported in
+ the FIT, add the required ``socver``/``boardrev`` entries in alphabetical
+ order.
+
+Image Building
+--------------
+
+FIT Image Properties
+^^^^^^^^^^^^^^^^^^^^
+
+- FIT is normally built with image data in the ``data`` property of each image
+ node. It is also possible for this data to reside outside the FIT itself
+ (external FIT). This allows the FDT part of the FIT to be quite small, so
+ that it can be loaded and scanned without loading a large amount of data.
+ Then when an image is needed it can be loaded from an external source.
+
+- External FITs use ``data-offset`` or ``data-position`` instead of ``data``.
+ The ``mkimage`` tool can convert a FIT to use external data using the ``-E``
+ argument.
+
+- The ``mkimage`` tool provides a ``-B`` argument to align each image to a
+ specific block size. Use ``-B 8`` to enforce 8-byte alignment.
+
+- The output FIT image must be named ``qclinux_fit.img`` so that U-Boot can
+ locate it in the FAT partition.
+
+Step-by-Step Workflow
+^^^^^^^^^^^^^^^^^^^^^
+
+1. **Install required tools**::
+
+ sudo apt-get install device-tree-compiler u-boot-tools mtools
+
+2. **Clone the qcom-dtb-metadata project**::
+
+ git clone https://github.com/qualcomm-linux/qcom-dtb-metadata.git
+ mkdir fit_image
+ cp -rap qcom-dtb-metadata/qcom-fitimage.its \
+ qcom-dtb-metadata/qcom-next-fitimage.its \
+ qcom-dtb-metadata/qcom-metadata.dts \
+ fit_image/
+
+3. **Copy compiled DTB/DTBO files from the kernel tree**
+
+ For steps on cloning and building the Qualcomm Linux Kernel Tree, refer to
+ https://github.com/qualcomm-linux/kmake-image/blob/main/README.md ::
+
+ mkdir -p fit_image/arch/arm64/boot/dts/qcom/
+ # Copy the compiled dtb/dtbo files from the kernel's kobj directory
+ cp -rap <u-boot build dir>/dts/upstream/src/arm64/qcom/*.dtb* \
+ fit_image/arch/arm64/boot/dts/qcom/
+
+4. **Compile the metadata DTS**::
+
+ cd fit_image
+ dtc -I dts -O dtb -o qcom-metadata.dtb qcom-metadata.dts
+
+5. **Generate the FIT image**
+
+ Use ``-E`` to place binary data outside the FIT structure and ``-B 8`` for
+ 8-byte alignment::
+
+ mkdir out
+
+ # For kernel main branch
+ mkimage -f qcom-fitimage.its out/qclinux_fit.img -E -B 8
+
+ # For kernel qcom-next branch
+ mkimage -f qcom-next-fitimage.its out/qclinux_fit.img -E -B 8
+
+ The ``-E`` flag places binary data outside the FIT structure. However,
+ since ``/incbin/`` is used in the ``.its`` file, all binaries are appended
+ into the same image. The FIT structure contains the offset and size for each
+ appended binary.
+
+6. **Pack the FIT image into a FAT partition image using mkimage**
+
+ The ``mkimage`` tool supports creating FAT filesystem images directly via
+ the ``fatfs`` image type.
+
+ mkimage -T fatfs -d out/ fitimage.bin \
+ --fat-extra-space 512 \
+ --fat-volume-id "MYBOOT" \
+ --fat-mkfs-opts "-S 512 -a"
+
+ Available parameters:
+
+ - ``--fat-extra-space <KB>`` — extra padding in KB (default: 512 KB)
+ - ``--fat-type <12|16|32|0>`` — force FAT type (0 = auto-detect)
+ - ``--fat-volume-id <label>`` — volume label (default: ``BOOT``)
+ - ``--fat-mkfs-opts <opts>`` — extra ``mkfs.vfat`` options (default: ``-S 512``)
+
+ .. note::
+
+ This requires ``mkfs.vfat`` (from ``dosfstools``) and ``mcopy``
+ (from ``mtools``) to be installed on the build host.
+
+ The resulting ``fitimage.bin`` is a FAT partition image containing
+ ``qclinux_fit.img`` and is ready to be flashed to the ``dtb_a``
+ partition.
+
+7. **Flash the image**::
+
+ fastboot flash dtb_a fitimage.bin
+
+Boot Flow
+---------
+
+U-Boot reads ``qclinux_fit.img`` from the FAT partition image flashed to the
+``dtb_a`` partition. It uses the metadata binary and compatible strings in the
+FIT to select the correct DTB for the running hardware. The FIT image contains
+a configuration table FDT, metadata FDT, and DTB/DTBO binaries. The
+configuration table FDT contains the offset and size of each DTB/DTBO within
+the same buffer. U-Boot parses the metadata, matches the compatible strings
+against the hardware identifiers read from the SoC and CDT, and passes the
+selected DTB to the OS at boot time.
+
+Inspecting the Generated Image
+-------------------------------
+
+To verify the contents of the generated FIT image::
+
+ # Extract individual DTBs from the image
+ git clone https://github.com/PabloCastellano/extract-dtb.git
+ # Creates a "dtb/" folder containing each of the dtb/dtbo files
+ ./extract-dtb/extract_dtb/extract_dtb.py fitimage.bin
+
+ # Verify the ITS/FIT structure (configuration table FDT)
+ fdtdump dtb/01_dtbdump_*.dtb
+
+ # Verify the metadata DTB contents
+ fdtdump dtb/02_dtbdump_Image_with_compressed_metadata_blob.dtb
diff --git a/doc/mkimage.1 b/doc/mkimage.1
index 9a2d07cee75..ed6bd9f32d9 100644
--- a/doc/mkimage.1
+++ b/doc/mkimage.1
@@ -54,6 +54,14 @@ The new
(Flattened Image Tree) format allows for more flexibility in handling images of
various types and also enhances integrity protection of images with stronger
checksums. It also supports verified boot.
+.P
+The
+.I fatfs
+image type creates a FAT filesystem image from a directory of files. The
+directory is specified with
+.BR \-d .
+The resulting image is a raw FAT partition image suitable for flashing directly
+to a storage device partition.
.
.SH OPTIONS
.
@@ -227,6 +235,11 @@ then multiple images may be specified, separated by colons:
.IP
.IR image-data-file [\fB:\fP image-data-file .\|.\|.]
.RE
+.IP
+For the
+.B fatfs
+image type, this argument specifies the input directory whose contents will be
+copied into the FAT filesystem image.
.
.TP
.B \-x
@@ -496,6 +509,59 @@ using
But if the original input to mkimage is a binary file (already compiled), then
the timestamp is assumed to have been set previously.
.
+.SS Options for creating FAT filesystem images
+.
+These options are only used when
+.B \-T fatfs
+is specified. The input directory is provided via
+.BR \-d .
+The host tools
+.B mkfs.vfat
+(from
+.IR dosfstools )
+and
+.B mcopy
+(from
+.IR mtools )
+must be installed on the build host.
+.
+.TP
+.BI \-\-fat\-extra\-space " size-kb"
+Add
+.I size-kb
+kilobytes of extra padding space to the FAT image beyond the size of the input
+data. This reserves room for future additions. The default is
+.BR 512 .
+.
+.TP
+.BI \-\-fat\-type " type"
+Force the FAT filesystem type to
+.IR type ,
+which must be one of
+.BR 12 ,
+.BR 16 ,
+.BR 32 ,
+or
+.B 0
+(auto-detect based on image size). The default is
+.B 0
+(auto-detect). FAT32 is automatically selected for images larger than 512 MB.
+.
+.TP
+.BI \-\-fat\-volume\-id " label"
+Set the FAT volume label to
+.IR label .
+The default is
+.BR BOOT .
+.
+.TP
+.BI \-\-fat\-mkfs\-opts " options"
+Pass additional options to
+.BR mkfs.vfat (8)
+when formatting the FAT image. The default is
+.BR "\-S 512"
+(512-byte sector size).
+.
.SH CONFIGURATION
This section documents the formats of the primary and secondary configuration
options for each image type which supports them.
@@ -544,6 +610,21 @@ and valid
are decimal numbers. See section 11.4.4.1 of the SAMA5D3 Series Data Sheet for
valid values for each parameter.
.
+.SS fatfs
+The
+.B fatfs
+image type creates a FAT filesystem image from a directory of files. The
+.B \-d
+option specifies the input directory; all files and subdirectories within it
+are copied into the FAT image using
+.BR mcopy .
+The image size is calculated automatically based on the total size of the input
+data plus the extra padding specified by
+.BR \-\-fat\-extra\-space .
+The FAT filesystem is formatted using
+.BR mkfs.vfat .
+No primary or secondary configuration is used.
+.
.SS imximage
The primary configuration is a file containing configuration commands, as
documented in doc/\:imx/\:mkimage/\:imximage.txt of the U-Boot source.
@@ -903,10 +984,32 @@ of data storage.
\fBmkimage -F external_data-offset.itb
.EE
.RE
+.P
+Create a FAT filesystem image from a directory, with default settings:
+.RS
+.P
+.EX
+\fBmkimage \-T fatfs \-d out/ fitimage.bin
+.EE
+.RE
+.P
+Create a FAT filesystem image with custom volume label, extra space, and
+mkfs.vfat options:
+.RS
+.P
+.EX
+\fBmkimage \-T fatfs \-d out/ fitimage.bin \\
+ \-\-fat\-extra\-space 512 \\
+ \-\-fat\-volume\-id "MYBOOT" \\
+ \-\-fat\-mkfs\-opts "\-S 512 \-a"
+.EE
+.RE
.
.SH SEE ALSO
.BR dtc (1),
.BR dumpimage (1),
+.BR mkfs.vfat (8),
+.BR mcopy (1),
.BR openssl (1),
the\~
.UR https://\:u-boot\:.readthedocs\:.io/\:en/\:latest/\:index.html
--
2.34.1
More information about the U-Boot
mailing list