[PATCH 7/7] doc: add fvupdate_to_fit.py documentation and example XML
Balaji Selvanathan
balaji.selvanathan at oss.qualcomm.com
Fri May 22 08:09:35 CEST 2026
Add comprehensive documentation for the fvupdate_to_fit.py tool that
converts Qualcomm FvUpdate.xml files to FIT capsule images. The
documentation covers usage, command-line options, deployment workflow,
and troubleshooting guidance.
Include an example FvUpdate.xml file demonstrating the expected XML
structure with UPDATE operations for multiple firmware partitions.
The documentation provides complete end-to-end guidance from XML
conversion through capsule deployment in U-Boot, including board-
specific GUIDs for QCS615, QCS6490, and Lemans platforms.
Signed-off-by: Balaji Selvanathan <balaji.selvanathan at oss.qualcomm.com>
---
doc/develop/fvupdate_to_fit.rst | 487 +++++++++++++++++++++++
doc/develop/fvupdate_to_fit/example_FvUpdate.xml | 43 ++
2 files changed, 530 insertions(+)
diff --git a/doc/develop/fvupdate_to_fit.rst b/doc/develop/fvupdate_to_fit.rst
new file mode 100644
index 00000000000..ef29587198f
--- /dev/null
+++ b/doc/develop/fvupdate_to_fit.rst
@@ -0,0 +1,487 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+
+FvUpdate.xml to Capsule Converter
+==================================
+
+This Python script provides complete end-to-end conversion from Qualcomm FvUpdate.xml files to ready-to-deploy EFI capsule files for U-Boot capsule updates.
+
+Overview
+--------
+
+The script offers two modes of operation:
+
+1. **FIT-only mode**: Converts FvUpdate.xml to FIT images
+2. **Complete mode**: Full workflow from XML to final capsule file
+
+The complete workflow includes:
+
+- FvUpdate.xml parsing and validation
+- FIT image generation
+- Final capsule creation with provided GUID
+- Auto-installation of missing tools
+
+Features
+--------
+
+Core Functionality
+~~~~~~~~~~~~~~~~~~
+
+- **XML Parsing**: Extracts UPDATE operations from FvUpdate.xml
+- **Binary Validation**: Ensures all referenced binary files exist
+- **ITS Generation**: Creates Image Tree Source files with proper node naming
+- **FIT Compilation**: Uses mkimage to generate FIT images
+- **Capsule Creation**: Creates final capsule files using mkeficapsule with provided GUID
+- **Tool Management**: Auto-installs missing tools (mkimage, mkeficapsule)
+
+Compatibility
+~~~~~~~~~~~~~
+
+- Qualcomm U-Boot capsule update system
+- Multi-partition firmware updates
+- FIT-based capsule payloads
+- EFI Firmware Management Protocol (FMP)
+- DFU backend integration
+
+Usage
+-----
+
+FIT Image Only
+~~~~~~~~~~~~~~
+
+Creates only system.fit::
+
+ ./fvupdate_to_fit.py FvUpdate.xml
+
+Complete Capsule Workflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates system.fit and firmware.capsule::
+
+ ./fvupdate_to_fit.py FvUpdate.xml \
+ --mkeficapsule <path_to_mkeficapsule_tool> \
+ --guid <guid_of_the_board> \
+ --fw-version <version_of_the_capsule_payload_in_0.0.A.B_format>
+
+Additional Examples
+~~~~~~~~~~~~~~~~~~~
+
+With custom output names::
+
+ ./fvupdate_to_fit.py FvUpdate.xml \
+ --mkeficapsule /path/to/mkeficapsule \
+ --guid 12345678-1234-5678-9abc-123456789abc \
+ --fw-version 0.0.1.0 \
+ --output custom.fit \
+ --capsule-output custom.capsule
+
+With verbose output::
+
+ ./fvupdate_to_fit.py FvUpdate.xml \
+ --mkeficapsule /path/to/mkeficapsule \
+ --guid 12345678-1234-5678-9abc-123456789abc \
+ --fw-version 0.0.1.0 \
+ --verbose
+
+With Capsule Signing
+~~~~~~~~~~~~~~~~~~~~
+
+Creates a signed capsule::
+
+ ./fvupdate_to_fit.py FvUpdate.xml \
+ --mkeficapsule /path/to/mkeficapsule \
+ --guid 12345678-1234-5678-9abc-123456789abc \
+ --fw-version 0.0.1.0 \
+ --monotonic-count 1 \
+ --private-key keys/CRT.key \
+ --certificate keys/CRT.crt
+
+Command Line Options
+--------------------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 20 50 30
+
+ * - Option
+ - Description
+ - Default
+ * - ``xml_file``
+ - Path to FvUpdate.xml file
+ - Required
+ * - ``--guid``
+ - GUID value of the board (enables complete mode). Board-specific GUIDs: qcs615: ``9FD379D2-670E-4BB3-86A1-40497E6E17B0``, qcs6490-rb3gen2: ``6f25bfd2-a165-468b-980f-ac51a0a45c52``, lemans-evk: ``78462415-6133-431c-9fae-48f2bafd5c71``
+ - Required
+ * - ``--mkeficapsule``
+ - Path to mkeficapsule binary
+ - Required
+ * - ``--fw-version``
+ - Firmware version in "0.0.A.B" format (e.g., "0.0.1.0")
+ - Optional
+ * - ``--monotonic-count``
+ - Monotonic count for capsule signing
+ - Optional
+ * - ``--private-key``
+ - Path to the private key for signing
+ - Optional
+ * - ``--certificate``
+ - Path to the certificate for signing
+ - Optional
+ * - ``-o, --output``
+ - Output FIT image name
+ - system.fit
+ * - ``-c, --capsule-output``
+ - Output capsule file name
+ - firmware.capsule
+ * - ``-v, --verbose``
+ - Enable verbose output
+ - Disabled
+ * - ``-h, --help``
+ - Show help message
+ - \-
+
+Requirements
+------------
+
+System Requirements
+~~~~~~~~~~~~~~~~~~~
+
+- Python 3.6+
+- Linux system with package manager (apt, yum, dnf, or pacman)
+- sudo access for tool installation
+
+Required Tools (Auto-installed)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- U-Boot tools (mkimage, mkeficapsule)
+
+Required Files
+~~~~~~~~~~~~~~
+
+- FvUpdate.xml file
+- Binary files in Images/ directory
+- GUID value for the target board (for complete mode)
+
+Installation
+------------
+
+1. Make the script executable::
+
+ chmod +x fvupdate_to_fit.py
+
+2. The script will auto-install missing tools on first run
+
+File Structure
+--------------
+
+The script expects the following directory structure::
+
+ project/
+ ├── FvUpdate.xml
+ ├── Images/
+ │ ├── xbl.elf
+ │ ├── uefi.bin
+ │ └── boot.img
+ └── fvupdate_to_fit.py
+
+Example FvUpdate.xml
+~~~~~~~~~~~~~~~~~~~~
+
+An example FvUpdate.xml file is provided for reference:
+
+.. literalinclude:: fvupdate_to_fit/example_FvUpdate.xml
+ :language: xml
+
+This example demonstrates the XML structure with UPDATE operations for
+multiple firmware partitions.
+
+XML Structure Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tool only processes the following XML elements:
+
+**Required Elements:**
+
+- ``<FwEntry>`` - Container for each firmware entry
+- ``<InputBinary>`` - Binary filename (must exist in Images/ directory)
+- ``<Operation>`` - Must be "UPDATE" to be processed
+- ``<Dest>/<PartitionName>`` - Target partition name (case-sensitive)
+
+**XML Structure:**
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="utf-8"?>
+ <FVItems>
+ <FwEntry>
+ <InputBinary>firmware.bin</InputBinary>
+ <Operation>UPDATE</Operation>
+ <Dest>
+ <PartitionName>partition_name</PartitionName>
+ </Dest>
+ </FwEntry>
+ </FVItems>
+
+**Notes:**
+
+- The tool hardcodes the Images/ directory for binary files
+- Only entries with ``<Operation>UPDATE</Operation>`` are processed
+- Partition names are case-sensitive and must match U-Boot partition discovery
+
+Output Files
+------------
+
+Complete Mode
+~~~~~~~~~~~~~
+
+- ``system.its`` - Image Tree Source file (kept)
+- ``system.fit`` - FIT image (kept)
+- ``firmware.capsule`` - Final capsule file (ready for deployment)
+
+FIT-only Mode
+~~~~~~~~~~~~~
+
+- ``system.its`` - Image Tree Source file
+- ``system.fit`` - FIT image
+
+Deployment Workflow
+-------------------
+
+After generating the capsule:
+
+1. **Copy capsule to boot partition**::
+
+ cp firmware.capsule /boot/
+
+2. **Deploy in U-Boot**::
+
+ => fatload mmc 0:1 $loadaddr firmware.capsule
+ => efidebug capsule update $loadaddr
+
+Technical Details
+-----------------
+
+FIT Image Structure
+~~~~~~~~~~~~~~~~~~~
+
+- **Node Names**: Match partition names (e.g., ``xbl_a``, ``uefi_a``)
+- **Image Type**: All images marked as "firmware"
+- **Hash Algorithm**: SHA256 for integrity verification
+- **Configuration**: Single config referencing all firmware images
+
+Capsule Structure
+~~~~~~~~~~~~~~~~~
+
+- **GUID**: Provided via --guid option
+- **Index**: Always 1 (required for FIT capsules)
+- **Payload**: FIT image containing all firmware
+- **Version**: Optional firmware version (in 0.0.A.B format) via --fw-version, encoded as (A << 16 | B)
+- **Signing**: Optional signing with monotonic count, private key, and certificate
+
+FMP Driver Compatibility
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The provided GUID must match what the FMP (Firmware Management Protocol) driver expects:
+
+- Uses actual partition names from FvUpdate.xml
+- Compatible with Qualcomm capsule update flow
+- Works with ``fit_update()`` processing
+
+Error Handling
+--------------
+
+Comprehensive error handling with fail-fast approach:
+
+- Missing XML files or invalid format
+- Missing binary files in Images/ directory
+- Tool installation failures
+- Capsule creation failures
+- Invalid GUID format
+
+Example Output
+--------------
+
+Complete Mode
+~~~~~~~~~~~~~
+
+::
+
+ Converting FvUpdate.xml to capsule...
+ ============================================================
+ Installing missing tools...
+ Installed u-boot-tools ✓
+ Parsing XML file: FvUpdate.xml
+ Found 3 FwEntry elements
+ Added: xbl_a -> xbl.elf
+ Added: uefi_a -> uefi.bin
+ Added: boot_a -> boot.img
+ Successfully parsed 3 UPDATE entries
+ Validating binary files...
+ xbl.elf: 524288 bytes
+ uefi.bin: 1048576 bytes
+ boot.img: 2097152 bytes
+ All binary files validated successfully
+ Generating ITS file: system.its
+ ITS file generated successfully
+ Compiling FIT image: system.fit
+ Running: mkimage -f system.its system.fit
+ FIT image compiled successfully: 3670016 bytes
+ Using GUID: 12345678-1234-5678-9abc-123456789abc
+ Creating capsule: firmware.capsule
+ Encoded Firmware version: 65536 (from 0.0.1.0)
+ Command: mkeficapsule -g 12345678-1234-5678-9abc-123456789abc -i 1 -v 65536 system.fit firmware.capsule
+ Capsule created successfully: 3670144 bytes ✓
+ ============================================================
+ SUCCESS: Complete capsule workflow completed!
+
+ Files created:
+ ITS file: system.its
+ FIT file: system.fit
+ Capsule file: firmware.capsule (3.5 MB)
+
+ Capsule GUID: 12345678-1234-5678-9abc-123456789abc
+
+ Ready for deployment:
+ 1. Copy firmware.capsule to boot partition
+ 2. In U-Boot: fatload mmc 0:1 $loadaddr firmware.capsule
+ 3. In U-Boot: efidebug capsule update $loadaddr
+
+FIT-only Mode
+~~~~~~~~~~~~~
+
+::
+
+ Converting FvUpdate.xml to FIT image...
+ ============================================================
+ Parsing XML file: FvUpdate.xml
+ Found 3 FwEntry elements
+ Added: xbl_a -> xbl.elf
+ Added: uefi_a -> uefi.bin
+ Added: boot_a -> boot.img
+ Successfully parsed 3 UPDATE entries
+ Validating binary files...
+ xbl.elf: 524288 bytes
+ uefi.bin: 1048576 bytes
+ boot.img: 2097152 bytes
+ All binary files validated successfully
+ Generating ITS file: system.its
+ ITS file generated successfully
+ Compiling FIT image: system.fit
+ FIT image compiled successfully: 3670016 bytes
+ ============================================================
+ CONVERSION SUMMARY:
+ Input XML: FvUpdate.xml
+ Generated ITS: system.its
+ Output FIT: system.fit
+ Partitions: 3
+ - xbl_a (xbl.elf)
+ - uefi_a (uefi.bin)
+ - boot_a (boot.img)
+
+ ============================================================
+ SUCCESS: FIT image created successfully!
+ Output: system.fit
+
+ To create capsule, run again with:
+ ./fvupdate_to_fit.py FvUpdate.xml --mkeficapsule <path_to_tool> --guid <board_guid> --fw-version <version>
+
+Viewing Generated File Contents
+--------------------------------
+
+FIT Image Contents
+~~~~~~~~~~~~~~~~~~
+
+You can inspect the generated ``system.fit`` file using U-Boot tools::
+
+ # View FIT image structure and metadata
+ mkimage -l system.fit
+
+ # List all images in the FIT
+ dumpimage -l system.fit
+
+Capsule Contents
+~~~~~~~~~~~~~~~~
+
+You can inspect the generated ``firmware.capsule`` file using mkeficapsule::
+
+ # View capsule header and metadata
+ mkeficapsule --dump-capsule firmware.capsule
+
+ # Or using local mkeficapsule binary
+ /path/to/local/mkeficapsule --dump-capsule firmware.capsule
+
+Troubleshooting
+---------------
+
+mkimage not found
+~~~~~~~~~~~~~~~~~
+
+Install U-Boot tools::
+
+ # Ubuntu/Debian
+ sudo apt-get install u-boot-tools
+
+ # CentOS/RHEL
+ sudo yum install uboot-tools
+
+mkeficapsule not found
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you get an error about mkeficapsule not being found, use a locally compiled version::
+
+ # Use local mkeficapsule binary
+ ./fvupdate_to_fit.py FvUpdate.xml \
+ --mkeficapsule /path/to/local/u-boot/tools/mkeficapsule \
+ --guid 12345678-1234-5678-9abc-123456789abc \
+ --fw-version 0.0.1.0
+
+ # Example with U-Boot build directory
+ ./fvupdate_to_fit.py FvUpdate.xml \
+ --mkeficapsule /local/mnt/workspace/bselvana/k2c_le/u-boot_upstream/u-boot_v2025_upstream/tools/mkeficapsule \
+ --guid 12345678-1234-5678-9abc-123456789abc \
+ --fw-version 0.0.1.0
+
+Invalid GUID format
+~~~~~~~~~~~~~~~~~~~
+
+Ensure the GUID follows the format: ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
+
+Supported Boards and GUIDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following Qualcomm boards are supported with their respective GUIDs:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Board
+ - GUID
+ * - **qcs615**
+ - ``9FD379D2-670E-4BB3-86A1-40497E6E17B0``
+ * - **qcs6490-rb3gen2**
+ - ``6f25bfd2-a165-468b-980f-ac51a0a45c52``
+ * - **lemans-evk**
+ - ``78462415-6133-431c-9fae-48f2bafd5c71``
+
+
+Example valid GUID format: ``12345678-1234-5678-9abc-123456789abc``
+
+Missing binary files
+~~~~~~~~~~~~~~~~~~~~
+
+Ensure all files referenced in FvUpdate.xml exist in the Images/ directory with correct names.
+
+XML parsing errors
+~~~~~~~~~~~~~~~~~~
+
+Verify FvUpdate.xml is well-formed XML with proper FwEntry structure.
+
+mkeficapsule binary not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you specify a custom mkeficapsule path, ensure:
+
+- The file exists and is executable
+- The path is correct (absolute or relative to current directory)
+- The binary supports capsule creation
diff --git a/doc/develop/fvupdate_to_fit/example_FvUpdate.xml b/doc/develop/fvupdate_to_fit/example_FvUpdate.xml
new file mode 100644
index 00000000000..c1dea8db4a2
--- /dev/null
+++ b/doc/develop/fvupdate_to_fit/example_FvUpdate.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+/** @file FVUpdate.xml
+
+ This file configures the content of the payload for firmware update
+
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+**/
+
+#Operation Type
+ IGNORE - Skip this entry (not processed by fvupdate_to_fit.py)
+ UPDATE - Include this entry in the capsule
+
+#NOTE: PartitionName is Case sensitive
+
+-->
+<FVItems>
+
+<!--BootLoader entries-->
+
+<!--FwEntry for UBoot-->
+ <FwEntry>
+ <InputBinary>u-boot.mbn</InputBinary>
+ <Operation>UPDATE</Operation>
+ <Dest>
+ <PartitionName>uefi_a</PartitionName>
+ </Dest>
+ </FwEntry>
+
+<!--FwEntry for TZ-->
+ <FwEntry>
+ <InputBinary>tz.mbn</InputBinary>
+ <Operation>UPDATE</Operation>
+ <Dest>
+ <PartitionName>tz_a</PartitionName>
+ </Dest>
+ </FwEntry>
+
+<!--Add FwEntries based on requirement-->
+
+</FVItems>
\ No newline at end of file
--
2.34.1
More information about the U-Boot
mailing list