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.conno...@linaro.org>
---
doc/board/qualcomm/index.rst | 1 +
doc/board/qualcomm/rb3gen2.rst | 27 +++++++++++++--------------
doc/board/qualcomm/rdp.rst | 5 +++--
doc/board/qualcomm/signing.rst | 29 +++++++++++++++++++++++++++++
4 files changed, 46 insertions(+), 16 deletions(-)
diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst
index
e2fcbfa19c2fff36c8551823ca4a53a5fdc7fa9a..0b24fb6691907ab6fcecc6ade55f363de44502a8
100644
--- a/doc/board/qualcomm/index.rst
+++ b/doc/board/qualcomm/index.rst
@@ -11,4 +11,5 @@ Qualcomm
board
phones
debugging
rdp
+ signing
diff --git a/doc/board/qualcomm/rb3gen2.rst b/doc/board/qualcomm/rb3gen2.rst
index
4240606224f5b36968277792dfd5dc93a762fdfa..79a57c689657719b61582fc33cd079f134cda054
100644
--- a/doc/board/qualcomm/rb3gen2.rst
+++ b/doc/board/qualcomm/rb3gen2.rst
@@ -17,34 +17,33 @@ 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 u-boot.mbn
-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
+the firmware still expects firmware ELF images to be "signed". More
information can be
+found in :doc:`signing`.
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
99cf8eba57ce9fc8860ba112df274515f941b46d..4e63fe624b8a6156c0b12021b321db518d88c321
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
0000000000000000000000000000000000000000..317cd57cefeeb3b073ebec79286f00414d1da342
--- /dev/null
+++ b/doc/board/qualcomm/signing.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Casey Connolly <casey.conno...@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.49.0
