Describe how the DDR loader passes the DRAM description to U-Boot in a transfer list, and add the transfer list to the DDR-loader handoff contract.
Also state that U-Boot proper started by the platform BL2 now needs a transfer list with its devicetree. Signed-off-by: David Lechner <[email protected]> --- doc/board/mediatek/mt8189-genio-evk.rst | 79 ++++++++++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 6 deletions(-) diff --git a/doc/board/mediatek/mt8189-genio-evk.rst b/doc/board/mediatek/mt8189-genio-evk.rst index 184085b83c1..637aa21e271 100644 --- a/doc/board/mediatek/mt8189-genio-evk.rst +++ b/doc/board/mediatek/mt8189-genio-evk.rst @@ -35,8 +35,11 @@ In the usual boot chain, U-Boot provides only U-Boot proper:: -> U-Boot proper (BL33) The platform BL2 initializes DRAM and loads BL31, BL32 and BL33. U-Boot proper -is linked at ``CONFIG_TEXT_BASE``, ``0x4c000000``. It takes the DRAM size from -the ``memory`` node of its devicetree, which describes 8 GiB of DRAM. +is linked at ``CONFIG_TEXT_BASE``, ``0x4c000000``. + +U-Boot proper requires a transfer list containing its devicetree, and does not +start without one. The platform BL2 must therefore pass such a transfer list +to BL33, together with the DRAM description described in `DRAM description`_. Building ~~~~~~~~ @@ -96,12 +99,71 @@ by name. Make sure the DIP switches and jumpers are set for eMMC, and use the default devicetree. +DRAM description +~~~~~~~~~~~~~~~~ + +The DRAM size depends on the DRAM fitted to the board, and so do the regions +which DRAM initialization reserves for use by the hardware, such as the DRAM +controller's tracking buffers at the top of each rank. The devicetree built +into U-Boot cannot describe them, so the DDR loader describes them in a +devicetree overlay. It passes the overlay to SPL in a `Firmware Handoff`_ +transfer list, which U-Boot reads as its bloblist (see +:doc:`/develop/bloblist`). + +The overlay contains a ``memory`` node with the DRAM size and a ``no-map`` +``reserved-memory`` node for each reserved region. The first compatible string +of its root node must match the one of the U-Boot devicetree. For example, on +a Genio 720 EVK with 8 GiB of DRAM:: + + /dts-v1/; + /plugin/; + + / { + compatible = "mediatek,mt8391-evk"; + }; + + &{/} { + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + dramc-rk0@13fffe000 { + reg = <0x1 0x3fffe000 0x0 0x2000>; + no-map; + }; + + dramc-rk1@23fffe000 { + reg = <0x2 0x3fffe000 0x0 0x2000>; + no-map; + }; + }; + + memory@40000000 { + device_type = "memory"; + reg = <0x0 0x40000000 0x2 0x0>; + }; + }; + +SPL adds the devicetree of U-Boot proper from the FIT to the transfer list and +passes the list on to U-Boot proper, through the BL33 entry point arguments +that it gives to BL31. U-Boot proper takes its devicetree from the transfer +list, applies the overlay to it and passes the reserved regions on to the OS. +If the transfer list has no room for the devicetree, SPL moves it to a bigger +buffer, so the DDR loader only needs to make the transfer list big enough for +its own entries. + +SPL stops if the DDR loader does not pass a transfer list with an overlay, +since U-Boot would otherwise use a DRAM size that may be wrong and would not +reserve the memory used by the DRAM controller. + DDR-loader handoff contract ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The contract between the DDR loader and U-Boot SPL consists of a fixed image -layout, initialized DRAM and the execution state at the SPL entry point. The -BootROM loads the image payload to ``CONFIG_MTK_GENIO_BROM_LOAD_ADDR``:: +layout, initialized DRAM, a transfer list describing the DRAM, and the +execution state at the SPL entry point. The BootROM loads the image payload to +``CONFIG_MTK_GENIO_BROM_LOAD_ADDR``:: offset 0 +----------------------+ | DDR loader | @@ -129,10 +191,13 @@ The DDR loader must: * copy the complete ``CONFIG_SPL_MAX_SIZE`` byte SPL region from ``CONFIG_MTK_GENIO_BROM_LOAD_ADDR + CONFIG_MTK_GENIO_DDR_LOADER_SIZE`` (``0x20a1000``) to ``CONFIG_SPL_TEXT_BASE``, +* write the transfer list described in `DRAM description`_ to DRAM outside + the SPL region and the memory used by SPL and the images it loads, * leave the MMU and caches disabled, with all of its writes visible to the CPU, and -* enter SPL at ``CONFIG_SPL_TEXT_BASE`` in AArch64 EL3h with exceptions - masked. +* enter SPL at ``CONFIG_SPL_TEXT_BASE`` in AArch64 EL3h with exceptions masked, + and with the transfer list in ``x0`` to ``x3`` following the transfer list + register convention. SPL obtains platform information from its embedded control devicetree and initializes the console, clocks, pinctrl, watchdog and eMMC through U-Boot @@ -236,3 +301,5 @@ a prebuilt Genio image for the target board:: Writing an invalid image to eMMC boot0 can make the board unbootable. Preserve the platform recovery path while testing. + +.. _`Firmware Handoff`: https://github.com/FirmwareHandoff/firmware_handoff -- 2.53.0
