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

[David Lechner via U-Boot <u-boot@lists.u-boot-project.org>]

On 7/18/26 11:16 AM, Carlo Caione wrote:
> 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 <ccaione@baylibre.com>
> ---
>  MAINTAINERS                                 |   1 +
>  board/mediatek/MAINTAINERS                  |   1 +
>  doc/board/mediatek/index.rst                |   1 +
>  doc/board/mediatek/mt8390-genio-700-evk.rst | 168 ++++++++++++++++++++++++++++
>  4 files changed, 171 insertions(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index e5b2a2e373c..116a7fe3423 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -421,6 +421,7 @@ F:	arch/arm/dts/mt*
>  F:	arch/arm/mach-mediatek/
>  F:	arch/arm/include/asm/arch-mediatek/
>  F:	board/mediatek/
> +F:	doc/board/mediatek/

This is no longer needed since [1].

[1]: https://lore.kernel.org/u-boot/20260617024105.152655-1-marek.vasut+renesas@mailbox.org/

I can fix up when applying if nothing else comes up.

>  F:	doc/device-tree-bindings/phy/phy-mtk-*
>  F:	doc/device-tree-bindings/usb/mediatek,*
>  F:	doc/README.mediatek
> diff --git a/board/mediatek/MAINTAINERS b/board/mediatek/MAINTAINERS
> index efd38d52338..bcf5fe66a1e 100644
> --- a/board/mediatek/MAINTAINERS
> +++ b/board/mediatek/MAINTAINERS
> @@ -26,6 +26,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 <Macpaul.Lin@mediatek.com>
> 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..152e5e35fa5
> --- /dev/null
> +++ b/doc/board/mediatek/mt8390-genio-700-evk.rst
> @@ -0,0 +1,168 @@
> +.. 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 product, which uses the
> +MT8188 SoC. The board is configured with

This doesn't sound right. It is based on MT8390 SoC. It is DT compatible with
MT8188, but I don't think that is worth mentioning here.

> +``mt8390_genio_700_evk_defconfig``.
> +
> +Boot chain
> +----------
> +
> +The normal eMMC boot chain is::
> +
> +   BootROM
> +     -> external DDR loader

What does "external" mean in this context? Proprietary?

> +     -> U-Boot SPL
> +     -> Arm Trusted Firmware-A BL31

Put BL31 in () to be consistent.

> +     -> OP-TEE (BL32)
> +     -> U-Boot proper (BL33)
> +
> +The BootROM loads a MediaTek image from the eMMC boot0 hardware partition.
> +This image contains an external 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
> +BL31, OP-TEE, U-Boot proper and the U-Boot control devicetree. SPL uses the

Inconsistent use of BL31 and application names.

> +standard FIT and Arm Trusted Firmware handoff code to start the remaining

s/handoff/hands off/

> +stages.
> +
> +The external DDR loader is a platform firmware component and is not built by
> +U-Boot.
> +
> +Build prerequisites
> +-------------------
> +
> +The following external binaries are required:
> +
> +``ddr-loader.bin``
> +   The MediaTek DDR loader for the board. The input may be shorter than
> +   ``0x4b000`` bytes; binman pads it with zeroes to the offset reserved before
> +   SPL. It must have been built with ``SPL_OFFSET=0x4b000``,

Inconsistent formatting. Should be ...

``SPL``
  It must ...

?

> +   ``SPL_SIZE=CONFIG_SPL_MAX_SIZE`` and an SPL destination and entry address
> +   matching ``CONFIG_SPL_TEXT_BASE``.
> +
> +``BL31``

Why is this BL31 instead of TF-A?

> +   The path to the TF-A BL31 binary built for MT8188/MT8390. It is loaded and
> +   entered at ``0x54601000``.
> +
> +``TEE``
> +   The path to 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 BL31=/path/to/bl31.bin
> +   $ export TEE=/path/to/tee.bin
> +   $ make O=build TEE="$TEE" mt8390_genio_700_evk_defconfig

Isn't it redundant to have TEE="$TEE" since it was exported above?

> +   $ make O=build BINMAN_INDIRS=/path/to/firmware \
> +         BL31="$BL31" TEE="$TEE"

Same here for BL31 and TEE.

> +
> +``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 O=build mt8390_genio_700_evk_defconfig
> +   $ make O=build u-boot.bin spl/u-boot-spl.bin

Do we really need O=build in all of the examples?

> +
> +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.
> +
> +A complete build without the external binaries can instead be requested with::
> +
> +   $ make O=build BINMAN_ALLOW_MISSING=1
> +
> +The standalone binaries from such a build remain usable, but the packaged
> +images contain fake external blobs and must not be deployed.

How is it usable if it can't be deployed?

> +
> +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
> +~~~~~~~~~~~~~~~~~

Probably deserves an external link on where to get genio-tools and pre-build
images.

> +
> +``genio-flash`` needs a Genio image directory containing the partition
> +metadata and a compatible 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.
>