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]> --- 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
