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 >
