diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/interrupt-framework-design.rst | 37 | ||||
| -rw-r--r-- | docs/porting-guide.rst | 78 | ||||
| -rw-r--r-- | docs/spd/trusty-dispatcher.rst | 17 | ||||
| -rw-r--r-- | docs/user-guide.rst | 15 |
4 files changed, 99 insertions, 48 deletions
diff --git a/docs/interrupt-framework-design.rst b/docs/interrupt-framework-design.rst index 940bc24f0..0eb7f54f2 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/porting-guide.rst b/docs/porting-guide.rst index 7683ded0e..21db86bde 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/spd/trusty-dispatcher.rst b/docs/spd/trusty-dispatcher.rst index f1982ea79..10b111d61 100644 --- a/docs/spd/trusty-dispatcher.rst +++ b/docs/spd/trusty-dispatcher.rst @@ -8,6 +8,23 @@ Detailed information and build instructions can be found on the Android Open Source Project (AOSP) webpage for Trusty hosted at https://source.android.com/security/trusty +Boot parameters +=============== + +Custom boot parameters can be passed to Trusty by providing a platform +specific function: + +.. code:: c + + void plat_trusty_set_boot_args(aapcs64_params_t *args) + +If this function is provided ``args->arg0`` must be set to the memory +size allocated to trusty. If the platform does not provide this +function, but defines ``TSP_SEC_MEM_SIZE``, a default implementation +will pass the memory size from ``TSP_SEC_MEM_SIZE``. ``args->arg1`` +can be set to a platform specific parameter block, and ``args->arg2`` +should then be set to the size of that block. + Supported platforms =================== diff --git a/docs/user-guide.rst b/docs/user-guide.rst index ed5ba1842..9e23711aa 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`_ |