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 <[email protected]> > --- > 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/[email protected]/ 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 <[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..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. >
