[PATCH v6 4/6] doc: board/qualcomm: update docs for new u-boot.mbn target
Casey Connolly
casey.connolly at linaro.org
Tue May 5 17:48:44 CEST 2026
Update the build docs to describe building the u-boot.mbn target
explicitly for some boards. Additionally add a new "signing" page to
describe the purpose of mkmbn and the MBN format.
Signed-off-by: Casey Connolly <casey.connolly at linaro.org>
---
doc/board/qualcomm/dragonwing.rst | 14 ++++----------
doc/board/qualcomm/index.rst | 1 +
doc/board/qualcomm/rb3gen2.rst | 30 ++++++++++++++----------------
doc/board/qualcomm/rdp.rst | 5 +++--
doc/board/qualcomm/signing.rst | 29 +++++++++++++++++++++++++++++
5 files changed, 51 insertions(+), 28 deletions(-)
diff --git a/doc/board/qualcomm/dragonwing.rst b/doc/board/qualcomm/dragonwing.rst
index d48994153095..028ec340d155 100644
--- a/doc/board/qualcomm/dragonwing.rst
+++ b/doc/board/qualcomm/dragonwing.rst
@@ -19,20 +19,15 @@ Installation
First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``QCS615``, ``QCS8300`` or ``QCS9100``::
$ export CROSS_COMPILE=<aarch64 toolchain prefix>
$ make qcom_qcs8300_defconfig
- $ make -j8 u-boot.mbn
+ $ make -j8
Although the board does not have secure boot set up by default,
-the firmware still expects firmware ELF images to be "signed". The signature
-does not provide any security in this case, but it provides the firmware with
-some required metadata.
+the firmware still expects firmware ELF images to be "signed" in the MBN format.
+This is handled automatically with mkmbn (see :doc:`signing` for more details).
-To "sign" ``u-boot.elf`` you can use e.g. `qtestsign`_::
-
- $ qtestsign -v6 aboot -o u-boot.mbn u-boot.elf
-
-Then flash the resulting ``u-boot.mbn`` to the ``uefi_a`` partition
+Just flash the resulting ``u-boot.mbn`` to the ``uefi_a`` partition
on your device with ``fastboot flash uefi_a u-boot.mbn``.
U-Boot should be running after a reboot (``fastboot reboot``).
@@ -43,7 +38,6 @@ A tool like bkerler's `edl`_ can be used for flashing with the firehose loader (
the firehose loader can be obtained from `dragonwing IQ9 bootbinaries`.) ::
$ edl.py --loader /path/to/prog_firehose_ddr.elf w uefi_a u-boot.mbn
-.. _qtestsign: https://github.com/msm8916-mainline/qtestsign
.. _edl: https://github.com/bkerler/edl
.. _dragonwing IQ9 bootbinaries: https://artifacts.codelinaro.org/ui/native/qli-ci/flashable-binaries/qimpsdk/qcs9075-rb8-core-kit
diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst
index 3238a68e859b..b7637b3c0439 100644
--- a/doc/board/qualcomm/index.rst
+++ b/doc/board/qualcomm/index.rst
@@ -13,4 +13,5 @@ Qualcomm
rb3gen2
iq8
phones
rdp
+ signing
diff --git a/doc/board/qualcomm/rb3gen2.rst b/doc/board/qualcomm/rb3gen2.rst
index 518d01c4c3a3..329baa8d1f3a 100644
--- a/doc/board/qualcomm/rb3gen2.rst
+++ b/doc/board/qualcomm/rb3gen2.rst
@@ -17,34 +17,32 @@ Installation
First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``qcm6490``::
$ export CROSS_COMPILE=<aarch64 toolchain prefix>
$ make qcm6490_defconfig
- $ make -j8
+ $ make -j8 DEVICE_TREE=qcom/qcs6490-rb3gen2
-This will build ``u-boot.elf`` in the configured output directory.
+This will build ``u-boot.mbn`` in the configured output directory.
-Although the RB3 Gen 2 does not have secure boot set up by default,
-the firmware still expects firmware ELF images to be "signed". The signature
-does not provide any security in this case, but it provides the firmware with
-some required metadata.
-
-To "sign" ``u-boot.elf`` you can use e.g. `qtestsign`_::
-
- $ qtestsign -v6 aboot -o u-boot.mbn u-boot.elf
+Although the board does not have secure boot set up by default,
+the firmware still expects firmware ELF images to be "signed" in the MBN format.
+This is handled automatically with mkmbn (see :doc:`signing` for more details).
Then install the resulting ``u-boot.mbn`` to the ``uefi_a`` partition
on your device with ``fastboot flash uefi_a u-boot.mbn``.
U-Boot should be running after a reboot (``fastboot reboot``).
-Note that fastboot is not yet supported in U-Boot on this board, as a result,
-to flash back the original firmware, or new versoins of the U-Boot, EDL mode
-must be used. This can be accessed by pressing the EDL mode button as described
-in the Qualcomm Linux documentation. A tool like bkerler's `edl`_ can be used
-for flashing with the firehose loader binary appropriate for the board.
+Note that fastboot is not yet supported in U-Boot on this board, as a result, to flash
+back the original firmware, or new versoins of the U-Boot, EDL mode must be used. This
+can be accessed by holding the EDL button while powering on as described in the
+Qualcomm Linux documentation.
+
+A tool like bkerler's `edl`_ can be used for flashing with the firehose loader from the `RB3 Gen 2 bootbinaries`. ::
+
+ $ edl.py --loader /path/to/prog_firehose_ddr.elf w uefi_a u-boot.mbn
-.. _qtestsign: https://github.com/msm8916-mainline/qtestsign
.. _edl: https://github.com/bkerler/edl
+.. _RB3 Gen 2 bootbinaries: https://artifacts.codelinaro.org/artifactory/qli-ci/software/chip/qualcomm_linux-spf-1-0/qualcomm-linux-spf-1-0_test_device_public/r1.0_00039.2/QCM6490.LE.1.0/common/build/ufs/bin/QCM6490_bootbinaries.zip
Usage
-----
diff --git a/doc/board/qualcomm/rdp.rst b/doc/board/qualcomm/rdp.rst
index 99cf8eba57ce..4e63fe624b8a 100644
--- a/doc/board/qualcomm/rdp.rst
+++ b/doc/board/qualcomm/rdp.rst
@@ -16,11 +16,12 @@ Installation
First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``IPQ9574``::
$ export CROSS_COMPILE=<aarch64 toolchain prefix>
$ make qcom_ipq9574_mmc_defconfig
- $ make -j8
+ $ make -j8 u-boot.mbn
-This will build ``u-boot.elf`` in the configured output directory.
+This will build the signed ``u-boot.mbn`` in the configured output directory. More information
+about image signing can be found in :doc:`signing`.
The firmware expects the ELF images to be in MBN format. The `elftombn.py` tool
can be used to convert the ELF images to MBN format.
diff --git a/doc/board/qualcomm/signing.rst b/doc/board/qualcomm/signing.rst
new file mode 100644
index 000000000000..317cd57cefee
--- /dev/null
+++ b/doc/board/qualcomm/signing.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Casey Connolly <casey.connolly at linaro.org>
+
+Qualcomm Image Signing
+======================
+
+On some boards like the RB3 Gen 2 where U-Boot runs as the first stage bootloader,
+it must be in a Qualcomm specific signed ELF format called ``mbn``.
+
+For most boards this is handled automatically with the ``mkmbn`` tool in the U-Boot
+build system. If you're bringing up a new platform which will run U-Boot as the first
+stage bootloader, you may need to add your board and platform compatible string and
+the load address used by your board to the ``boards`` table in ``tools/qcom/mkmbn/mkmbn.py``.
+
+For example:
+
+.. code-block:: python
+
+ boards: dict[bytes, int] = {
+ # Exact matches for boards, these are preferred
+ # Don't forget the null terminator!
+ b"qcom,qcs6490-rb3gen2\0": MbnData(0x9FC00000, 6, SwId.aboot),
+ ...
+ }
+
+
+When you run make to build the ``u-boot.mbn`` target, ``mkmbn`` will inspect the DTB in your
+U-Boot image and try to match the compatible to the table, then it will build an ELF image and
+hash/sign it per the MBN spec.
--
2.53.0
More information about the U-Boot
mailing list