Document how to build and sign U-Boot for snagboot mode on Qualcomm platforms, using Lemans-EVK as the example, and how to add a snagboot defconfig for another board using the qcom-snagboot.config fragment.
Signed-off-by: Balaji Selvanathan <[email protected]> --- Changes in v8: - Point to the upstream Snagboot docs instead of describing the tool - Drop the "Why Snagboot?", architecture and EDL+Firehose comparison sections - Move the build and signing steps ahead of board enablement - Drop the list of Kconfig options selected/forbidden by QCOM_SNAGBOOT_MODE and the Lemans-EVK example section - Replace the signing prerequisites list with commands to fetch swiv_build_utility.py and qtestsign - Drop the "Expected result" and "Output" blocks Changes in v7: - Rebased on top of latest file Changes in v5: - Added build steps for U-Boot in Snagboot mode Changes in v4: - Newly added in v4 --- doc/board/qualcomm/index.rst | 1 + doc/board/qualcomm/snagboot.rst | 80 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+) diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index 56b8d894c2a..b8bc37bb384 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -17,3 +17,4 @@ Qualcomm rdp signing spl + snagboot diff --git a/doc/board/qualcomm/snagboot.rst b/doc/board/qualcomm/snagboot.rst new file mode 100644 index 00000000000..716d88b2ba2 --- /dev/null +++ b/doc/board/qualcomm/snagboot.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Snagboot Mode for Qualcomm Platforms +===================================== + +`Snagboot`_ is a recovery and reflashing tool that can download a +bootloader to a device in its boot ROM recovery mode and then flash +images to it. On Qualcomm SoCs, snagrecover uses the Sahara protocol in +EDL mode to load XBL, which initializes DDR, and then loads U-Boot into +DDR. U-Boot enters fastboot mode and snagflash uses fastboot to flash +the system images. See the `Snagboot documentation`_ for how to use +the host tools. + +U-Boot built in snagboot mode runs directly from the address XBL loads +it to. It must cope with the MMU left enabled by XBL, and it cannot +rely on PSCI firmware or Command DB being set up. + +Currently supported platforms: + +* Lemans-EVK (``qcom_lemans_snagboot_defconfig``) + +.. _Snagboot: https://github.com/bootlin/snagboot +.. _Snagboot documentation: https://github.com/bootlin/snagboot/tree/main/docs + +Building +-------- + +First, setup ``CROSS_COMPILE`` for aarch64. Then, configure and build U-Boot for +the Lemans EVK platform:: + + $ export CROSS_COMPILE=<aarch64 toolchain prefix> + $ make O=.output qcom_lemans_snagboot_defconfig + $ make -j8 O=.output + +Additional tooling +^^^^^^^^^^^^^^^^^^ + +In order to generate a working image, ``swiv_build_utility.py`` and +``qtestsign`` are needed:: + + $ git clone https://github.com/qualcomm-linux/boot-firmware-ci + $ export SWIV_BUILD="$PWD/boot-firmware-ci/tools/swiv_build_utility.py" + $ git clone https://github.com/msm8916-mainline/qtestsign + $ export QTESTSIGN="$PWD/qtestsign/qtestsign.py" + +``qtestsign`` requires Python 3.7+ and the ``cryptography`` module, which +can be installed with ``pip install ./qtestsign``. + +Signing +^^^^^^^ + +Add the SWIV segment required for TZ-based signing:: + + $ python3 "$SWIV_BUILD" .output/u-boot-swiv.elf .output/u-boot.elf lemans + +Then sign the resulting ELF with test keys:: + + $ python3 "$QTESTSIGN" -v 6 -o .output/u-boot.mbn tz .output/u-boot-swiv.elf + +This generates the final ``.output/u-boot.mbn`` binary, that can then be +used with snagboot. + +Board Enablement +---------------- + +Common snagboot settings live in the ``configs/qcom-snagboot.config`` +fragment. A platform-specific snagboot defconfig includes it on top of +``qcom_defconfig`` and sets the platform values:: + + #include "qcom_defconfig" + #include "qcom-snagboot.config" + + # Address where XBL loads U-Boot + CONFIG_TEXT_BASE=0x1c100000 + CONFIG_REMAKE_ELF=y + CONFIG_FASTBOOT_BUF_ADDR=0xdb300000 + CONFIG_DEFAULT_DEVICE_TREE="qcom/<your-board>" + + # Timer frequency for your platform + CONFIG_COUNTER_FREQUENCY=19200000 -- 2.34.1
