Re: [PATCH v2 4/4] doc: board: mediatek: document Genio 700 SPL boot

Le mer. 22 juil. 2026 à 23:36, Carlo Caione <[email protected]> a écrit :
>
> Document the normal eMMC boot chain, external firmware prerequisites,
> binman build invocation and generated images.
>
> Also describe storage mapping, handoff details, verification steps, and
> current security and recovery limitations.
>
> Signed-off-by: Carlo Caione <[email protected]>

Hi Carlo,

Thank you very much for starting this doc.
This was already requested few months ago  [1]. MediaTek, wanted to
handle this internally. Did you sync with them?

Also a lot of stuff in this documentation is quite generic, maybe it
worth refactoring a bit to share it with other Genio EVKs?

Maybe Macpaul Lin  have some feedback about this?

Cheers
Julien

[1]: https://lore.kernel.org/all/[email protected]/#t

> ---
>  board/mediatek/MAINTAINERS                  |   1 +
>  doc/board/mediatek/index.rst                |   1 +
>  doc/board/mediatek/mt8390-genio-700-evk.rst | 164 ++++++++++++++++++++++++++++
>  3 files changed, 166 insertions(+)
>
> diff --git a/board/mediatek/MAINTAINERS b/board/mediatek/MAINTAINERS
> index d99c6d708b2..e657c5b04d5 100644
> --- a/board/mediatek/MAINTAINERS
> +++ b/board/mediatek/MAINTAINERS
> @@ -27,6 +27,7 @@ F:    arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
>  F:     configs/mt8188.config
>  F:     configs/mt8370_genio_510_evk_defconfig
>  F:     configs/mt8390_genio_700_evk_defconfig
> +F:     doc/board/mediatek/mt8390-genio-700-evk.rst
>
>  MT8195/MT8395
>  M:     Macpaul Lin <[email protected]>
> diff --git a/doc/board/mediatek/index.rst b/doc/board/mediatek/index.rst
> index c55d5aeb5c4..09038e29152 100644
> --- a/doc/board/mediatek/index.rst
> +++ b/doc/board/mediatek/index.rst
> @@ -7,3 +7,4 @@ Mediatek
>     :maxdepth: 2
>
>     mt7621
> +   mt8390-genio-700-evk
> diff --git a/doc/board/mediatek/mt8390-genio-700-evk.rst b/doc/board/mediatek/mt8390-genio-700-evk.rst
> new file mode 100644
> index 00000000000..2ccfa8e6f27
> --- /dev/null
> +++ b/doc/board/mediatek/mt8390-genio-700-evk.rst
> @@ -0,0 +1,164 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (C) 2026 Baylibre SAS
> +
> +MediaTek Genio 700 EVK
> +======================
> +
> +The MediaTek Genio 700 EVK is based on the MT8390 SoC and is configured with
> +``mt8390_genio_700_evk_defconfig``.
> +
> +Boot chain
> +----------
> +
> +The normal eMMC boot chain is::
> +
> +   BootROM
> +     -> platform DDR loader
> +     -> U-Boot SPL
> +     -> Arm Trusted Firmware-A (BL31)
> +     -> OP-TEE (BL32)
> +     -> U-Boot proper (BL33)
> +
> +The BootROM loads a MediaTek image from the eMMC boot0 hardware partition.
> +This image contains a platform DDR loader followed by U-Boot SPL. The DDR
> +loader initializes DRAM, copies the fixed ``CONFIG_SPL_MAX_SIZE`` byte SPL
> +region to ``CONFIG_SPL_TEXT_BASE`` and enters SPL at EL3 with exceptions
> +masked.
> +
> +SPL reads a FIT image from partition 1 of the eMMC user area. The FIT contains
> +Arm Trusted Firmware-A (BL31), OP-TEE (BL32), U-Boot proper (BL33) and the
> +U-Boot control devicetree. SPL uses the standard FIT and Arm Trusted Firmware
> +support to hand off to BL31.
> +
> +The DDR loader is a platform firmware component built separately from U-Boot
> +and supplied to binman as an external blob.
> +
> +Build prerequisites
> +-------------------
> +
> +The following external binaries are required:
> +
> +``ddr-loader.bin``
> +   The MediaTek DDR loader for the board. Build it with
> +   ``SPL_OFFSET=0x4b000``, ``SPL_SIZE`` equal to ``CONFIG_SPL_MAX_SIZE`` and an
> +   SPL destination and entry address matching ``CONFIG_SPL_TEXT_BASE``. The
> +   input may be shorter than ``0x4b000`` bytes; binman pads it with zeroes to
> +   the offset reserved before SPL.
> +
> +``BL31``
> +   The U-Boot build variable naming the Arm Trusted Firmware-A BL31 binary
> +   built for MT8390. It is loaded and entered at ``0x54601000``.
> +
> +``TEE``
> +   The U-Boot build variable naming the OP-TEE binary. A standard OP-TEE v1
> +   ``tee.bin`` image is supported. The FIT loads it at ``0x431fffe4`` and
> +   enters it at ``0x43200000``.
> +
> +These binaries must match the board memory layout and its firmware security
> +policy. Place ``ddr-loader.bin`` in a directory which can be passed to binman
> +with ``BINMAN_INDIRS``.
> +
> +Building
> +--------
> +
> +For example, with the DDR loader in ``/path/to/firmware/ddr-loader.bin``::
> +
> +   $ export CROSS_COMPILE=aarch64-linux-gnu-
> +   $ export KBUILD_OUTPUT=build
> +   $ export BL31=/path/to/bl31.bin
> +   $ export TEE=/path/to/tee.bin
> +   $ make mt8390_genio_700_evk_defconfig
> +   $ make BINMAN_INDIRS=/path/to/firmware
> +
> +``TEE`` must be set for both configuration and compilation. U-Boot uses its
> +presence during configuration to enable the support needed to preserve the
> +OP-TEE reserved-memory nodes in the devicetree passed to the operating system.
> +Do not deploy images if binman reports that it used fake or missing external
> +blobs.
> +
> +Building standalone binaries
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The external binaries are packaging inputs rather than U-Boot compilation
> +dependencies. To build only U-Boot proper and SPL, request their targets
> +directly::
> +
> +   $ make mt8390_genio_700_evk_defconfig
> +   $ make u-boot.bin spl/u-boot-spl.bin
> +
> +This produces ``build/u-boot.bin`` and ``build/spl/u-boot-spl.bin`` without
> +building ``mtk-boot.bin`` or ``bootloaders.img``. The DDR loader and BL31 are
> +not needed in this case.
> +
> +The presence of ``TEE`` during configuration enables the U-Boot support needed
> +to preserve the OP-TEE reserved-memory nodes. Set ``TEE`` during configuration
> +if the resulting ``u-boot.bin`` will later be used in a boot chain containing
> +OP-TEE, even when the standalone target does not read the file.
> +
> +Binman produces two deployable images in the build directory:
> +
> +``mtk-boot.bin``
> +   A MediaTek eMMC image with load and entry address ``0x201000``. It contains
> +   the DDR loader, padded to ``0x4b000`` bytes, followed by U-Boot SPL padded
> +   to ``CONFIG_SPL_MAX_SIZE``. The fixed regions make every byte copied by the
> +   external loader part of the BootROM-loaded image.
> +
> +``bootloaders.img``
> +   A FIT image containing BL31, U-Boot proper, OP-TEE and the U-Boot control
> +   devicetree. Each component has a SHA-256 hash.
> +
> +Binman also creates ``mtk-boot.map`` and ``bootloaders.map``. These show the
> +offset and size of every component. The FIT can be inspected with::
> +
> +   $ dumpimage -l build/bootloaders.img
> +
> +Installing
> +----------
> +
> +Use the board provisioning tools to place the images as follows:
> +
> +===================  ================================================
> +Image                Destination
> +===================  ================================================
> +``mtk-boot.bin``     Start of the eMMC boot0 hardware partition
> +``bootloaders.img``  GPT partition 1 in the eMMC user area
> +===================  ================================================
> +
> +The standard Genio 700 partition layout names GPT partition 1
> +``bootloaders``. SPL selects the partition by number through
> +``CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION``; it does not locate it by name.
> +
> +Writing an invalid image to eMMC boot0 can make the board unbootable. Preserve
> +the platform recovery path and any backup bootloader partition while testing.
> +Selection of a backup partition is not implemented by this SPL configuration.
> +
> +Using Genio Tools
> +~~~~~~~~~~~~~~~~~
> +
> +Install `Genio Tools
> +<https://genio.mediatek.com/doc/iot-yocto/latest/tools/genio-tools.html>`_ and
> +obtain a compatible `prebuilt Genio image
> +<https://genio.mediatek.com/doc/iot-yocto/latest/sw/yocto/download.html>`_.
> +``genio-flash`` needs the extracted image directory for its partition metadata
> +and download bootstrap. To update only the primary boot chain while retaining
> +the backup bootloader partition, run::
> +
> +   $ genio-flash -P /path/to/genio-image \
> +         mmc0boot0:/absolute/path/to/build/mtk-boot.bin \
> +         bootloaders:/absolute/path/to/build/bootloaders.img
> +
> +Genio Tools uses the default bootstrap from the image directory. Keep
> +``bootloaders_b`` unchanged until the new images have been tested. Add
> +``--dry-run`` to check the selected files and partitions without accessing the
> +board.
> +
> +Limitations
> +-----------
> +
> +A successful boot prints banners from U-Boot SPL, BL31, OP-TEE and U-Boot
> +proper.
> +
> +The generated images are not signed. Production signing, rollback protection
> +and provisioning are platform integration responsibilities. The images only
> +establish the firmware boot chain; operating-system boot policy remains
> +independent and uses the normal U-Boot facilities.
>
> --
> 2.55.0
>