[PATCH v2 0/4] Add Genio 700 SPL boot support

[PATCH v2 0/4] Add Genio 700 SPL boot support

[Carlo Caione via U-Boot]

The Genio 700 boot chain uses a platform DDR loader built separately
from U-Boot to initialize DRAM before entering U-Boot SPL. Add the SPL
devicetree and configuration needed to initialize the debug UART, watchdog,
pinctrl, and eMMC, then load a conventional FIT from the bootloaders GPT
partition.

Add a binman description that generates the two images consumed by the
MediaTek flashing flow:

  mtk-boot.bin
    MediaTek BootROM wrapper containing the platform DDR loader and SPL

  bootloaders.img
    FIT containing BL31, OP-TEE, U-Boot proper, and its control DT

The DDR loader, BL31, and OP-TEE remain external build inputs. Document the
complete build and flashing procedure.

Tested on a Genio 700 EVK using a full genio-flash cycle and a cold
boot. SPL loaded the FIT from eMMC and passed OP-TEE as BL32 and U-Boot
proper as BL33 to BL31. Linux 6.6.37 reached the RITY login prompt.

Signed-off-by: Carlo Caione <ccaione@baylibre.com>
---
Changes in v2:
- Clarify that the platform DDR loader is built separately from U-Boot.
- Fix the SPL copy-window wording in patch 2.
- Keep the SPL annotations board-scoped and drop the unused pericfg_ao tag.
- Normalize the firmware-stage names in the board documentation.
- Simplify the documented build commands.
- Remove the redundant MediaTek documentation maintainer pattern.
- Add links to Genio Tools and prebuilt images.
- Link to v1: https://patch.msgid.link/20260718-ccaione-upstream-mt8390-spl-v1-0-1256b6dfda3f@baylibre.com

---
Carlo Caione (4):
      arm: dts: mediatek: prepare Genio 700 devices for SPL
      configs: mt8390: enable eMMC FIT boot from SPL
      arm: mediatek: mt8390: build boot images with binman
      doc: board: mediatek: document Genio 700 SPL boot

 arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi | 206 ++++++++++++++++++++++++++
 arch/arm/mach-mediatek/Kconfig                |   1 +
 board/mediatek/MAINTAINERS                    |   1 +
 configs/mt8390_genio_700_evk_defconfig        |  28 ++++
 doc/board/mediatek/index.rst                  |   1 +
 doc/board/mediatek/mt8390-genio-700-evk.rst   | 164 ++++++++++++++++++++
 6 files changed, 401 insertions(+)
---
base-commit: d0c49353a648e135f269a2953dc9326505ba87de
change-id: 20260717-ccaione-upstream-mt8390-spl-7f64ca12dfbd

Best regards,
--  
Carlo Caione <ccaione@baylibre.com>

[PATCH v2 1/4] arm: dts: mediatek: prepare Genio 700 devices for SPL

[Carlo Caione via U-Boot]

The Genio 700 boot flow enters U-Boot SPL after an external DDR loader
has initialized DRAM. SPL then needs the debug UART and eMMC controller,
together with their clock, syscon, pinctrl and watchdog providers, to
load the firmware FIT.

Signed-off-by: Julien Masson <jmasson@baylibre.com>
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
---
 arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi | 86 +++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi b/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
index 586d15bf72e..2b392c866fb 100644
--- a/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
+++ b/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
@@ -5,3 +5,89 @@
  */
 
 #include "mt8188-u-boot.dtsi"
+
+&clk26m {
+	bootph-pre-ram;
+};
+
+&gic {
+	bootph-pre-ram;
+};
+
+&topckgen {
+	bootph-pre-ram;
+};
+
+&infracfg_ao {
+	bootph-pre-ram;
+};
+
+&pio {
+	bootph-pre-ram;
+};
+
+&watchdog {
+	bootph-pre-ram;
+};
+
+&apmixedsys {
+	bootph-pre-ram;
+};
+
+&uart0 {
+	bootph-pre-ram;
+};
+
+&mmc0 {
+	bootph-pre-ram;
+};
+
+/ {
+	memory@40000000 {
+		bootph-pre-ram;
+	};
+};
+
+&mmc0_default_pins {
+	bootph-pre-ram;
+
+	pins-clk {
+		bootph-pre-ram;
+	};
+
+	pins-cmd-dat {
+		bootph-pre-ram;
+	};
+
+	pins-rst {
+		bootph-pre-ram;
+	};
+};
+
+&mmc0_uhs_pins {
+	bootph-pre-ram;
+
+	pins-clk {
+		bootph-pre-ram;
+	};
+
+	pins-cmd-dat {
+		bootph-pre-ram;
+	};
+
+	pins-ds {
+		bootph-pre-ram;
+	};
+
+	pins-rst {
+		bootph-pre-ram;
+	};
+};
+
+&uart0_pins {
+	bootph-pre-ram;
+
+	pins {
+		bootph-pre-ram;
+	};
+};

-- 
2.55.0

[PATCH v2 2/4] configs: mt8390: enable eMMC FIT boot from SPL

[Carlo Caione via U-Boot]

Enable the normal Genio 700 SPL path entered by the external DDR
loader at 0x40000000. Bind the raw SPL to the loader's 0xaf000-byte
copy window, place BSS separately in DRAM, and retain the
non-overlapping SPL malloc region.

Use generic SPL MMC, GPT, FIT, and Arm Trusted Firmware support to load
the firmware FIT from eMMC partition 1. Keep U-Boot proper at the shared
MT8188 CONFIG_TEXT_BASE of 0x4c000000.

The MediaTek BL31 used on Genio 700 stalls when passed the runtime
devicetree as its platform parameter. Enable SPL_ATF_NO_PLATFORM_PARAM
so SPL can still use the tree to locate OP-TEE and U-Boot while passing
NULL as the separate BL31 platform parameter.

Signed-off-by: Vitor Sato Eschholz <vsatoes@baylibre.com>
Signed-off-by: Julien Stephan <jstephan@baylibre.com>
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
---
 configs/mt8390_genio_700_evk_defconfig | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/configs/mt8390_genio_700_evk_defconfig b/configs/mt8390_genio_700_evk_defconfig
index fe4f6ad9016..5730b056e29 100644
--- a/configs/mt8390_genio_700_evk_defconfig
+++ b/configs/mt8390_genio_700_evk_defconfig
@@ -1,3 +1,30 @@
 #include <configs/mt8188.config>
 
 CONFIG_DEFAULT_DEVICE_TREE="mediatek/mt8390-genio-700-evk"
+CONFIG_SPL=y
+CONFIG_SPL_TEXT_BASE=0x40000000
+CONFIG_SPL_MAX_SIZE=0xaf000
+CONFIG_SPL_HAS_BSS_LINKER_SECTION=y
+CONFIG_SPL_BSS_START_ADDR=0x400bb800
+CONFIG_SPL_BSS_LIMIT=y
+CONFIG_SPL_BSS_MAX_SIZE=0x100000
+CONFIG_SPL_SYS_MALLOC=y
+CONFIG_SPL_HAS_CUSTOM_MALLOC_START=y
+CONFIG_SPL_CUSTOM_SYS_MALLOC_ADDR=0x5c000000
+CONFIG_SPL_SYS_MALLOC_SIZE=0x9000000
+CONFIG_SPL_SYSCON=y
+CONFIG_SPL_CLK=y
+CONFIG_SPL_SERIAL=y
+# CONFIG_SPL_USE_TINY_PRINTF is not set
+CONFIG_SPL_PINCTRL=y
+CONFIG_SPL_PINCONF=y
+CONFIG_SPL_WATCHDOG=y
+CONFIG_SPL_MMC=y
+CONFIG_SPL_LIBDISK_SUPPORT=y
+CONFIG_SPL_EFI_PARTITION=y
+CONFIG_SPL_SYS_MMCSD_RAW_MODE=y
+CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_USE_PARTITION=y
+CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=1
+CONFIG_SPL_LOAD_FIT=y
+CONFIG_SPL_ATF=y
+CONFIG_SPL_ATF_NO_PLATFORM_PARAM=y

-- 
2.55.0

Re: [PATCH v2 2/4] configs: mt8390: enable eMMC FIT boot from SPL

[Julien Stephan]

Le mer. 22 juil. 2026 à 23:36, Carlo Caione <ccaione@baylibre.com> a écrit :
>
> Enable the normal Genio 700 SPL path entered by the external DDR
> loader at 0x40000000. Bind the raw SPL to the loader's 0xaf000-byte
> copy window, place BSS separately in DRAM, and retain the
> non-overlapping SPL malloc region.
>
> Use generic SPL MMC, GPT, FIT, and Arm Trusted Firmware support to load
> the firmware FIT from eMMC partition 1. Keep U-Boot proper at the shared
> MT8188 CONFIG_TEXT_BASE of 0x4c000000.
>
> The MediaTek BL31 used on Genio 700 stalls when passed the runtime
> devicetree as its platform parameter. Enable SPL_ATF_NO_PLATFORM_PARAM
> so SPL can still use the tree to locate OP-TEE and U-Boot while passing
> NULL as the separate BL31 platform parameter.
>
> Signed-off-by: Vitor Sato Eschholz <vsatoes@baylibre.com>
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
> Signed-off-by: Carlo Caione <ccaione@baylibre.com>
> ---
>  configs/mt8390_genio_700_evk_defconfig | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>
> diff --git a/configs/mt8390_genio_700_evk_defconfig b/configs/mt8390_genio_700_evk_defconfig
> index fe4f6ad9016..5730b056e29 100644
> --- a/configs/mt8390_genio_700_evk_defconfig
> +++ b/configs/mt8390_genio_700_evk_defconfig
> @@ -1,3 +1,30 @@
>  #include <configs/mt8188.config>
>
>  CONFIG_DEFAULT_DEVICE_TREE="mediatek/mt8390-genio-700-evk"
> +CONFIG_SPL=y
> +CONFIG_SPL_TEXT_BASE=0x40000000
> +CONFIG_SPL_MAX_SIZE=0xaf000
> +CONFIG_SPL_HAS_BSS_LINKER_SECTION=y
> +CONFIG_SPL_BSS_START_ADDR=0x400bb800
> +CONFIG_SPL_BSS_LIMIT=y
> +CONFIG_SPL_BSS_MAX_SIZE=0x100000
> +CONFIG_SPL_SYS_MALLOC=y
> +CONFIG_SPL_HAS_CUSTOM_MALLOC_START=y
> +CONFIG_SPL_CUSTOM_SYS_MALLOC_ADDR=0x5c000000
> +CONFIG_SPL_SYS_MALLOC_SIZE=0x9000000
> +CONFIG_SPL_SYSCON=y
> +CONFIG_SPL_CLK=y
> +CONFIG_SPL_SERIAL=y
> +# CONFIG_SPL_USE_TINY_PRINTF is not set
> +CONFIG_SPL_PINCTRL=y
> +CONFIG_SPL_PINCONF=y
> +CONFIG_SPL_WATCHDOG=y
> +CONFIG_SPL_MMC=y
> +CONFIG_SPL_LIBDISK_SUPPORT=y
> +CONFIG_SPL_EFI_PARTITION=y
> +CONFIG_SPL_SYS_MMCSD_RAW_MODE=y
> +CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_USE_PARTITION=y
> +CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=1
> +CONFIG_SPL_LOAD_FIT=y
> +CONFIG_SPL_ATF=y
> +CONFIG_SPL_ATF_NO_PLATFORM_PARAM=y
>

Hi Carlo,

Did you test on Genio 510? AFAIK Genio 510 and Genio 700 are very similar.
If it works on Genio 510, then all theses configs could be placed into
 configs/mt8188.config.

Cheers
Julien

> --
> 2.55.0
>

Re: [PATCH v2 2/4] configs: mt8390: enable eMMC FIT boot from SPL

[Carlo Caione]

On Tue Jul 28, 2026 at 6:00 PM CEST, Julien Stephan wrote:
> Le mer. 22 juil. 2026 à 23:36, Carlo Caione <ccaione@baylibre.com> a écrit :
[...]

> Hi Carlo,
>
> Did you test on Genio 510? AFAIK Genio 510 and Genio 700 are very similar.
> If it works on Genio 510, then all theses configs could be placed into
>  configs/mt8188.config.

Hey Julien,
I didn't test it but being G700 and G510 so close I don't see why this
cannot be done.

thanks,

--
Carlo Caione

[PATCH v2 3/4] arm: mediatek: mt8390: build boot images with binman

[Carlo Caione via U-Boot]

Generate the Genio 700 boot-chain images from the U-Boot build.

mtk-boot.bin wraps an external DDR loader, padded to its fixed
0x4b000-byte ABI, followed by a CONFIG_SPL_MAX_SIZE U-Boot SPL region
in a MediaTek eMMC BootROM image. The external loader copies that
complete fixed-size SPL window, so pad the region to keep every source
byte inside the BootROM-loaded payload.

bootloaders.img is a conventional FIT containing BL31, U-Boot proper,
OP-TEE, and the U-Boot control devicetree.

Use the standard BL31 and TEE binman inputs and obtain ddr-loader.bin
through BINMAN_INDIRS. Disable SPL binman symbols because SPL and
U-Boot proper live in separate storage images. SPL locates U-Boot
through the GPT FIT partition, so there are no in-image U-Boot offsets
to publish.

Signed-off-by: Vitor Sato Eschholz <vsatoes@baylibre.com>
Signed-off-by: Julien Stephan <jstephan@baylibre.com>
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
---
 arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi | 120 ++++++++++++++++++++++++++
 arch/arm/mach-mediatek/Kconfig                |   1 +
 configs/mt8390_genio_700_evk_defconfig        |   1 +
 3 files changed, 122 insertions(+)

diff --git a/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi b/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
index 2b392c866fb..cd07538766a 100644
--- a/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
+++ b/arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi
@@ -4,6 +4,7 @@
  * Author: Julien Stephan <jstephan@baylibre.com>
  */
 
+#include <config.h>
 #include "mt8188-u-boot.dtsi"
 
 &clk26m {
@@ -43,11 +44,130 @@
 };
 
 / {
+	binman: binman {
+		multiple-images;
+	};
+
 	memory@40000000 {
 		bootph-pre-ram;
 	};
 };
 
+&binman {
+	mtk-boot {
+		filename = "mtk-boot.bin";
+
+		mkimage {
+			args = "-T", "mtk_image",
+			       "-a", "0x201000",
+			       "-e", "0x201000",
+			       "-n", "media=emmc;arm64=1";
+
+			section {
+				pad-byte = <0>;
+
+				/* Must match SPL_OFFSET in the external DDR loader. */
+				ddr-loader {
+					type = "blob-ext";
+					filename = "ddr-loader.bin";
+					size = <0x4b000>;
+				};
+
+				u-boot-spl {
+					size = <CONFIG_SPL_MAX_SIZE>;
+				};
+			};
+		};
+	};
+
+	bootloaders {
+		filename = "bootloaders.img";
+
+		fit {
+			description = "MediaTek Genio 700 bootloaders";
+			#address-cells = <1>;
+
+			images {
+				uboot {
+					description = "U-Boot";
+					type = "firmware";
+					os = "u-boot";
+					arch = "arm64";
+					compression = "none";
+					load = <CONFIG_TEXT_BASE>;
+					entry = <CONFIG_TEXT_BASE>;
+
+					u-boot-nodtb {
+					};
+
+					hash {
+						algo = "sha256";
+					};
+				};
+
+				atf {
+					description = "ARM Trusted Firmware BL31";
+					type = "firmware";
+					os = "arm-trusted-firmware";
+					arch = "arm64";
+					compression = "none";
+					load = <0x54601000>;
+					entry = <0x54601000>;
+
+					atf-bl31 {
+					};
+
+					hash {
+						algo = "sha256";
+					};
+				};
+
+				optee {
+					description = "OP-TEE";
+					type = "firmware";
+					os = "tee";
+					arch = "arm64";
+					compression = "none";
+					load = <0x431fffe4>;
+					entry = <0x43200000>;
+
+					tee-os {
+					};
+
+					hash {
+						algo = "sha256";
+					};
+				};
+
+				uboot-fdt {
+					description = "U-Boot control devicetree";
+					type = "flat_dt";
+					arch = "arm64";
+					compression = "none";
+
+					u-boot-dtb {
+					};
+
+					hash {
+						algo = "sha256";
+					};
+				};
+			};
+
+			configurations {
+				default = "conf";
+
+				conf {
+					description = "Genio 700 boot chain";
+					firmware = "atf";
+					loadables = "uboot", "optee";
+					fdt = "uboot-fdt";
+				};
+			};
+		};
+	};
+};
+
 &mmc0_default_pins {
 	bootph-pre-ram;
 
diff --git a/arch/arm/mach-mediatek/Kconfig b/arch/arm/mach-mediatek/Kconfig
index 5e6c50ca64d..9ff7e7a7f5e 100644
--- a/arch/arm/mach-mediatek/Kconfig
+++ b/arch/arm/mach-mediatek/Kconfig
@@ -87,6 +87,7 @@ config TARGET_MT8183
 config TARGET_MT8188
 	bool "MediaTek MT8188 SoC"
 	select ARM64
+	select BINMAN if SPL
 	help
 	  The MediaTek MT8188 is a ARM64-based SoC with a dual-core Cortex-A78
 	  cluster and a six-core Cortex-A55 cluster. It includes UART, SPI,
diff --git a/configs/mt8390_genio_700_evk_defconfig b/configs/mt8390_genio_700_evk_defconfig
index 5730b056e29..1287cdf0af6 100644
--- a/configs/mt8390_genio_700_evk_defconfig
+++ b/configs/mt8390_genio_700_evk_defconfig
@@ -2,6 +2,7 @@
 
 CONFIG_DEFAULT_DEVICE_TREE="mediatek/mt8390-genio-700-evk"
 CONFIG_SPL=y
+# CONFIG_SPL_BINMAN_SYMBOLS is not set
 CONFIG_SPL_TEXT_BASE=0x40000000
 CONFIG_SPL_MAX_SIZE=0xaf000
 CONFIG_SPL_HAS_BSS_LINKER_SECTION=y

-- 
2.55.0

Re: [PATCH v2 3/4] arm: mediatek: mt8390: build boot images with binman

[David Lechner]

On 7/22/26 4:35 PM, Carlo Caione wrote:
> Generate the Genio 700 boot-chain images from the U-Boot build.
> 
> mtk-boot.bin wraps an external DDR loader, padded to its fixed
> 0x4b000-byte ABI, followed by a CONFIG_SPL_MAX_SIZE U-Boot SPL region
> in a MediaTek eMMC BootROM image. The external loader copies that
> complete fixed-size SPL window, so pad the region to keep every source
> byte inside the BootROM-loaded payload.
> 
> bootloaders.img is a conventional FIT containing BL31, U-Boot proper,
> OP-TEE, and the U-Boot control devicetree.
> 
> Use the standard BL31 and TEE binman inputs and obtain ddr-loader.bin
> through BINMAN_INDIRS. Disable SPL binman symbols because SPL and
> U-Boot proper live in separate storage images. SPL locates U-Boot
> through the GPT FIT partition, so there are no in-image U-Boot offsets
> to publish.
> 
> Signed-off-by: Vitor Sato Eschholz <vsatoes@baylibre.com>
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
> Signed-off-by: Carlo Caione <ccaione@baylibre.com>
> ---
>  arch/arm/dts/mt8390-genio-700-evk-u-boot.dtsi | 120 ++++++++++++++++++++++++++

Similar to Julien's comment on patch 2, I would suggest to put
as much of this as possible in mt8390-genio-common-u-boot.dtsi (following
upstream naming convention) so that we don't have to repeat it
on Genio 510 or move it later.


>  arch/arm/mach-mediatek/Kconfig                |   1 +
>  configs/mt8390_genio_700_evk_defconfig        |   1 +
>  3 files changed, 122 insertions(+)
> 

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

[Carlo Caione via U-Boot]

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

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

[Julien Stephan]

Le mer. 22 juil. 2026 à 23:36, Carlo Caione <ccaione@baylibre.com> 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 <ccaione@baylibre.com>

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/87y0lblck1.fsf@kernel.org/#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 <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..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
>

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

[Carlo Caione]

On Tue Jul 28, 2026 at 6:13 PM CEST, Julien Stephan wrote:
> Le mer. 22 juil. 2026 à 23:36, Carlo Caione <ccaione@baylibre.com> 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 <ccaione@baylibre.com>
>
> Hi Carlo,

Hey Julien,

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

Oh TIL. No, I didn't sync explicitly on this point but that thread is
several months old and nothing was done about that so I think we can add
a bit of documentation, we can revise it later if needed or if MediaTek
wants to chime in (in CC).

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

That is unfortunatel not exactly true. We are currently relying
on an ABI contract between the loader and the SPL that is not yet
standardized (I'll document it in the next revision).

There is a conversation going on with several parties involved about
this but this is still pretty much WIP. So also in this case I prefer
to keep this contained for G510 and G700, we can revisit this once the
contract has been formalized and extended to all the Gevio platforms.

Cheers,

--
Carlo Caione