Download agents have different firmware and eMMC provisioning requirements from normal storage boot. Document them so users can build compatible images and understand which persistent eMMC settings each agent changes.
Signed-off-by: Carlo Caione <[email protected]> --- doc/board/mediatek/mt8188-genio-evk.rst | 81 +++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/doc/board/mediatek/mt8188-genio-evk.rst b/doc/board/mediatek/mt8188-genio-evk.rst index e36e8faeb48..43948bb4365 100644 --- a/doc/board/mediatek/mt8188-genio-evk.rst +++ b/doc/board/mediatek/mt8188-genio-evk.rst @@ -279,3 +279,84 @@ 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. + +BootROM download agents +----------------------- + +A download agent (DA) runs from RAM and exposes eMMC through USB fastboot for +provisioning or recovery. The BootROM downloads ``da.bin`` into SRAM; the +external DDR loader initializes DRAM and enters SPL using the same execution +contract as normal boot. The DA itself is not installed in an eMMC partition. + +Two mutually exclusive modes are available: + +* ``CONFIG_MTK_BROM_DOWNLOAD_AGENT_SPL_FASTBOOT`` runs fastboot directly in + SPL. It needs the matching external DDR loader, but no BL31 or OP-TEE. +* ``CONFIG_MTK_BROM_DOWNLOAD_AGENT_UBOOT_FASTBOOT`` uses SPL to load BL31 and + U-Boot from a FIT in RAM. U-Boot then runs ``fastboot usb 0``. This mode needs + a matching BL31 built without an OP-TEE dependency, and a DDR loader which + implements the additional FIT copy described below. + +For Genio 700, build the SPL fastboot mode with:: + + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ make O=build-da-spl mt8390_genio_700_evk_da_spl_defconfig + $ make O=build-da-spl BINMAN_INDIRS=/path/to/firmware + +For fastboot in U-Boot proper:: + + $ make O=build-da-uboot mt8390_genio_700_evk_da_uboot_defconfig + $ make O=build-da-uboot BL31=/path/to/da-bl31.bin \ + BINMAN_INDIRS=/path/to/firmware + +Use the corresponding ``mt8370_genio_510_evk_da_spl_defconfig`` or +``mt8370_genio_510_evk_da_uboot_defconfig`` for Genio 510. Each build produces +``da.bin`` and ``da.map`` in its output directory. Use board- and mode-matched +firmware inputs; do not set ``TEE`` for these builds. + +Image and loader contract +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Both DA modes use the shared ``mtk-genio-*-binman-u-boot.dtsi`` templates and +``CONFIG_MTK_GENIO_IMAGE_CONTRACT`` settings. The image starts with the DDR +loader padded to ``CONFIG_MTK_GENIO_DDR_LOADER_SIZE``, followed by SPL padded +to ``CONFIG_SPL_MAX_SIZE``. The loader copies that SPL region to +``CONFIG_SPL_TEXT_BASE`` before entering it. SPL fastboot reserves a 16 MiB +heap, including space for the sparse writer's 8 MiB buffer. + +The full-U-Boot DA appends a FIT at ``CONFIG_MTK_GENIO_DA_FIT_OFFSET``, in a +fixed region of ``CONFIG_MTK_GENIO_DA_FIT_MAX_SIZE`` bytes. The external +loader must copy this complete region to ``CONFIG_SPL_LOAD_FIT_ADDRESS`` +before entering SPL. Its ``DA_FIT_OFFSET`` and ``DA_FIT_SIZE`` must match the +U-Boot settings. The FIT container is directly parseable; only its BL31 and +U-Boot payloads are gzip-compressed. SPL decompresses them to +``CONFIG_MTK_GENIO_BL31_LOAD_ADDR`` and ``CONFIG_TEXT_BASE`` respectively, +then enters BL31, which starts U-Boot. + +These fixed regions are part of the external loader ABI. Changing the image +sizes or addresses requires corresponding loader changes. Binman rejects +payloads which exceed their reserved regions. The generated DA is a raw +payload for the platform download tooling; it has no eMMC BootROM wrapper. +Its FIT hashes do not authenticate it. Platforms requiring authenticated +DAs must use their external signing and BootROM download tooling. + +Provisioning behavior +~~~~~~~~~~~~~~~~~~~~~ + +Before entering fastboot, the SPL DA selects eMMC boot0 (BOOT1 in the eMMC +register encoding), enables boot acknowledgment and sets the boot bus to +x1 SDR. If ``RST_N_FUNCTION`` is still zero, it permanently enables the eMMC +reset pin. That field is write-once. A previously programmed reset policy is +left unchanged. Preparation errors are printed and fastboot remains available +for recovery. + +The full-U-Boot DA does not perform that automatic eMMC boot preparation. +Its provisioning flow must configure the target's boot settings separately +when needed, particularly on a blank device. Neither mode changes the GPT or +writes firmware partitions until commanded by the host. Use the platform +provisioning tools with the matching DA and partition metadata. + +Use raw images with the eMMC boot-area aliases ``mmc0boot0`` and +``mmc0boot1``: these aliases write the downloaded bytes without expanding +Android sparse images. Sparse flashing is supported for GPT partitions and +the eMMC user-area alias. -- 2.55.0
