diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/firmware-design.rst | 6 | ||||
| -rw-r--r-- | docs/interrupt-framework-design.rst | 37 | ||||
| -rw-r--r-- | docs/plat/hikey.rst | 2 | ||||
| -rw-r--r-- | docs/plat/socionext-uniphier.rst | 58 | ||||
| -rw-r--r-- | docs/porting-guide.rst | 78 | ||||
| -rw-r--r-- | docs/user-guide.rst | 15 |
6 files changed, 116 insertions, 80 deletions
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index 1f8fcc86..c383c5d1 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -2574,9 +2574,9 @@ This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 2. - The Common not Private (CnP) bit is enabled to indicate that multiple - Page Entries in the same Inner Shareable domain use the same translation - table entries for a given stage of translation for a particular translation - regime. + Processing Elements in the same Inner Shareable domain use the same + translation table entries for a given stage of translation for a particular + translation regime. ARMv7 ~~~~~ diff --git a/docs/interrupt-framework-design.rst b/docs/interrupt-framework-design.rst index 940bc24f..0eb7f54f 100644 --- a/docs/interrupt-framework-design.rst +++ b/docs/interrupt-framework-design.rst @@ -135,7 +135,7 @@ Non-secure interrupts former's state is correctly saved by the latter. #. **CSS=1, TEL3=0**. Interrupt is routed to FEL when execution is in - non-secure state. This is an valid routing model as a non-secure interrupt + non-secure state. This is a valid routing model as a non-secure interrupt is handled by non-secure software. #. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in @@ -151,6 +151,10 @@ EL3 interrupts in Secure-EL1/Secure-EL0 is in control of how its execution is preempted by EL3 interrupt and can handover the interrupt to EL3 for handling. + However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is + invalid as EL3 interrupts are unconditionally routed to EL3, and EL3 + interrupts will always preempt Secure EL1/EL0 execution. + #. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in Secure-EL1/Secure-EL0. This is a valid routing model as secure software in EL3 can handle the interrupt. @@ -212,17 +216,14 @@ The framework makes the following assumptions to simplify its implementation. #. Interrupt exceptions (``PSTATE.I`` and ``F`` bits) are masked during execution in EL3. -#. .. rubric:: Interrupt management - :name: interrupt-management - - The following sections describe how interrupts are managed by the interrupt - handling framework. This entails: +#. Interrupt management: the following sections describe how interrupts are + managed by the interrupt handling framework. This entails: -#. Providing an interface to allow registration of a handler and specification - of the routing model for a type of interrupt. + #. Providing an interface to allow registration of a handler and + specification of the routing model for a type of interrupt. -#. Implementing support to hand control of an interrupt type to its registered - handler when the interrupt is generated. + #. Implementing support to hand control of an interrupt type to its + registered handler when the interrupt is generated. Both aspects of interrupt management involve various components in the secure software stack spanning from EL3 to Secure-EL1. These components are described @@ -415,6 +416,9 @@ runtime. Test secure payload dispatcher behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being +``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``. + The TSPD only handles Secure-EL1 interrupts and is provided with the following routing model at build time. @@ -678,14 +682,14 @@ the handler function for that type of interrupt. The SPD service is responsible for the following: #. Validating the interrupt. This involves ensuring that the interrupt was - generating according to the interrupt routing model specified by the SPD + generated according to the interrupt routing model specified by the SPD service during registration. It should use the security state of the exception level (passed in the ``flags`` parameter of the handler) where the interrupt was taken from to determine this. If the interrupt is not recognised then the handler should treat it as an irrecoverable error condition. - A SPD service can register a handler for Secure-EL1 and/or Non-secure + An SPD service can register a handler for Secure-EL1 and/or Non-secure interrupts. A non-secure interrupt should never be routed to EL3 from from non-secure state. Also if a routing model is chosen where Secure-EL1 interrupts are routed to S-EL1 when execution is in Secure state, then a @@ -809,9 +813,10 @@ Test secure payload dispatcher non-secure interrupt handling The TSP in Secure-EL1 can be preempted by a non-secure interrupt during ``yielding`` SMC processing or by a higher priority EL3 interrupt during -Secure-EL1 interrupt processing. Currently only non-secure interrupts can -cause preemption of TSP since there are no EL3 interrupts in the -system. +Secure-EL1 interrupt processing. When ``EL3_EXCEPTION_HANDLING`` is ``0``, only +non-secure interrupts can cause preemption of TSP since there are no EL3 +interrupts in the system. With ``EL3_EXCEPTION_HANDLING=1`` however, any EL3 +interrupt may preempt Secure execution. It should be noted that while TSP is preempted, the TSPD only allows entry into the TSP either for Secure-EL1 interrupt handling or for resuming the preempted @@ -994,7 +999,7 @@ TSP by returning ``SMC_UNK`` error. -------------- -*Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2018, ARM Limited and Contributors. All rights reserved.* .. _Porting Guide: ./porting-guide.rst .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html diff --git a/docs/plat/hikey.rst b/docs/plat/hikey.rst index 1c481044..99259f3a 100644 --- a/docs/plat/hikey.rst +++ b/docs/plat/hikey.rst @@ -65,7 +65,7 @@ Build Procedure BUILDFLAGS=-DSERIAL_BASE=0xF8015000 - If your hikey hardware is built by LeMarker, nothing to do. + If your hikey hardware is built by LeMaker, nothing to do. - Build it as debug mode. Create your own build script file or you could refer to **build\_uefi.sh** in l-loader git repository. diff --git a/docs/plat/socionext-uniphier.rst b/docs/plat/socionext-uniphier.rst index 2c652ac9..590ff625 100644 --- a/docs/plat/socionext-uniphier.rst +++ b/docs/plat/socionext-uniphier.rst @@ -3,26 +3,28 @@ ARM Trusted Firmware for Socionext UniPhier SoCs Socionext UniPhier ARMv8-A SoCs use ARM Trusted Firmware as the secure world -firmware, supporting BL1, BL2, and BL31. - -UniPhier SoC family implements its internal boot ROM, so BL1 is used as pseudo -ROM (i.e. runs in RAM). The internal boot ROM loads 64KB [1]_ image from a -non-volatile storage to the on-chip SRAM. Unfortunately, BL1 does not fit in -the 64KB limit if `Trusted Board Boot`_ (TBB) is enabled. To solve this problem, -Socionext provides a first stage loader called `UniPhier BL`_. This loader runs -in the on-chip SRAM, initializes the DRAM, expands BL1 there, and hands the -control over to it. Therefore, all images of ARM Trusted Firmware run in DRAM. +firmware, supporting BL2 and BL31. + +UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_ +image from a non-volatile storage to the on-chip SRAM, and jumps over to it. +ARM Trusted Firmware provides a special mode, BL2-AT-EL3, which enables BL2 to +execute at EL3. It is useful for platforms with non-TF boot ROM, like UniPhier. +Here, a problem is BL2 does not fit in the 64KB limit if `Trusted Board Boot`_ +(TBB) is enabled. To solve this issue, Socionext provides a first stage loader +called `UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the +DRAM, expands BL2 there, and hands the control over to it. Therefore, all images +of ARM Trusted Firmware run in DRAM. The UniPhier platform works with/without TBB. See below for the build process of each case. The image authentication for the UniPhier platform fully complies with the Trusted Board Boot Requirements (TBBR) specification. The UniPhier BL does not implement the authentication functionality, that is, -it can not verify the BL1 image by itself. Instead, the UniPhier BL assures -the BL1 validity in a different way; BL1 is GZIP-compressed and appended to -the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL1 -fits in the 64KB limit. The concatenated image is loaded by the boot ROM -(and verified if the chip fuses are blown). +it can not verify the BL2 image by itself. Instead, the UniPhier BL assures +the BL2 validity in a different way; BL2 is GZIP-compressed and appended to +the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL2 +fits in the 64KB limit. The concatenated image is loaded by the internal boot +ROM (and verified if the chip fuses are blown). Boot Flow @@ -31,32 +33,32 @@ Boot Flow 1. The Boot ROM This is hard-wired ROM, so never corrupted. It loads the UniPhier BL (with - compressed-BL1 appended) into the on-chip SRAM. If the SoC fuses are blown, + compressed-BL2 appended) into the on-chip SRAM. If the SoC fuses are blown, the image is verified by the SoC's own method. 2. UniPhier BL This runs in the on-chip SRAM. After the minimum SoC initialization and DRAM - setup, it decompresses the appended BL1 image into the DRAM, then jumps to - the BL1 entry. + setup, it decompresses the appended BL2 image into the DRAM, then jumps to + the BL2 entry. -3. BL1 +3. BL2 (at EL3) - This runs in the DRAM. It extracts BL2 from FIP (Firmware Image Package). - If TBB is enabled, the BL2 is authenticated by the standard mechanism of ARM - Trusted Firmware. + This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally + SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled, + they are all authenticated by the standard mechanism of ARM Trusted Firmware. + After loading all the images, it jumps to the BL31 entry. -4. BL2, BL31, and more +4. BL31, BL32, and BL33 - They all run in the DRAM, and are authenticated by the standard mechanism if - TBB is enabled. See `Firmware Design`_ for details. + They all run in the DRAM. See `Firmware Design`_ for details. Basic Build ----------- -BL1 must be compressed for the reason above. The UniPhier's platform makefile -provides a build target ``bl1_gzip`` for this. +BL2 must be compressed for the reason above. The UniPhier's platform makefile +provides a build target ``bl2_gzip`` for this. For a non-secure boot loader (aka BL33), U-Boot is well supported for UniPhier SoCs. The U-Boot image (``u-boot.bin``) must be built in advance. For the build @@ -64,11 +66,11 @@ procedure of U-Boot, refer to the document in the `U-Boot`_ project. To build minimum functionality for UniPhier (without TBB):: - make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl1_gzip fip + make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl2_gzip fip Output images: -- ``bl1.bin.gzip`` +- ``bl2.bin.gz`` - ``fip.bin`` diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 7683ded0..21db86bd 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -459,19 +459,19 @@ constants must also be defined: - **#define : ADDR\_SPACE\_SIZE** Defines the total size of the address space in bytes. For example, for a 32 - bit address space, this value should be ``(1ull << 32)``. This definition is + bit address space, this value should be ``(1ULL << 32)``. This definition is now deprecated, platforms should use ``PLAT_PHY_ADDR_SPACE_SIZE`` and ``PLAT_VIRT_ADDR_SPACE_SIZE`` instead. - **#define : PLAT\_VIRT\_ADDR\_SPACE\_SIZE** Defines the total size of the virtual address space in bytes. For example, - for a 32 bit virtual address space, this value should be ``(1ull << 32)``. + for a 32 bit virtual address space, this value should be ``(1ULL << 32)``. - **#define : PLAT\_PHY\_ADDR\_SPACE\_SIZE** Defines the total size of the physical address space in bytes. For example, - for a 32 bit physical address space, this value should be ``(1ull << 32)``. + for a 32 bit physical address space, this value should be ``(1ULL << 32)``. If the platform port uses the IO storage framework, the following constants must also be defined: @@ -1179,25 +1179,6 @@ its own use. This function helps fulfill requirements 4 and 5 above. -Function : bl1\_init\_bl2\_mem\_layout() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : meminfo *, meminfo * - Return : void - -BL1 needs to tell the next stage the amount of secure RAM available -for it to use. This information is populated in a ``meminfo`` -structure. - -Depending upon where BL2 has been loaded in secure RAM (determined by -``BL2_BASE``), BL1 calculates the amount of free memory available for BL2 to use. -BL1 also ensures that its data sections resident in secure RAM are not visible -to BL2. An illustration of how this is done in ARM standard platforms is given -in the **Memory layout on ARM development platforms** section in the -`Firmware Design`_. - Function : bl1\_plat\_prepare\_exit() [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1259,6 +1240,30 @@ standard platforms return an image descriptor corresponding to BL2 or one of the firmware update images defined in the Trusted Board Boot Requirements specification. +Function : bl1\_plat\_handle\_pre\_image\_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int image_id + Return : int + +This function can be used by the platforms to update/use image information +corresponding to ``image_id``. This function is invoked in BL1, both in cold +boot and FWU code path, before loading the image. + +Function : bl1\_plat\_handle\_post\_image\_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int image_id + Return : int + +This function can be used by the platforms to update/use image information +corresponding to ``image_id``. This function is invoked in BL1, both in cold +boot and FWU code path, after loading and authenticating the image. + Function : bl1\_plat\_fwu\_done() [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1424,10 +1429,22 @@ The purpose of this function is to return a pointer to a ``meminfo`` structure populated with the extents of secure RAM available for BL2 to use. See ``bl2_early_platform_setup()`` above. -Following function is required only when LOAD\_IMAGE\_V2 is enabled. +Following functions are optionally used only when LOAD\_IMAGE\_V2 is enabled. -Function : bl2\_plat\_handle\_post\_image\_load() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2\_plat\_handle\_pre\_image\_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +This function can be used by the platforms to update/use image information +for given ``image_id``. This function is currently invoked in BL2 before +loading each image, when LOAD\_IMAGE\_V2 is enabled. + +Function : bl2\_plat\_handle\_post\_image\_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1435,9 +1452,8 @@ Function : bl2\_plat\_handle\_post\_image\_load() [mandatory] Return : int This function can be used by the platforms to update/use image information -for given ``image_id``. This function is currently invoked in BL2 to handle -BL image specific information based on the ``image_id`` passed, when -LOAD\_IMAGE\_V2 is enabled. +for given ``image_id``. This function is currently invoked in BL2 after +loading each image, when LOAD\_IMAGE\_V2 is enabled. Following functions are required only when LOAD\_IMAGE\_V2 is disabled. @@ -2006,9 +2022,9 @@ This macro must be defined to the EL3 exception priority level associated with Critical SDEI events on the platform. This must have a lower value (therefore of higher priority) than ``PLAT_SDEI_NORMAL_PRI``. -It's recommended that SDEI exception priorities in general are assigned the -lowest among Secure priorities. Among the SDEI exceptions, Critical SDEI -priority must be higher than Normal SDEI priority. +**Note**: SDEI exception priorities must be the lowest among Secure priorities. +Among the SDEI exceptions, Critical SDEI priority must be higher than Normal +SDEI priority. Functions ......... diff --git a/docs/user-guide.rst b/docs/user-guide.rst index ed5ba184..9e23711a 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -617,6 +617,9 @@ Common build options interrupts to TSP allowing it to save its context and hand over synchronously to EL3 via an SMC. + Note: when ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` + must also be set to ``1``. + - ``USE_COHERENT_MEM``: This flag determines whether to include the coherent memory region in the BL memory map or not (see "Use of Coherent memory in Trusted Firmware" section in `Firmware Design`_). It can take the value 1 @@ -752,6 +755,9 @@ ARM FVP platform specific build options - ``FVP_CCN`` : The CCN driver is selected. This is the default if ``FVP_CLUSTER_COUNT`` > 2. +- ``FVP_MAX_CPUS_PER_CLUSTER``: Sets the maximum number of CPUs implemented in + a single cluster. This option defaults to 4. + - ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU in the system. This option defaults to 1. Note that the build option ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms. @@ -1579,6 +1585,7 @@ The following ``Foundation_Platform`` parameters should be used to boot Linux wi <path-to>/Foundation_Platform \ --cores=4 \ + --arm-v8.0 \ --secure-memory \ --visualization \ --gicv3 \ @@ -1597,6 +1604,12 @@ Notes: and enable the GICv3 device in the model. Note that without this option, the Foundation FVP defaults to legacy (Versatile Express) memory map which is not supported by ARM Trusted Firmware. +- In order for the Arm Trusted Firmware to run correctly on the Foundation + Model the architecture versions must match. The Foundation FVP defaults to + the highest v8.x version it supports but the default build for Arm Trusted + Firmware is for v8.0. To avoid issues either start the Foundation Model to + use v8.0 architecture using the ``--arm-v8.0`` option or build Arm Trusted + Firmware with an appropriate value for ``ARM_ARCH_MINOR``. Running on the AEMv8 Base FVP with reset to BL1 entrypoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1867,7 +1880,7 @@ wakeup interrupt from RTC. -------------- -*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2018, ARM Limited and Contributors. All rights reserved.* .. _Linaro: `Linaro Release Notes`_ .. _Linaro Release: `Linaro Release Notes`_ |