diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index 405964d24..27ee38b80 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -418,6 +418,63 @@ BL2 execution continues as follows: #. BL1 passes control to BL31 at the specified entrypoint at EL3. +Running BL2 at EL3 execution level +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some platforms have a non-TF Boot ROM that expects the next boot stage +to execute at EL3. On these platforms, TF BL1 is a waste of memory +as its only purpose is to ensure TF BL2 is entered at S-EL1. To avoid +this waste, a special mode enables BL2 to execute at EL3, which allows +a non-TF Boot ROM to load and jump directly to BL2. This mode is selected +when the build flag BL2_AT_EL3 is enabled. The main differences in this +mode are: + +#. BL2 includes the reset code and the mailbox mechanism to differentiate + cold boot and warm boot. It runs at EL3 doing the arch + initialization required for EL3. + +#. BL2 does not receive the meminfo information from BL1 anymore. This + information can be passed by the Boot ROM or be internal to the + BL2 image. + +#. Since BL2 executes at EL3, BL2 jumps directly to the next image, + instead of invoking the RUN_IMAGE SMC call. + + +We assume 3 different types of BootROM support on the platform: + +#. The Boot ROM always jumps to the same address, for both cold + and warm boot. In this case, we will need to keep a resident part + of BL2 whose memory cannot be reclaimed by any other image. The + linker script defines the symbols __TEXT_RESIDENT_START__ and + __TEXT_RESIDENT_END__ that allows the platform to configure + correctly the memory map. +#. The platform has some mechanism to indicate the jump address to the + Boot ROM. Platform code can then program the jump address with + psci_warmboot_entrypoint during cold boot. +#. The platform has some mechanism to program the reset address using + the PROGRAMMABLE_RESET_ADDRESS feature. Platform code can then + program the reset address with psci_warmboot_entrypoint during + cold boot, bypassing the boot ROM for warm boot. + +In the last 2 cases, no part of BL2 needs to remain resident at +runtime. In the first 2 cases, we expect the Boot ROM to be able to +differentiate between warm and cold boot, to avoid loading BL2 again +during warm boot. + +This functionality can be tested with FVP loading the image directly +in memory and changing the address where the system jumps at reset. +For example: + + -C cluster0.cpu0.RVBAR=0x4014000 + --data cluster0.cpu0=bl2.bin@0x4014000 + +With this configuration, FVP is like a platform of the first case, +where the Boot ROM jumps always to the same address. For simplification, +BL32 is loaded in DRAM in this case, to avoid other images reclaiming +BL2 memory. + + AArch64 BL31 ~~~~~~~~~~~~ diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index f020ec97d..0eb4ac3ab 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -1624,6 +1624,70 @@ element in the boot sequence. If there are no more boot sources then it must return 0, otherwise it must return 1. The default implementation of this always returns 0. +Boot Loader Stage 2 (BL2) at EL3 +-------------------------------- + +When the platform has a non-TF Boot ROM it is desirable to jump +directly to BL2 instead of TF BL1. In this case BL2 is expected to +execute at EL3 instead of executing at EL1. Refer to the `Firmware +Design`_ for more information. + +All mandatory functions of BL2 must be implemented, except the functions +bl2\_early\_platform\_setup and bl2\_el3\_plat\_arch\_setup, because +their work is done now by bl2\_el3\_early\_platform\_setup and +bl2\_el3\_plat\_arch\_setup. These functions should generally implement +the bl1\_plat\_xxx() and bl2\_plat\_xxx() functionality combined. + + +Function : bl2\_el3\_early\_platform\_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + Argument : u_register_t, u_register_t, u_register_t, u_register_t + Return : void + +This function executes with the MMU and data caches disabled. It is only called +by the primary CPU. This function receives four parameters which can be used +by the platform to pass any needed information from the Boot ROM to BL2. + +On ARM standard platforms, this function does the following: + +- Initializes a UART (PL011 console), which enables access to the ``printf`` + family of functions in BL2. + +- Initializes the storage abstraction layer used to load further bootloader + images. It is necessary to do this early on platforms with a SCP\_BL2 image, + since the later ``bl2_platform_setup`` must be done after SCP\_BL2 is loaded. + +- Initializes the private variables that define the memory layout used. + +Function : bl2\_el3\_plat\_arch\_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + Argument : void + Return : void + +This function executes with the MMU and data caches disabled. It is only called +by the primary CPU. + +The purpose of this function is to perform any architectural initialization +that varies across platforms. + +On ARM standard platforms, this function enables the MMU. + +Function : bl2\_el3\_plat\_prepare\_exit() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + Argument : void + Return : void + +This function is called prior to exiting BL2 and run the next image. +It should be used to perform platform specific clean up or bookkeeping +operations before transferring control to the next image. This function +runs with MMU disabled. + FWU Boot Loader Stage 2 (BL2U) ------------------------------ diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 13f096419..274faa811 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -245,6 +245,9 @@ Common build options BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not be built. +- ``BL2_AT_EL3``: This is an optional build option that enables the use of + BL2 at EL3 execution level. + - ``BL31``: This is an optional build option which specifies the path to BL31 image for the ``fip`` target. In this case, the BL31 in the ARM Trusted Firmware will not be built.