Merge pull request #122 from 'danh-arm:dh/v0.4-docs'
diff --git a/docs/diagrams/non-sec-int-handling.png b/docs/diagrams/non-sec-int-handling.png
new file mode 100644
index 0000000..1a5f629
--- /dev/null
+++ b/docs/diagrams/non-sec-int-handling.png
Binary files differ
diff --git a/docs/diagrams/sec-int-handling.png b/docs/diagrams/sec-int-handling.png
new file mode 100644
index 0000000..2ebbca4
--- /dev/null
+++ b/docs/diagrams/sec-int-handling.png
Binary files differ
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index ab575ed..b20f06b 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -8,10 +8,11 @@
3. EL3 runtime services framework
4. Power State Coordination Interface
5. Secure-EL1 Payloads and Dispatchers
-6. Memory layout on FVP platforms
-7. Firmware Image Package (FIP)
-8. Code Structure
-9. References
+6. Crash Reporting in BL3-1
+7. Memory layout on FVP platforms
+8. Firmware Image Package (FIP)
+9. Code Structure
+10. References
1. Introduction
@@ -31,6 +32,10 @@
instruction. The SMC instruction must be used as mandated by the [SMC Calling
Convention PDD][SMCCC] [3].
+The ARM Trusted Firmware implements a framework for configuring and managing
+interrupts generated in either security state. The details of the interrupt
+management framework and its design can be found in [ARM Trusted
+Firmware Interrupt Management Design guide][INTRG] [4].
2. Cold boot
-------------
@@ -56,6 +61,14 @@
trusted DRAM regions. Each boot loader stage uses one or more of these
memories for its code and data.
+The sections below provide the following details:
+
+* initialization and execution of the first three stages during cold boot
+* specification of the BL3-1 entrypoint requirements for use by alternative
+ Trusted Boot Firmware in place of the provided BL1 and BL2
+* changes in BL3-1 behavior when using the `RESET_TO_BL31` option which
+ allows BL3-1 to run without BL1 and BL2
+
### BL1
@@ -288,15 +301,16 @@
far as system register settings are concerned. Since BL1 code resides in ROM,
architectural initialization in BL3-1 allows override of any previous
initialization done by BL1. BL3-1 creates page tables to address the first
-4GB of physical address space and initializes the MMU accordingly. It replaces
-the exception vectors populated by BL1 with its own. BL3-1 exception vectors
-signal error conditions in the same way as BL1 does if an unexpected
-exception is raised. They implement more elaborate support for handling SMCs
-since this is the only mechanism to access the runtime services implemented by
-BL3-1 (PSCI for example). BL3-1 checks each SMC for validity as specified by
-the [SMC calling convention PDD][SMCCC] before passing control to the required
-SMC handler routine. BL3-1 programs the `CNTFRQ_EL0` register with the clock
-frequency of the system counter, which is provided by the platform.
+4GB of physical address space and initializes the MMU accordingly. It initializes
+a buffer of frequently used pointers, called per-cpu pointer cache, in memory for
+faster access. Currently the per-cpu pointer cache contains only the pointer
+to crash stack. It then replaces the exception vectors populated by BL1 with its
+own. BL3-1 exception vectors implement more elaborate support for
+handling SMCs since this is the only mechanism to access the runtime services
+implemented by BL3-1 (PSCI for example). BL3-1 checks each SMC for validity as
+specified by the [SMC calling convention PDD][SMCCC] before passing control to
+the required SMC handler routine. BL3-1 programs the `CNTFRQ_EL0` register with
+the clock frequency of the system counter, which is provided by the platform.
#### Platform initialization
@@ -367,6 +381,167 @@
by BL2 to jump to the Non-trusted firmware image (BL3-3) at the highest
available Exception Level (EL2 if available, otherwise EL1).
+
+### Using alternative Trusted Boot Firmware in place of BL1 and BL2
+
+Some platforms have existing implementations of Trusted Boot Firmware that
+would like to use ARM Trusted Firmware BL3-1 for the EL3 Runtime Firmware. To
+enable this firmware architecture it is important to provide a fully documented
+and stable interface between the Trusted Boot Firmware and BL3-1.
+
+Future changes to the BL3-1 interface will be done in a backwards compatible
+way, and this enables these firmware components to be independently enhanced/
+updated to develop and exploit new functionality.
+
+#### Required CPU state when calling `bl31_entrypoint()` during cold boot
+
+This function must only be called by the primary CPU, if this is called by any
+other CPU the firmware will abort.
+
+On entry to this function the calling primary CPU must be executing in AArch64
+EL3, little-endian data access, and all interrupt sources masked:
+
+ PSTATE.EL = 3
+ PSTATE.RW = 1
+ PSTATE.DAIF = 0xf
+ CTLR_EL3.EE = 0
+
+X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
+platform code in BL3-1:
+
+ X0 : Reserved for common Trusted Firmware information
+ X1 : Platform specific information
+
+BL3-1 zero-init sections (e.g. `.bss`) should not contain valid data on entry,
+these will be zero filled prior to invoking platform setup code.
+
+##### Use of the X0 and X1 parameters
+
+The parameters are platform specific and passed from `bl31_entrypoint()` to
+`bl31_early_platform_setup()`. The value of these parameters is never directly
+used by the common BL3-1 code.
+
+The convention is that `X0` conveys information regarding the BL3-1, BL3-2 and
+BL3-3 images from the Trusted Boot firmware and `X1` can be used for other
+platform specific purpose. This convention allows platforms which use ARM
+Trusted Firmware's BL1 and BL2 images to transfer additional platform specific
+information from Secure Boot without conflicting with future evolution of the
+Trusted Firmware using `X0` to pass a `bl31_params` structure.
+
+BL3-1 common and SPD initialization code depends on image and entrypoint
+information about BL3-3 and BL3-2, which is provided via BL3-1 platform APIs.
+This information is required until the start of execution of BL3-3. This
+information can be provided in a platform defined manner, e.g. compiled into
+the platform code in BL3-1, or provided in a platform defined memory location
+by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the
+Cold boot Initialization parameters. This data may need to be cleaned out of
+the CPU caches if it is provided by an earlier boot stage and then accessed by
+BL3-1 platform code before the caches are enabled.
+
+ARM Trusted Firmware's BL2 implementation passes a `bl31_params` structure in
+`X0` and the FVP port interprets this in the BL3-1 platform code.
+
+##### MMU, Data caches & Coherency
+
+BL3-1 does not depend on the enabled state of the MMU, data caches or
+interconnect coherency on entry to `bl31_entrypoint()`. If these are disabled
+on entry, these should be enabled during `bl31_plat_arch_setup()`.
+
+##### Data structures used in the BL3-1 cold boot interface
+
+These structures are designed to support compatibility and independent
+evolution of the structures and the firmware images. For example, a version of
+BL3-1 that can interpret the BL3-x image information from different versions of
+BL2, a platform that uses an extended entry_point_info structure to convey
+additional register information to BL3-1, or a ELF image loader that can convey
+more details about the firmware images.
+
+To support these scenarios the structures are versioned and sized, which enables
+BL3-1 to detect which information is present and respond appropriately. The
+`param_header` is defined to capture this information:
+
+ typedef struct param_header {
+ uint8_t type; /* type of the structure */
+ uint8_t version; /* version of this structure */
+ uint16_t size; /* size of this structure in bytes */
+ uint32_t attr; /* attributes: unused bits SBZ */
+ } param_header_t;
+
+The structures using this format are `entry_point_info`, `image_info` and
+`bl31_params`. The code that allocates and populates these structures must set
+the header fields appropriately, and the `SET_PARA_HEAD()` a macro is defined
+to simplify this action.
+
+#### Required CPU state for BL3-1 Warm boot initialization
+
+When requesting a CPU power-on, or suspending a running CPU, ARM Trusted
+Firmware provides the platform power management code with a Warm boot
+initialization entry-point, to be invoked by the CPU immediately after the
+reset handler. On entry to the Warm boot initialization function the calling
+CPU must be in AArch64 EL3, little-endian data access and all interrupt sources
+masked:
+
+ PSTATE.EL = 3
+ PSTATE.RW = 1
+ PSTATE.DAIF = 0xf
+ SCTLR_EL3.EE = 0
+
+The PSCI implementation will initialize the processor state and ensure that the
+platform power management code is then invoked as required to initialize all
+necessary system, cluster and CPU resources.
+
+
+### Using BL3-1 as the CPU reset vector
+
+On some platforms the runtime firmware (BL3-x images) for the application
+processors are loaded by trusted firmware running on a secure system processor
+on the SoC, rather than by BL1 and BL2 running on the primary application
+processor. For this type of SoC it is desirable for the application processor
+to always reset to BL3-1 which eliminates the need for BL1 and BL2.
+
+ARM Trusted Firmware provides a build-time option `RESET_TO_BL31` that includes
+some additional logic in the BL3-1 entrypoint to support this use case.
+
+In this configuration, the platform's Trusted Boot Firmware must ensure that
+BL3-1 is loaded to its runtime address, which must match the CPU's RVBAR reset
+vector address, before the application processor is powered on. Additionally,
+platform software is responsible for loading the other BL3-x images required and
+providing entry point information for them to BL3-1. Loading these images might
+be done by the Trusted Boot Firmware or by platform code in BL3-1.
+
+The ARM FVP port supports the `RESET_TO_BL31` configuration, in which case the
+`bl31.bin` image must be loaded to its run address in Trusted SRAM and all CPU
+reset vectors be changed from the default `0x0` to this run address. See the
+[User Guide] for details of running the FVP models in this way.
+
+This configuration requires some additions and changes in the BL3-1
+functionality:
+
+#### Determination of boot path
+
+In this configuration, BL3-1 uses the same reset framework and code as the one
+described for BL1 above. On a warm boot a CPU is directed to the PSCI
+implementation via a platform defined mechanism. On a cold boot, the platform
+must place any secondary CPUs into a safe state while the primary CPU executes
+a modified BL3-1 initialization, as described below.
+
+#### Architectural initialization
+
+As the first image to execute in this configuration BL3-1 must ensure that
+interconnect coherency is enabled (if required) before enabling the MMU.
+
+#### Platform initialization
+
+In this configuration, when the CPU resets to BL3-1 there are no parameters
+that can be passed in registers by previous boot stages. Instead, the platform
+code in BL3-1 needs to know, or be able to determine, the location of the BL3-2
+(if required) and BL3-3 images and provide this information in response to the
+`bl31_plat_get_next_image_ep_info()` function.
+
+As the first image to execute in this configuration BL3-1 must also ensure that
+any security initialisation, for example programming a TrustZone address space
+controller, is carried out during early platform initialisation.
+
3. EL3 runtime services framework
----------------------------------
@@ -613,16 +788,13 @@
The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
the BL3-2 image. It needs access to the information passed by BL2 to BL3-1 to do
-so. Hence BL3-1 implements:
+so. This is provided by:
-1. `bl31_plat_get_bl32_mem_layout()` to return the extents of memory
- available for BL3-2's use as communicated by BL2.
+ entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t);
-2. `bl31_get_next_image_info(uint32_t security_state)` to return a reference
- to the `el_change_info` structure corresponding to the next image which will
- be run in the specified security state. The SPD uses this api with the
- secure security state as the parameter to get entry related information about
- BL3-2.
+which returns a reference to the `entry_point_info` structure corresponding to
+the image which will be run in the specified security state. The SPD uses this
+API to get entry point information for the SECURE image, BL3-2.
In the absence of a BL3-2 image, BL3-1 passes control to the normal world
bootloader image (BL3-3). When the BL3-2 image is present, it is typical
@@ -632,7 +804,7 @@
initialization of the SPD service. The BL3-2 initialization function has this
prototype:
- int32_t init(meminfo *bl32_meminfo);
+ int32_t init();
and is registered using the `bl31_register_bl32_init()` function.
@@ -664,8 +836,102 @@
`bl31_main()` will set up the return to the normal world firmware BL3-3 and
continue the boot process in the normal world.
+6. Crash Reporting in BL3-1
+----------------------------------
+
+The BL3-1 implements a scheme for reporting the processor state when an unhandled
+exception is encountered. The reporting mechanism attempts to preserve all the
+register contents and report it via the default serial output. The general purpose
+registers, EL3, Secure EL1 and some EL2 state registers are reported.
+
+A dedicated per-cpu crash stack is maintained by BL3-1 and this is retrieved via
+the per-cpu pointer cache. The implementation attempts to minimise the memory
+required for this feature. The file `crash_reporting.S` contains the
+implementation for crash reporting.
+
+The sample crash output is shown below.
+
+ x0 :0x000000004F00007C
+ x1 :0x0000000007FFFFFF
+ x2 :0x0000000004014D50
+ x3 :0x0000000000000000
+ x4 :0x0000000088007998
+ x5 :0x00000000001343AC
+ x6 :0x0000000000000016
+ x7 :0x00000000000B8A38
+ x8 :0x00000000001343AC
+ x9 :0x00000000000101A8
+ x10 :0x0000000000000002
+ x11 :0x000000000000011C
+ x12 :0x00000000FEFDC644
+ x13 :0x00000000FED93FFC
+ x14 :0x0000000000247950
+ x15 :0x00000000000007A2
+ x16 :0x00000000000007A4
+ x17 :0x0000000000247950
+ x18 :0x0000000000000000
+ x19 :0x00000000FFFFFFFF
+ x20 :0x0000000004014D50
+ x21 :0x000000000400A38C
+ x22 :0x0000000000247950
+ x23 :0x0000000000000010
+ x24 :0x0000000000000024
+ x25 :0x00000000FEFDC868
+ x26 :0x00000000FEFDC86A
+ x27 :0x00000000019EDEDC
+ x28 :0x000000000A7CFDAA
+ x29 :0x0000000004010780
+ x30 :0x000000000400F004
+ scr_el3 :0x0000000000000D3D
+ sctlr_el3 :0x0000000000C8181F
+ cptr_el3 :0x0000000000000000
+ tcr_el3 :0x0000000080803520
+ daif :0x00000000000003C0
+ mair_el3 :0x00000000000004FF
+ spsr_el3 :0x00000000800003CC
+ elr_el3 :0x000000000400C0CC
+ ttbr0_el3 :0x00000000040172A0
+ esr_el3 :0x0000000096000210
+ sp_el3 :0x0000000004014D50
+ far_el3 :0x000000004F00007C
+ spsr_el1 :0x0000000000000000
+ elr_el1 :0x0000000000000000
+ spsr_abt :0x0000000000000000
+ spsr_und :0x0000000000000000
+ spsr_irq :0x0000000000000000
+ spsr_fiq :0x0000000000000000
+ sctlr_el1 :0x0000000030C81807
+ actlr_el1 :0x0000000000000000
+ cpacr_el1 :0x0000000000300000
+ csselr_el1 :0x0000000000000002
+ sp_el1 :0x0000000004028800
+ esr_el1 :0x0000000000000000
+ ttbr0_el1 :0x000000000402C200
+ ttbr1_el1 :0x0000000000000000
+ mair_el1 :0x00000000000004FF
+ amair_el1 :0x0000000000000000
+ tcr_el1 :0x0000000000003520
+ tpidr_el1 :0x0000000000000000
+ tpidr_el0 :0x0000000000000000
+ tpidrro_el0 :0x0000000000000000
+ dacr32_el2 :0x0000000000000000
+ ifsr32_el2 :0x0000000000000000
+ par_el1 :0x0000000000000000
+ far_el1 :0x0000000000000000
+ afsr0_el1 :0x0000000000000000
+ afsr1_el1 :0x0000000000000000
+ contextidr_el1 :0x0000000000000000
+ vbar_el1 :0x0000000004027000
+ cntp_ctl_el0 :0x0000000000000000
+ cntp_cval_el0 :0x0000000000000000
+ cntv_ctl_el0 :0x0000000000000000
+ cntv_cval_el0 :0x0000000000000000
+ cntkctl_el1 :0x0000000000000000
+ fpexc32_el2 :0x0000000004000700
+ sp_el0 :0x0000000004010780
+
-6. Memory layout on FVP platforms
+7. Memory layout on FVP platforms
----------------------------------
On FVP platforms, we use the Trusted ROM and Trusted SRAM to store the trusted
@@ -906,7 +1172,7 @@
------------ 0x04000000
-7. Firmware Image Package (FIP)
+8. Firmware Image Package (FIP)
--------------------------------
Using a Firmware Image Package (FIP) allows for packing bootloader images (and
@@ -984,7 +1250,7 @@
platform policy can be modified to allow additional images.
-8. Code Structure
+9. Code Structure
------------------
Trusted Firmware code is logically divided between the three boot loader
@@ -1024,7 +1290,7 @@
kernel at boot time. These can be found in the `fdts` directory.
-9. References
+10. References
--------------
1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
@@ -1034,6 +1300,7 @@
3. [SMC Calling Convention PDD (ARM DEN 0028A)][SMCCC].
+4. [ARM Trusted Firmware Interrupt Management Design guide][INTRG].
- - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -1044,3 +1311,5 @@
[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)"
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
+[User Guide]: ./user-guide.md
+[INTRG]: ./interrupt-framework-design.md
diff --git a/docs/interrupt-framework-design.md b/docs/interrupt-framework-design.md
new file mode 100644
index 0000000..f96f764
--- /dev/null
+++ b/docs/interrupt-framework-design.md
@@ -0,0 +1,848 @@
+ARM Trusted Firmware Interrupt Management Design guide
+======================================================
+
+Contents :
+
+1. Introduction
+ * Assumptions
+ * Concepts
+ - Interrupt Types
+ - Routing Model
+ - Valid Routing Models
+ + Secure-EL1 Interrupts
+ + Non-secure Interrupts
+ - Mapping of Interrupt Type to Signal
+
+2. Interrupt Management
+ * Software Components
+ * Interrupt Registration
+ - EL3 Runtime Firmware
+ - Secure Payload Dispatcher
+ + Test Secure Payload Dispatcher behavior
+ - Secure Payload
+ + Secure Payload IHF design w.r.t Secure-EL1 interrupts
+ + Secure Payload IHF design w.r.t Non-secure interrupts
+ + Test Secure Payload behavior
+ * Interrupt Handling
+ - EL3 Runtime Firmware
+ - Secure Payload Dispatcher
+ + Interrupt Entry
+ + Interrupt Exit
+ + Test Secure Payload Dispatcher behavior
+ - Secure Payload
+ + Test Secure Payload behavior
+
+
+1. Introduction
+----------------
+This document describes the design of the Interrupt management framework in ARM
+Trusted Firmware. This section briefly describes the requirements from this
+framework. It also briefly explains some concepts and assumptions. They will
+help in understanding the implementation of the framework explained in
+subsequent sections.
+
+This framework is responsible for managing interrupts routed to EL3. It also
+allows EL3 software to configure the interrupt routing behavior. Its main
+objective is to implement the following two requirements.
+
+1. It should be possible to route interrupts meant to be handled by secure
+ software (Secure interrupts) to EL3, when execution is in non-secure state
+ (normal world). The framework should then take care of handing control of
+ the interrupt to either software in EL3 or Secure-EL1 depending upon the
+ software configuration and the GIC implementation. This requirement ensures
+ that secure interrupts are under the control of the secure software with
+ respect to their delivery and handling without the possibility of
+ intervention from non-secure software.
+
+2. It should be possible to route interrupts meant to be handled by
+ non-secure software (Non-secure interrupts) to the last executed exception
+ level in the normal world when the execution is in secure world at
+ exception levels lower than EL3. This could be done with or without the
+ knowledge of software executing in Secure-EL1/Secure-EL0. The choice of
+ approach should be governed by the secure software. This requirement
+ ensures that non-secure software is able to execute in tandem with the
+ secure software without overriding it.
+
+### 1.1 Assumptions
+The framework makes the following assumptions to simplify its implementation.
+
+1. All secure interrupts are handled in Secure-EL1. They can be delivered to
+ Secure-EL1 via EL3 but they cannot be handled in EL3. It will be possible
+ to extend the framework to handle secure interrupts in EL3 in the future.
+
+2. Interrupt exceptions (`PSTATE.I` and `F` bits) are masked during execution
+ in EL3.
+
+### 1.2 Concepts
+
+#### 1.2.1 Interrupt types
+The framework categorises an interrupt to be one of the following depending upon
+the exception level(s) it is handled in.
+
+1. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or
+ Secure-EL1 depending upon the security state of the current execution
+ context. It is always handled in Secure-EL1.
+
+2. Non-secure interrupt. This type of interrupt can be routed to EL3,
+ Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the
+ current execution context. It is always handled in either Non-secure EL1
+ or EL2.
+
+3. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1
+ depending upon the security state of the current execution context. It is
+ always handled in EL3.
+
+In the current implementation of the framework, all secure interrupts are
+treated as Secure EL1 interrupts. It will be possible for EL3 software to
+configure a secure interrupt as an EL3 interrupt in future implementations. The
+following constants define the various interrupt types in the framework
+implementation.
+
+ #define INTR_TYPE_S_EL1 0
+ #define INTR_TYPE_EL3 1
+ #define INTR_TYPE_NS 2
+
+
+#### 1.2.2 Routing model
+A type of interrupt can be either generated as an FIQ or an IRQ. The target
+exception level of an interrupt type is configured through the FIQ and IRQ bits
+in the Secure Configuration Register at EL3 (`SCR_EL3.FIQ` and `SCR_EL3.IRQ`
+bits). When `SCR_EL3.FIQ`=1, FIQs are routed to EL3. Otherwise they are routed
+to the First Exception Level (FEL) capable of handling interrupts. When
+`SCR_EL3.IRQ`=1, IRQs are routed to EL3. Otherwise they are routed to the
+FEL. This register is configured independently by EL3 software for each security
+state prior to entry into a lower exception level in that security state.
+
+A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as
+its target exception level for each security state. It is represented by a
+single bit for each security state. A value of `0` means that the interrupt
+should be routed to the FEL. A value of `1` means that the interrupt should be
+routed to EL3. A routing model is applicable only when execution is not in EL3.
+
+The default routing model for an interrupt type is to route it to the FEL in
+either security state.
+
+#### 1.2.3 Valid routing models
+The framework considers certain routing models for each type of interrupt to be
+incorrect as they conflict with the requirements mentioned in Section 1. The
+following sub-sections describe all the possible routing models and specify
+which ones are valid or invalid. Only the Secure-EL1 and Non-secure interrupt
+types are considered as EL3 interrupts are currently unsupported (See 1.1). The
+terminology used in the following sub-sections is explained below.
+
+1. __CSS__. Current Security State. `0` when secure and `1` when non-secure
+
+2. __TEL3__. Target Exception Level 3. `0` when targeted to the FEL. `1` when
+ targeted to EL3.
+
+
+##### 1.2.3.1 Secure-EL1 interrupts
+
+1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in
+ secure state. This is a valid routing model as secure software is in
+ control of handling secure interrupts.
+
+2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
+ state. This is a valid routing model as secure software in EL3 can
+ handover the interrupt to Secure-EL1 for handling.
+
+3. __CSS=1, TEL3=0__. Interrupt is routed to the FEL when execution is in
+ non-secure state. This is an invalid routing model as a secure interrupt
+ is not visible to the secure software which violates the motivation behind
+ the ARM Security Extensions.
+
+4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
+ state. This is a valid routing model as secure software in EL3 can
+ handover the interrupt to Secure-EL1 for handling.
+
+
+##### 1.2.3.2 Non-secure interrupts
+
+1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in
+ secure state. This allows the secure software to trap non-secure
+ interrupts, perform its bookeeping and hand the interrupt to the
+ non-secure software through EL3. This is a valid routing model as secure
+ software is in control of how its execution is pre-empted by non-secure
+ interrupts.
+
+2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
+ state. This is a valid routing model as secure software in EL3 can save
+ the state of software in Secure-EL1/Secure-EL0 before handing the
+ interrupt to non-secure software. This model requires additional
+ coordination between Secure-EL1 and EL3 software to ensure that the
+ former's state is correctly saved by the latter.
+
+3. __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
+ is handled by non-secure software.
+
+4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in
+ non-secure state. This is an invalid routing model as there is no valid
+ reason to route the interrupt to EL3 software and then hand it back to
+ non-secure software for handling.
+
+
+#### 1.2.4 Mapping of interrupt type to signal
+The framework is meant to work with any interrupt controller implemented by a
+platform. A interrupt controller could generate a type of interrupt as either an
+FIQ or IRQ signal to the CPU depending upon the current security state.The
+mapping between the type and signal is known only to the platform. The framework
+uses this information to determine whether the IRQ or the FIQ bit should be
+programmed in `SCR_EL3` while applying the routing model for a type of
+interrupt. The platform provides this information through the
+`plat_interrupt_type_to_line()` API (described in the [Porting
+Guide]). For example, on the FVP port when the platform uses an ARM GICv2
+interrupt controller, Secure-EL1 interrupts are signalled through the FIQ signal
+while Non-secure interrupts are signalled through the IRQ signal. This applies
+when execution is in either security state.
+
+
+2. Interrupt management
+-----------------------
+The following sections describe how interrupts are managed by the interrupt
+handling framework. This entails:
+
+1. Providing an interface to allow registration of a handler and specification
+ of the routing model for a type of interrupt.
+
+2. 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
+in the section 2.1. The framework stores information associated with each type
+of interrupt in the following data structure.
+
+```
+typedef struct intr_type_desc {
+ interrupt_type_handler_t handler;
+ uint32_t flags;
+ uint32_t scr_el3[2];
+} intr_type_desc_t;
+```
+
+The `flags` field stores the routing model for the interrupt type in
+bits[1:0]. Bit[0] stores the routing model when execution is in the secure
+state. Bit[1] stores the routing model when execution is in the non-secure
+state. As mentioned in Section 1.2.2, a value of `0` implies that the interrupt
+should be targeted to the FEL. A value of `1` implies that it should be targeted
+to EL3. The remaining bits are reserved and SBZ. The helper macro
+`set_interrupt_rm_flag()` should be used to set the bits in the `flags`
+parameter.
+
+The `scr_el3[2]` field also stores the routing model but as a mapping of the
+model in the `flags` field to the corresponding bit in the `SCR_EL3` for each
+security state.
+
+The framework also depends upon the platform port to configure the interrupt
+controller to distinguish between secure and non-secure interrupts. The platform
+is expected to be aware of the secure devices present in the system and their
+associated interrupt numbers. It should configure the interrupt controller to
+enable the secure interrupts, ensure that their priority is always higher than
+the non-secure interrupts and target them to the primary CPU. It should also
+export the interface described in the the [Porting Guide][PRTG] to enable
+handling of interrupts.
+
+In the remainder of this document, for the sake of simplicity it is assumed that
+the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal is
+used to generate non-secure interrupts in either security state.
+
+### 2.1 Software components
+Roles and responsibilities for interrupt management are sub-divided between the
+following components of software running in EL3 and Secure-EL1. Each component is
+briefly described below.
+
+1. EL3 Runtime Firmware. This component is common to all ports of the ARM
+ Trusted Firmware.
+
+2. Secure Payload Dispatcher (SPD) service. This service interfaces with the
+ Secure Payload (SP) software which runs in exception levels lower than EL3
+ i.e. Secure-EL1/Secure-EL0. It is responsible for switching execution
+ between software running in secure and non-secure states at exception
+ levels lower than EL3. A switch is triggered by a Secure Monitor Call from
+ either state. It uses the APIs exported by the Context management library
+ to implement this functionality. Switching execution between the two
+ security states is a requirement for interrupt management as well. This
+ results in a significant dependency on the SPD service. ARM Trusted
+ firmware implements an example Test Secure Payload Dispatcher (TSPD)
+ service.
+
+ An SPD service plugs into the EL3 runtime firmware and could be common to
+ some ports of the ARM Trusted Firmware.
+
+3. Secure Payload (SP). On a production system, the Secure Payload corresponds
+ to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
+ SPD service to manage communication with non-secure software. ARM Trusted
+ Firmware implements an example secure payload called Test Secure Payload
+ (TSP) which runs only in Secure-EL1.
+
+ A Secure payload implementation could be common to some ports of the ARM
+ Trusted Firmware just like the SPD service.
+
+
+### 2.2 Interrupt registration
+This section describes in detail the role of each software component (see 2.1)
+during the registration of a handler for an interrupt type.
+
+
+#### 2.2.1 EL3 runtime firmware
+This component declares the following prototype for a handler of an interrupt type.
+
+ typedef uint64_t (*interrupt_type_handler_t)(uint32_t id,
+ uint32_t flags,
+ void *handle,
+ void *cookie);
+
+The value of the `id` parameter depends upon the definition of the
+`IMF_READ_INTERRUPT_ID` build time flag. When the flag is defined, `id` contains
+the number of the highest priority pending interrupt of the type that this
+handler was registered for. When the flag is not defined `id` contains
+`INTR_ID_UNAVAILABLE`.
+
+The `flags` parameter contains miscellaneous information as follows.
+
+1. Security state, bit[0]. This bit indicates the security state of the lower
+ exception level when the interrupt was generated. A value of `1` means
+ that it was in the non-secure state. A value of `0` indicates that it was
+ in the secure state. This bit can be used by the handler to ensure that
+ interrupt was generated and routed as per the routing model specified
+ during registration.
+
+2. Reserved, bits[31:1]. The remaining bits are reserved for future use.
+
+The `handle` parameter points to the `cpu_context` structure of the current CPU
+for the security state specified in the `flags` parameter.
+
+Once the handler routine completes, execution will return to either the secure
+or non-secure state. The handler routine should return a pointer to
+`cpu_context` structure of the current CPU for the the target security state. It
+should treat all error conditions as critical errors and take appropriate action
+within its implementation e.g. use assertion failures.
+
+The runtime firmware provides the following API for registering a handler for a
+particular type of interrupt. A Secure Payload Dispatcher service should use
+this API to register a handler for Secure-EL1 and optionally for non-secure
+interrupts. This API also requires the caller to specify the routing model for
+the type of interrupt.
+
+ int32_t register_interrupt_type_handler(uint32_t type,
+ interrupt_type_handler handler,
+ uint64_t flags);
+
+
+The `type` parameter can be one of the three interrupt types listed above i.e.
+`INTR_TYPE_S_EL1`, `INTR_TYPE_NS` & `INTR_TYPE_EL3` (currently unimplemented).
+The `flags` parameter is as described in Section 2.
+
+The function will return `0` upon a successful registration. It will return
+`-EALREADY` in case a handler for the interrupt type has already been
+registered. If the `type` is unrecognised or the `flags` or the `handler` are
+invalid it will return `-EINVAL`. It will return `-ENOTSUP` if the specified
+`type` is not supported by the framework i.e. `INTR_TYPE_EL3`.
+
+Interrupt routing is governed by the configuration of the `SCR_EL3.FIQ/IRQ` bits
+prior to entry into a lower exception level in either security state. The
+context management library maintains a copy of the `SCR_EL3` system register for
+each security state in the `cpu_context` structure of each CPU. It exports the
+following APIs to let EL3 Runtime Firmware program and retrieve the routing
+model for each security state for the current CPU. The value of `SCR_EL3` stored
+in the `cpu_context` is used by the `el3_exit()` function to program the
+`SCR_EL3` register prior to returning from the EL3 exception level.
+
+ uint32_t cm_get_scr_el3(uint32_t security_state);
+ void cm_write_scr_el3_bit(uint32_t security_state,
+ uint32_t bit_pos,
+ uint32_t value);
+
+`cm_get_scr_el3()` returns the value of the `SCR_EL3` register for the specified
+security state of the current CPU. `cm_write_scr_el3()` writes a `0` or `1` to
+the bit specified by `bit_pos`. `register_interrupt_type_handler()` invokes
+`set_routing_model()` API which programs the `SCR_EL3` according to the routing
+model using the `cm_get_scr_el3()` and `cm_write_scr_el3_bit()` APIs.
+
+It is worth noting that in the current implementation of the framework, the EL3
+runtime firmware is responsible for programming the routing model. The SPD is
+responsible for ensuring that the routing model has been adhered to upon
+receiving an interrupt.
+
+#### 2.2.2 Secure payload dispatcher
+A SPD service is responsible for determining and maintaining the interrupt
+routing model supported by itself and the Secure Payload. It is also responsible
+for ferrying interrupts between secure and non-secure software depending upon
+the routing model. It could determine the routing model at build time or at
+runtime. It must use this information to register a handler for each interrupt
+type using the `register_interrupt_type_handler()` API in EL3 runtime firmware.
+
+If the routing model is not known to the SPD service at build time, then it must
+be provided by the SP as the result of its initialisation. The SPD should
+program the routing model only after SP initialisation has completed e.g. in the
+SPD initialisation function pointed to by the `bl32_init` variable.
+
+The SPD should determine the mechanism to pass control to the Secure Payload
+after receiving an interrupt from the EL3 runtime firmware. This information
+could either be provided to the SPD service at build time or by the SP at
+runtime.
+
+#### 2.2.2.1 Test secure payload dispatcher behavior
+The TSPD only handles Secure-EL1 interrupts and is provided with the following
+routing model at build time.
+
+* Secure-EL1 interrupts are routed to EL3 when execution is in non-secure
+ state and are routed to the FEL when execution is in the secure state
+ i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=1__ for Secure-EL1 interrupts
+
+* The default routing model is used for non-secure interrupts i.e they are
+ routed to the FEL in either security state i.e __CSS=0, TEL3=0__ &
+ __CSS=1, TEL3=0__ for Non-secure interrupts
+
+It performs the following actions in the `tspd_init()` function to fulfill the
+requirements mentioned earlier.
+
+1. It passes control to the Test Secure Payload to perform its
+ initialisation. The TSP provides the address of the vector table
+ `tsp_vectors` in the SP which also includes the handler for Secure-EL1
+ interrupts in the `fiq_entry` field. The TSPD passes control to the TSP at
+ this address when it receives a Secure-EL1 interrupt.
+
+ The handover agreement between the TSP and the TSPD requires that the TSPD
+ masks all interrupts (`PSTATE.DAIF` bits) when it calls
+ `tsp_fiq_entry()`. The TSP has to preserve the callee saved general
+ purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use
+ `x0-x18` to enable its C runtime.
+
+2. The TSPD implements a handler function for Secure-EL1 interrupts. It
+ registers it with the EL3 runtime firmware using the
+ `register_interrupt_type_handler()` API as follows
+
+ /* Forward declaration */
+ interrupt_type_handler tspd_secure_el1_interrupt_handler;
+ int32_t rc, flags = 0;
+ set_interrupt_rm_flag(flags, NON_SECURE);
+ rc = register_interrupt_type_handler(INTR_TYPE_S_EL1,
+ tspd_secure_el1_interrupt_handler,
+ flags);
+ assert(rc == 0);
+
+#### 2.2.3 Secure payload
+A Secure Payload must implement an interrupt handling framework at Secure-EL1
+(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload
+execution will alternate between the below cases.
+
+1. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt
+ type is targeted to the FEL, then it will be routed to the Secure-EL1
+ exception vector table. This is defined as the asynchronous model of
+ handling interrupts. This mode applies to both Secure-EL1 and non-secure
+ interrupts.
+
+2. In the code where both interrupts are disabled, if an interrupt type is
+ targeted to the FEL, then execution will eventually migrate to the
+ non-secure state. Any non-secure interrupts will be handled as described
+ in the routing model where __CSS=1 and TEL3=0__. Secure-EL1 interrupts
+ will be routed to EL3 (as per the routing model where __CSS=1 and
+ TEL3=1__) where the SPD service will hand them to the SP. This is defined
+ as the synchronous mode of handling interrupts.
+
+The interrupt handling framework implemented by the SP should support one or
+both these interrupt handling models depending upon the chosen routing model.
+
+The following list briefly describes how the choice of a valid routing model
+(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of
+the interrupt routing model is not known to the SPD service at compile time,
+then the SP should pass this information to the SPD service at runtime during
+its initialisation phase.
+
+As mentioned earlier, it is assumed that the FIQ signal is used to generate
+Secure-EL1 interrupts and the IRQ signal is used to generate non-secure
+interrupts in either security state.
+
+##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts
+1. __CSS=0, TEL3=0__. If `PSTATE.F=0`, Secure-EL1 interrupts will be
+ trigerred at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1
+ IHF should implement support for handling FIQ interrupts asynchronously.
+
+ If `PSTATE.F=1` then Secure-EL1 interrupts will be handled as per the
+ synchronous interrupt handling model. The SP could implement this scenario
+ by exporting a seperate entrypoint for Secure-EL1 interrupts to the SPD
+ service during the registration phase. The SPD service would also need to
+ know the state of the system, general purpose and the `PSTATE` registers
+ in which it should arrange to return execution to the SP. The SP should
+ provide this information in an implementation defined way during the
+ registration phase if it is not known to the SPD service at build time.
+
+2. __CSS=1, TEL3=1__. Interrupts are routed to EL3 when execution is in
+ non-secure state. They should be handled through the synchronous interrupt
+ handling model as described in 1. above.
+
+3. __CSS=0, TEL3=1__. Secure interrupts are routed to EL3 when execution is in
+ secure state. They will not be visible to the SP. The `PSTATE.F` bit in
+ Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will
+ call the handler registered by the SPD service for Secure-EL1
+ interrupts. Secure-EL1 IHF should then handle all Secure-EL1 interrupt
+ through the synchronous interrupt handling model described in 1. above.
+
+
+##### 2.2.3.2 Secure payload IHF design w.r.t non-secure interrupts
+1. __CSS=0, TEL3=0__. If `PSTATE.I=0`, non-secure interrupts will be
+ trigerred at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1
+ IHF should co-ordinate with the SPD service to transfer execution to the
+ non-secure state where the interrupt should be handled e.g the SP could
+ allocate a function identifier to issue a SMC64 or SMC32 to the SPD
+ service which indicates that the SP execution has been pre-empted by a
+ non-secure interrupt. If this function identifier is not known to the SPD
+ service at compile time then the SP could provide it during the
+ registration phase.
+
+ If `PSTATE.I=1` then the non-secure interrupt will pend until execution
+ resumes in the non-secure state.
+
+2. __CSS=0, TEL3=1__. Non-secure interrupts are routed to EL3. They will not
+ be visible to the SP. The `PSTATE.I` bit in Secure-EL1/Secure-EL0 will
+ have not effect. The SPD service should register a non-secure interrupt
+ handler which should save the SP state correctly and resume execution in
+ the non-secure state where the interrupt will be handled. The Secure-EL1
+ IHF does not need to take any action.
+
+3. __CSS=1, TEL3=0__. Non-secure interrupts are handled in the FEL in
+ non-secure state (EL1/EL2) and are not visible to the SP. This routing
+ model does not affect the SP behavior.
+
+
+A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly
+configured at the interrupt controller by the platform port of the EL3 runtime
+firmware. It should configure any additional Secure-EL1 interrupts which the EL3
+runtime firmware is not aware of through its platform port.
+
+#### 2.2.3.3 Test secure payload behavior
+The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is
+described in Section 2.2.2. It is known to the TSPD service at build time.
+
+The TSP implements an entrypoint (`tsp_fiq_entry()`) for handling Secure-EL1
+interrupts taken in non-secure state and routed through the TSPD service
+(synchronous handling model). It passes the reference to this entrypoint via
+`tsp_vectors` to the TSPD service.
+
+The TSP also replaces the default exception vector table referenced through the
+`early_exceptions` variable, with a vector table capable of handling FIQ and IRQ
+exceptions taken at the same (Secure-EL1) exception level. This table is
+referenced through the `tsp_exceptions` variable and programmed into the
+VBAR_EL1. It caters for the asynchronous handling model.
+
+The TSP also programs the Secure Physical Timer in the ARM Generic Timer block
+to raise a periodic interrupt (every half a second) for the purpose of testing
+interrupt management across all the software components listed in 2.1
+
+
+### 2.3 Interrupt handling
+This section describes in detail the role of each software component (see
+Section 2.1) in handling an interrupt of a particular type.
+
+#### 2.3.1 EL3 runtime firmware
+The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced
+by the `runtime_exceptions` variable as follows.
+
+1. IRQ and FIQ exceptions taken from the current exception level with
+ `SP_EL0` or `SP_EL3` are reported as irrecoverable error conditions. As
+ mentioned earlier, EL3 runtime firmware always executes with the
+ `PSTATE.I` and `PSTATE.F` bits set.
+
+2. The following text describes how the IRQ and FIQ exceptions taken from a
+ lower exception level using AArch64 or AArch32 are handled.
+
+When an interrupt is generated, the vector for each interrupt type is
+responsible for:
+
+1. Saving the entire general purpose register context (x0-x30) immediately
+ upon exception entry. The registers are saved in the per-cpu `cpu_context`
+ data structure referenced by the `SP_EL3`register.
+
+2. Saving the `ELR_EL3`, `SP_EL0` and `SPSR_EL3` system registers in the
+ per-cpu `cpu_context` data structure referenced by the `SP_EL3` register.
+
+3. Switching to the C runtime stack by restoring the `CTX_RUNTIME_SP` value
+ from the per-cpu `cpu_context` data structure in `SP_EL0` and
+ executing the `msr spsel, #0` instruction.
+
+4. Determining the type of interrupt. Secure-EL1 interrupts will be signalled
+ at the FIQ vector. Non-secure interrupts will be signalled at the IRQ
+ vector. The platform should implement the following API to determine the
+ type of the pending interrupt.
+
+ uint32_t plat_ic_get_interrupt_type(void);
+
+ It should return either `INTR_TYPE_S_EL1` or `INTR_TYPE_NS`.
+
+5. Determining the handler for the type of interrupt that has been generated.
+ The following API has been added for this purpose.
+
+ interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type);
+
+ It returns the reference to the registered handler for this interrupt
+ type. The `handler` is retrieved from the `intr_type_desc_t` structure as
+ described in Section 2. `NULL` is returned if no handler has been
+ registered for this type of interrupt. This scenario is reported as an
+ irrecoverable error condition.
+
+6. Calling the registered handler function for the interrupt type generated.
+ The firmware also determines the interrupt id if the IMF_READ_INTERRUPT_ID
+ build time flag is set. The id is set to `INTR_ID_UNAVAILABLE` if the flag
+ is not set. The id along with the current security state and a reference to
+ the `cpu_context_t` structure for the current security state are passed to
+ the handler function as its arguments.
+
+ The handler function returns a reference to the per-cpu `cpu_context_t`
+ structure for the target security state.
+
+7. Calling `el3_exit()` to return from EL3 into a lower exception level in
+ the security state determined by the handler routine. The `el3_exit()`
+ function is responsible for restoring the register context from the
+ `cpu_context_t` data structure for the target security state.
+
+
+#### 2.3.2 Secure payload dispatcher
+
+##### 2.3.2.1 Interrupt entry
+The SPD service begins handling an interrupt when the EL3 runtime firmware calls
+the handler function for that type of interrupt. The SPD service is responsible
+for the following:
+
+1. Validating the interrupt. This involves ensuring that the interrupt was
+ generating according to the interrupt routing model specified by the SPD
+ service during registration. It should use the interrupt id and 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
+ interrupts. The following text describes further error scenarios keeping
+ this in mind:
+
+ 1. __SPD service has registered a handler for Non-secure interrupts__:
+ When an interrupt is received by the handler, it could check its id
+ to ensure it has been configured as a non-secure interrupt at the
+ interrupt controller. A secure interrupt should never be handed to
+ the non-secure interrupt handler. A non-secure interrupt should
+ never be routed to EL3 when execution is in non-secure state. The
+ handler could check the security state flag to ensure this.
+
+ 2. __SPD service has registered a handler for Secure-EL1 interrupts__:
+ When an interrupt is received by the handler, it could check its id
+ to ensure it has been configured as a secure interrupt at the
+ interrupt controller. A non-secure interrupt should never be handed
+ to the secure interrupt handler. If the routing model chosen is such
+ that Secure-EL1 interrupts are not routed to EL3 when execution is
+ in non-secure state, then a Secure-EL1 interrupt generated in the
+ secure state would be invalid. The handler could use the security
+ state flag to check this.
+
+ The SPD service should use the platform API:
+ `plat_ic_get_interrupt_type()` to determine the type of interrupt for the
+ specified id.
+
+2. Determining whether the security state of the exception level for handling
+ the interrupt is the same as the security state of the exception level
+ where the interrupt was generated. This depends upon the routing model and
+ type of the interrupt. The SPD should use this information to determine if
+ a context switch is required. The following two cases would require a
+ context switch from secure to non-secure or vice-versa.
+
+ 1. A Secure-EL1 interrupt taken from the non-secure state should be
+ routed to the Secure Payload.
+
+ 2. A non-secure interrupt taken from the secure state should be routed
+ to the last known non-secure exception level.
+
+ The SPD service must save the system register context of the current
+ security state. It must then restore the system register context of the
+ target security state. It should use the `cm_set_next_eret_context()` API
+ to ensure that the next `cpu_context` to be restored is of the target
+ security state.
+
+ If the target state is secure then execution should be handed to the SP as
+ per the synchronous interrupt handling model it implements. A Secure-EL1
+ interrupt can be routed to EL3 while execution is in the SP. This implies
+ that SP execution can be preempted while handling an interrupt by a
+ another higher priority Secure-EL1 interrupt (or a EL3 interrupt in the
+ future). The SPD service should manage secure interrupt priorities before
+ handing control to the SP to prevent this type of preemption which can
+ leave the system in an inconsistent state.
+
+3. Setting the return value of the handler to the per-cpu `cpu_context` if
+ the interrupt has been successfully validated and ready to be handled at a
+ lower exception level.
+
+The routing model allows non-secure interrupts to be taken to Secure-EL1 when in
+secure state. The SPD service and the SP should implement a mechanism for
+routing these interrupts to the last known exception level in the non-secure
+state. The former should save the SP context, restore the non-secure context and
+arrange for entry into the non-secure state so that the interrupt can be
+handled.
+
+##### 2.3.2.2 Interrupt exit
+When the Secure Payload has finished handling a Secure-EL1 interrupt, it could
+return control back to the SPD service through a SMC32 or SMC64. The SPD service
+should handle this secure monitor call so that execution resumes in the
+exception level and the security state from where the Secure-EL1 interrupt was
+originally taken.
+
+##### 2.3.2.1 Test secure payload dispatcher behavior
+The example TSPD service registers a handler for Secure-EL1 interrupts taken
+from the non-secure state. Its handler `tspd_secure_el1_interrupt_handler()`
+takes the following actions upon being invoked.
+
+1. It uses the `id` parameter to query the interrupt controller to ensure
+ that the interrupt is a Secure-EL1 interrupt. It asserts if this is not
+ the case.
+
+2. It uses the security state provided in the `flags` parameter to ensure
+ that the secure interrupt originated from the non-secure state. It asserts
+ if this is not the case.
+
+3. It saves the system register context for the non-secure state by calling
+ `cm_el1_sysregs_context_save(NON_SECURE);`.
+
+4. It sets the `ELR_EL3` system register to `tsp_fiq_entry` and sets the
+ `SPSR_EL3.DAIF` bits in the secure CPU context. It sets `x0` to
+ `TSP_HANDLE_FIQ_AND_RETURN`. If the TSP was in the middle of handling a
+ standard SMC, then the `ELR_EL3` and `SPSR_EL3` registers in the secure CPU
+ context are saved first.
+
+5. It restores the system register context for the secure state by calling
+ `cm_el1_sysregs_context_restore(SECURE);`.
+
+6. It ensures that the secure CPU context is used to program the next
+ exception return from EL3 by calling `cm_set_next_eret_context(SECURE);`.
+
+7. It returns the per-cpu `cpu_context` to indicate that the interrupt can
+ now be handled by the SP. `x1` is written with the value of `elr_el3`
+ register for the non-secure state. This information is used by the SP for
+ debugging purposes.
+
+The figure below describes how the interrupt handling is implemented by the TSPD
+when a Secure-EL1 interrupt is generated when execution is in the non-secure
+state.
+
+
+
+The TSP issues an SMC with `TSP_HANDLED_S_EL1_FIQ` as the function identifier to
+signal completion of interrupt handling.
+
+The TSP issues an SMC with `TSP_PREEMPTED` as the function identifier to signal
+generation of a non-secure interrupt in Secure-EL1.
+
+The TSPD service takes the following actions in `tspd_smc_handler()` function
+upon receiving an SMC with `TSP_HANDLED_S_EL1_FIQ` and `TSP_PREEMPTED` as the
+function identifiers:
+
+1. It ensures that the call originated from the secure state otherwise
+ execution returns to the non-secure state with `SMC_UNK` in `x0`.
+
+2. If the function identifier is `TSP_HANDLED_S_EL1_FIQ`, it restores the
+ saved `ELR_EL3` and `SPSR_EL3` system registers back to the secure CPU
+ context (see step 4 above) in case the TSP had been preempted by a non
+ secure interrupt earlier. It does not save the secure context since the
+ TSP is expected to preserve it (see Section 2.2.2.1)
+
+3. If the function identifier is `TSP_PREEMPTED`, it saves the system
+ register context for the secure state by calling
+ `cm_el1_sysregs_context_save(SECURE)`.
+
+4. It restores the system register context for the non-secure state by
+ calling `cm_el1_sysregs_context_restore(NON_SECURE)`. It sets `x0` to
+ `SMC_PREEMPTED` if the incoming function identifier is
+ `TSP_PREEMPTED`. The Normal World is expected to resume the TSP after the
+ non-secure interrupt handling by issuing an SMC with `TSP_FID_RESUME` as
+ the function identifier.
+
+5. It ensures that the non-secure CPU context is used to program the next
+ exception return from EL3 by calling
+ `cm_set_next_eret_context(NON_SECURE)`.
+
+6. `tspd_smc_handler()` returns a reference to the non-secure `cpu_context`
+ as the return value.
+
+As mentioned in 4. above, if a non-secure interrupt preempts the TSP execution
+then the non-secure software issues an SMC with `TSP_FID_RESUME` as the function
+identifier to resume TSP execution. The TSPD service takes the following actions
+in `tspd_smc_handler()` function upon receiving this SMC:
+
+1. It ensures that the call originated from the non secure state. An
+ assertion is raised otherwise.
+
+2. Checks whether the TSP needs a resume i.e check if it was preempted. It
+ then saves the system register context for the secure state by calling
+ `cm_el1_sysregs_context_save(NON_SECURE)`.
+
+3. Restores the secure context by calling
+ `cm_el1_sysregs_context_restore(SECURE)`
+
+4. It ensures that the secure CPU context is used to program the next
+ exception return from EL3 by calling `cm_set_next_eret_context(SECURE)`.
+
+5. `tspd_smc_handler()` returns a reference to the secure `cpu_context` as the
+ return value.
+
+The figure below describes how the TSP/TSPD handle a non-secure interrupt when
+it is generated during execution in the TSP with `PSTATE.I` = 0.
+
+
+
+
+#### 2.3.3 Secure payload
+The SP should implement one or both of the synchronous and asynchronous
+interrupt handling models depending upon the interrupt routing model it has
+chosen (as described in 2.2.3).
+
+In the synchronous model, it should begin handling a Secure-EL1 interrupt after
+receiving control from the SPD service at an entrypoint agreed upon during build
+time or during the registration phase. Before handling the interrupt, the SP
+should save any Secure-EL1 system register context which is needed for resuming
+normal execution in the SP later e.g. `SPSR_EL1, `ELR_EL1`. After handling the
+interrupt, the SP could return control back to the exception level and security
+state where the interrupt was originally taken from. The SP should use an SMC32
+or SMC64 to ask the SPD service to do this.
+
+In the asynchronous model, the Secure Payload is responsible for handling
+non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception
+vector table when `PSTATE.I` and `PSTATE.F` bits are 0. As described earlier,
+when a non-secure interrupt is generated, the SP should coordinate with the SPD
+service to pass control back to the non-secure state in the last known exception
+level. This will allow the non-secure interrupt to be handled in the non-secure
+state.
+
+##### 2.3.3.1 Test secure payload behavior
+The TSPD hands control of a Secure-EL1 interrupt to the TSP at the
+`tsp_fiq_entry()`. The TSP handles the interrupt while ensuring that the
+handover agreement described in Section 2.2.2.1 is maintained. It updates some
+statistics by calling `tsp_update_sync_fiq_stats()`. It then calls
+`tsp_fiq_handler()` which.
+
+1. Checks whether the interrupt is the secure physical timer interrupt. It
+ uses the platform API `plat_ic_get_pending_interrupt_id()` to get the
+ interrupt number.
+
+2. Handles the interrupt by acknowledging it using the
+ `plat_ic_acknowledge_interrupt()` platform API, calling
+ `tsp_generic_timer_handler()` to reprogram the secure physical generic
+ timer and calling the `plat_ic_end_of_interrupt()` platform API to signal
+ end of interrupt processing.
+
+The TSP passes control back to the TSPD by issuing an SMC64 with
+`TSP_HANDLED_S_EL1_FIQ` as the function identifier.
+
+The TSP handles interrupts under the asynchronous model as follows.
+
+1. Secure-EL1 interrupts are handled by calling the `tsp_fiq_handler()`
+ function. The function has been described above.
+
+2. Non-secure interrupts are handled by issuing an SMC64 with `TSP_PREEMPTED`
+ as the function identifier. Execution resumes at the instruction that
+ follows this SMC instruction when the TSPD hands control to the TSP in
+ response to an SMC with `TSP_FID_RESUME` as the function identifier from
+ the non-secure state (see section 2.3.2.1).
+
+- - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
+
+[Porting Guide]: ./porting-guide.md
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index b4e0a58..d970190 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -7,12 +7,14 @@
1. Introduction
2. Common Modifications
* Common mandatory modifications
+ * Handling reset
* Common optional modifications
3. Boot Loader stage specific modifications
* Boot Loader stage 1 (BL1)
* Boot Loader stage 2 (BL2)
* Boot Loader stage 3-1 (BL3-1)
* PSCI implementation (in BL3-1)
+ * Interrupt Management framework (in BL3-1)
4. C Library
5. Storage abstraction layer
@@ -29,10 +31,12 @@
* Setting up the execution context in a certain way, or
* Defining certain constants (for example #defines).
-The firmware provides a default implementation of variables and functions to
-fulfill the optional requirements. These implementations are all weakly defined;
-they are provided to ease the porting effort. Each platform port can override
-them with its own implementation if the default implementation is inadequate.
+The platform-specific functions and variables are all declared in
+[include/plat/common/platform.h]. The firmware provides a default implementation
+of variables and functions to fulfill the optional requirements. These
+implementations are all weakly defined; they are provided to ease the porting
+effort. Each platform port can override them with its own implementation if the
+default implementation is inadequate.
Some modifications are common to all Boot Loader (BL) stages. Section 2
discusses these in detail. The subsequent sections discuss the remaining
@@ -77,11 +81,12 @@
for the firmware to work correctly.
-### File : platform.h [mandatory]
+### File : platform_def.h [mandatory]
-Each platform must export a header file of this name with the following
-constants defined. In the ARM FVP port, this file is found in
-[plat/fvp/platform.h].
+Each platform must ensure that a header file of this name is in the system
+include path with the following constants defined. This may require updating the
+list of `PLAT_INCLUDES` in the `platform.mk` file. In the ARM FVP port, this
+file is found in [plat/fvp/include/platform_def.h].
* **#define : PLATFORM_LINKER_FORMAT**
@@ -175,11 +180,6 @@
the linker scripts to ensure that the BL1 data section and BL2/BL3-1 binary
images fit into the available memory.
-* **#define : SYS_CNTCTL_BASE**
-
- Defines the base address of the `CNTCTLBase` frame of the memory mapped
- counter and timer in the system level implementation of the generic timer.
-
* **#define : BL1_RO_BASE**
Defines the base address in secure ROM where BL1 originally lives. Must be
@@ -249,11 +249,11 @@
constants.
-### File : platform_macros.S [mandatory]
+### File : plat_macros.S [mandatory]
-Each platform must export a file of this name with the following
-macro defined. In the ARM FVP port, this file is found in
-[plat/fvp/include/platform_macros.S].
+Each platform must ensure a file of this name is in the system include path with
+the following macro defined. In the ARM FVP port, this file is found in
+[plat/fvp/include/plat_macros.S].
* **Macro : plat_print_gic_regs**
@@ -276,8 +276,85 @@
In the ARM FVP port, it returns the base frequency of the system counter,
which is retrieved from the first entry in the frequency modes table.
+
+2.2 Handling Reset
+------------------
+
+BL1 by default implements the reset vector where execution starts from a cold
+or warm boot. BL3-1 can be optionally set as a reset vector using the
+RESET_TO_BL31 make variable.
+
+For each CPU, the reset vector code is responsible for the following tasks:
+
+1. Distinguishing between a cold boot and a warm boot.
+
+2. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
+ the CPU is placed in a platform-specific state until the primary CPU
+ performs the necessary steps to remove it from this state.
+
+3. In the case of a warm boot, ensuring that the CPU jumps to a platform-
+ specific address in the BL3-1 image in the same processor mode as it was
+ when released from reset.
+
+The following functions need to be implemented by the platform port to enable
+reset vector code to perform the above tasks.
+
+
+### Function : platform_get_entrypoint() [mandatory]
+
+ Argument : unsigned long
+ Return : unsigned int
+
+This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The CPU
+is identified by its `MPIDR`, which is passed as the argument. The function is
+responsible for distinguishing between a warm and cold reset using platform-
+specific means. If it's a warm reset then it returns the entrypoint into the
+BL3-1 image that the CPU must jump to. If it's a cold reset then this function
+must return zero.
+
+This function is also responsible for implementing a platform-specific mechanism
+to handle the condition where the CPU has been warm reset but there is no
+entrypoint to jump to.
+
+This function does not follow the Procedure Call Standard used by the
+Application Binary Interface for the ARM 64-bit architecture. The caller should
+not assume that callee saved registers are preserved across a call to this
+function.
+
+This function fulfills requirement 1 and 3 listed above.
+
+
+### Function : plat_secondary_cold_boot_setup() [mandatory]
+
+ Argument : void
+ Return : void
+
+This function is called with the MMU and data caches disabled. It is responsible
+for placing the executing secondary CPU in a platform-specific state until the
+primary CPU performs the necessary actions to bring it out of that state and
+allow entry into the OS.
+
+In the ARM FVP port, each secondary CPU powers itself off. The primary CPU is
+responsible for powering up the secondary CPU when normal world software
+requires them.
+
+This function fulfills requirement 2 above.
-2.2 Common optional modifications
+
+### Function : platform_mem_init() [mandatory]
+
+ Argument : void
+ Return : void
+
+This function is called before any access to data is made by the firmware, in
+order to carry out any essential memory initialization.
+
+The ARM FVP port uses this function to initialize the mailbox memory used for
+providing the warm-boot entry-point addresses.
+
+
+
+2.3 Common optional modifications
---------------------------------
The following are helper functions implemented by the firmware that perform
@@ -382,8 +459,6 @@
* In BL1, whenever an exception is taken.
* In BL2, whenever an exception is taken.
-* In BL3-1, whenever an asynchronous exception or a synchronous exception
- other than an SMC32/SMC64 exception is taken.
The default implementation doesn't do anything, to avoid making assumptions
about the way the platform displays its status information.
@@ -403,24 +478,16 @@
BL1 implements the reset vector where execution starts from after a cold or
warm boot. For each CPU, BL1 is responsible for the following tasks:
-1. Distinguishing between a cold boot and a warm boot.
+1. Handling the reset as described in section 2.2
2. In the case of a cold boot and the CPU being the primary CPU, ensuring that
only this CPU executes the remaining BL1 code, including loading and passing
control to the BL2 stage.
-3. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
- the CPU is placed in a platform-specific state until the primary CPU
- performs the necessary steps to remove it from this state.
-
-4. In the case of a warm boot, ensuring that the CPU jumps to a platform-
- specific address in the BL3-1 image in the same processor mode as it was
- when released from reset.
-
-5. Loading the BL2 image from non-volatile storage into secure memory at the
+3. Loading the BL2 image from non-volatile storage into secure memory at the
address specified by the platform defined constant `BL2_BASE`.
-6. Populating a `meminfo` structure with the following information in memory,
+4. Populating a `meminfo` structure with the following information in memory,
accessible by BL2 immediately upon entry.
meminfo.total_base = Base address of secure RAM visible to BL2
@@ -447,69 +514,19 @@
The following functions need to be implemented by the platform port to enable
BL1 to perform the above tasks.
-
-### Function : platform_get_entrypoint() [mandatory]
-
- Argument : unsigned long
- Return : unsigned int
-
-This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The CPU
-is identified by its `MPIDR`, which is passed as the argument. The function is
-responsible for distinguishing between a warm and cold reset using platform-
-specific means. If it's a warm reset then it returns the entrypoint into the
-BL3-1 image that the CPU must jump to. If it's a cold reset then this function
-must return zero.
-
-This function is also responsible for implementing a platform-specific mechanism
-to handle the condition where the CPU has been warm reset but there is no
-entrypoint to jump to.
-
-This function does not follow the Procedure Call Standard used by the
-Application Binary Interface for the ARM 64-bit architecture. The caller should
-not assume that callee saved registers are preserved across a call to this
-function.
-
-This function fulfills requirement 1 listed above.
-
-### Function : plat_secondary_cold_boot_setup() [mandatory]
+### Function : bl1_plat_arch_setup() [mandatory]
Argument : void
Return : void
-This function is called with the MMU and data caches disabled. It is responsible
-for placing the executing secondary CPU in a platform-specific state until the
-primary CPU performs the necessary actions to bring it out of that state and
-allow entry into the OS.
-
-In the ARM FVP port, each secondary CPU powers itself off. The primary CPU is
-responsible for powering up the secondary CPU when normal world software
-requires them.
-
-This function fulfills requirement 3 above.
-
-
-### Function : platform_cold_boot_init() [mandatory]
-
- Argument : unsigned long
- Return : unsigned int
-
-This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU. The argument to this function is the address of the
-`bl1_main()` routine where the generic BL1-specific actions are performed.
This function performs any platform-specific and architectural setup that the
-platform requires to make execution of `bl1_main()` possible.
-
-The platform must enable the MMU with identity mapped page tables and enable
-caches by setting the `SCTLR.I` and `SCTLR.C` bits.
-
-Platform-specific setup might include configuration of memory controllers,
-configuration of the interconnect to allow the cluster to service cache snoop
-requests from another cluster, zeroing of the ZI section, and so on.
+platform requires. Platform-specific setup might include configuration of
+memory controllers, configuration of the interconnect to allow the cluster
+to service cache snoop requests from another cluster, and so on.
In the ARM FVP port, this function enables CCI snoops into the cluster that the
-primary CPU is part of. It also enables the MMU and initializes the ZI section
-in the BL1 image through the use of linker defined symbols.
+primary CPU is part of. It also enables the MMU.
This function helps fulfill requirement 2 above.
@@ -526,7 +543,7 @@
This function is also responsible for initializing the storage abstraction layer
which is used to load further bootloader images.
-This function helps fulfill requirement 5 above.
+This function helps fulfill requirement 3 above.
### Function : bl1_plat_sec_mem_layout() [mandatory]
@@ -549,7 +566,7 @@
populates a similar structure to tell BL2 the extents of memory available for
its own use.
-This function helps fulfill requirement 5 above.
+This function helps fulfill requirement 3 above.
### Function : init_bl2_mem_layout() [optional]
@@ -557,10 +574,8 @@
Argument : meminfo *, meminfo *, unsigned int, unsigned long
Return : void
-Each BL stage needs to tell the next stage the amount of secure RAM available
-for it to use. For example, as part of handing control to BL2, BL1 informs BL2
-of the extents of secure RAM available for BL2 to use. BL2 must do the same when
-passing control to BL3-1. This information is populated in a `meminfo`
+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
@@ -569,6 +584,18 @@
to BL2. An illustration of how this is done in the ARM FVP port is given in the
[User Guide], in the Section "Memory layout on Base FVP".
+
+### Function : bl1_plat_set_bl2_ep_info() [mandatory]
+
+ Argument : image_info *, entry_point_info *
+ Return : void
+
+This function is called after loading BL2 image and it can be used to overwrite
+the entry point set by loader and also set the security state and SPSR which
+represents the entry point system state for BL2.
+
+On FVP, we are setting the security state and the SPSR for the BL2 entrypoint
+
3.2 Boot Loader Stage 2 (BL2)
-----------------------------
@@ -589,55 +616,22 @@
address is determined using the `plat_get_ns_image_entrypoint()` function
described below.
- BL2 populates an `el_change_info` structure in memory provided by the
- platform with information about how BL3-1 should pass control to the normal
- world BL image.
-
-3. Populating a `meminfo` structure with the following information in
- memory that is accessible by BL3-1 immediately upon entry.
-
- meminfo.total_base = Base address of secure RAM visible to BL3-1
- meminfo.total_size = Size of secure RAM visible to BL3-1
- meminfo.free_base = Base address of secure RAM available for allocation
- to BL3-1
- meminfo.free_size = Size of secure RAM available for allocation to
- BL3-1
-
- BL2 populates this information in the `bl31_meminfo` field of the pointer
- returned by the `bl2_get_bl31_args_ptr() function. BL2 implements the
- `init_bl31_mem_layout()` function to populate the BL3-1 meminfo structure
- described above. The platform may override this implementation, for example
- if the platform wants to restrict the amount of memory visible to BL3-1.
- Details of this function are given below.
+3. BL2 populates an `entry_point_info` structure in memory provided by the
+ platform with information about how BL3-1 should pass control to the
+ other BL images.
4. (Optional) Loading the BL3-2 binary image (if present) from platform
provided non-volatile storage. To load the BL3-2 image, BL2 makes use of
- the `bl32_meminfo` field in the `bl31_args` structure to which a pointer is
- returned by the `bl2_get_bl31_args_ptr()` function. The platform also
- defines the address in memory where BL3-2 is loaded through the optional
- constant `BL32_BASE`. BL2 uses this information to determine if there is
- enough memory to load the BL3-2 image. If `BL32_BASE` is not defined then
- this and the following two steps are not performed.
+ the `meminfo` returned by the `bl2_plat_get_bl32_meminfo()` function.
+ The platform also defines the address in memory where BL3-2 is loaded
+ through the optional constant `BL32_BASE`. BL2 uses this information
+ to determine if there is enough memory to load the BL3-2 image.
+ If `BL32_BASE` is not defined then this and the next step is not performed.
5. (Optional) Arranging to pass control to the BL3-2 image (if present) that
- has been pre-loaded at `BL32_BASE`. BL2 populates an `el_change_info`
+ has been pre-loaded at `BL32_BASE`. BL2 populates an `entry_point_info`
structure in memory provided by the platform with information about how
- BL3-1 should pass control to the BL3-2 image. This structure follows the
- `el_change_info` structure populated for the normal world BL image in 2.
- above.
-
-6. (Optional) Populating a `meminfo` structure with the following information
- in memory that is accessible by BL3-1 immediately upon entry.
-
- meminfo.total_base = Base address of memory visible to BL3-2
- meminfo.total_size = Size of memory visible to BL3-2
- meminfo.free_base = Base address of memory available for allocation
- to BL3-2
- meminfo.free_size = Size of memory available for allocation to
- BL3-2
-
- BL2 populates this information in the `bl32_meminfo` field of the pointer
- returned by the `bl2_get_bl31_args_ptr()` function.
+ BL3-1 should pass control to the BL3-2 image.
The following functions must be implemented by the platform port to enable BL2
to perform the above tasks.
@@ -645,14 +639,12 @@
### Function : bl2_early_platform_setup() [mandatory]
- Argument : meminfo *, void *
+ Argument : meminfo *
Return : void
This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU. The arguments to this function are:
-
-* The address of the `meminfo` structure populated by BL1
-* An opaque pointer that the platform may use as needed.
+by the primary CPU. The arguments to this function is the address of the
+`meminfo` structure populated by BL1.
The platform must copy the contents of the `meminfo` structure into a private
variable as the original memory may be subsequently overwritten by BL2. The
@@ -683,26 +675,11 @@
called by the primary CPU.
The purpose of this function is to perform any platform initialization
-specific to BL2. For example on the ARM FVP port this function initialises a
-internal pointer (`bl2_to_bl31_args`) to a `bl31_args` which will be used by
-BL2 to pass information to BL3_1. The pointer is initialized to the base
-address of Secure DRAM (`0x06000000`).
-
-The ARM FVP port also populates the `bl32_meminfo` field in the `bl31_args`
-structure pointed to by `bl2_to_bl31_args` with the extents of memory available
-for use by the BL3-2 image. The memory is allocated in the Secure DRAM from the
-address defined by the constant `BL32_BASE`. The ARM FVP port currently loads
-the BL3-2 image at the Secure DRAM address `0x6002000`.
-
-The non-secure memory extents used for loading BL3-3 are also initialized in
-this function. This information is accessible in the `bl33_meminfo` field in
-the `bl31_args` structure pointed to by `bl2_to_bl31_args`.
-
-Platform security components are configured if required. For the Base FVP the
-TZC-400 TrustZone controller is configured to only grant non-secure access
-to DRAM. This avoids aliasing between secure and non-secure accesses in the
-TLB and cache - secure execution states can use the NS attributes in the
-MMU translation tables to access the DRAM.
+specific to BL2. Platform security components are configured if required.
+For the Base FVP the TZC-400 TrustZone controller is configured to only
+grant non-secure access to DRAM. This avoids aliasing between secure and
+non-secure accesses in the TLB and cache - secure execution states can use
+the NS attributes in the MMU translation tables to access the DRAM.
This function is also responsible for initializing the storage abstraction layer
which is used to load further bootloader images.
@@ -721,41 +698,110 @@
populated with the extents of secure RAM available for BL2 to use. See
`bl2_early_platform_setup()` above.
+
+### Function : bl2_plat_get_bl31_params() [mandatory]
+
+ Argument : void
+ Return : bl31_params *
+
+BL2 platform code needs to return a pointer to a `bl31_params` structure it
+will use for passing information to BL3-1. The `bl31_params` structure carries
+the following information.
+ - Header describing the version information for interpreting the bl31_param
+ structure
+ - Information about executing the BL3-3 image in the `bl33_ep_info` field
+ - Information about executing the BL3-2 image in the `bl32_ep_info` field
+ - Information about the type and extents of BL3-1 image in the
+ `bl31_image_info` field
+ - Information about the type and extents of BL3-2 image in the
+ `bl32_image_info` field
+ - Information about the type and extents of BL3-3 image in the
+ `bl33_image_info` field
+
+The memory pointed by this structure and its sub-structures should be
+accessible from BL3-1 initialisation code. BL3-1 might choose to copy the
+necessary content, or maintain the structures until BL3-3 is initialised.
-### Function : bl2_get_bl31_args_ptr() [mandatory]
+
+### Funtion : bl2_plat_get_bl31_ep_info() [mandatory]
Argument : void
- Return : bl31_args *
+ Return : entry_point_info *
+
+BL2 platform code returns a pointer which is used to populate the entry point
+information for BL3-1 entry point. The location pointed by it should be
+accessible from BL1 while processing the synchronous exception to run to BL3-1.
+
+On FVP this is allocated inside an bl2_to_bl31_params_mem structure which
+is allocated at an address pointed by PARAMS_BASE.
+
+
+### Function : bl2_plat_set_bl31_ep_info() [mandatory]
+
+ Argument : image_info *, entry_point_info *
+ Return : void
-BL2 platform code needs to return a pointer to a `bl31_args` structure it will
-use for passing information to BL3-1. The `bl31_args` structure carries the
-following information. This information is used by the `bl2_main()` function to
-load the BL3-2 (if present) and BL3-3 images.
- - Extents of memory available to the BL3-1 image in the `bl31_meminfo` field
- - Extents of memory available to the BL3-2 image in the `bl32_meminfo` field
- - Extents of memory available to the BL3-3 image in the `bl33_meminfo` field
- - Information about executing the BL3-3 image in the `bl33_image_info` field
- - Information about executing the BL3-2 image in the `bl32_image_info` field
+This function is called after loading BL3-1 image and it can be used to
+overwrite the entry point set by loader and also set the security state
+and SPSR which represents the entry point system state for BL3-1.
+On FVP, we are setting the security state and the SPSR for the BL3-1
+entrypoint.
-### Function : init_bl31_mem_layout() [optional]
+### Function : bl2_plat_set_bl32_ep_info() [mandatory]
- Argument : meminfo *, meminfo *, unsigned int
+ Argument : image_info *, entry_point_info *
Return : void
-Each BL stage needs to tell the next stage the amount of secure RAM that is
-available for it to use. For example, as part of handing control to BL2, BL1
-must inform BL2 about the extents of secure RAM that is available for BL2 to
-use. BL2 must do the same when passing control to BL3-1. This information is
-populated in a `meminfo` structure.
+This function is called after loading BL3-2 image and it can be used to
+overwrite the entry point set by loader and also set the security state
+and SPSR which represents the entry point system state for BL3-2.
-Depending upon where BL3-1 has been loaded in secure RAM (determined by
-`BL31_BASE`), BL2 calculates the amount of free memory available for BL3-1 to
-use. BL2 also ensures that BL3-1 is able reclaim memory occupied by BL2. This
-is done because BL2 never executes again after passing control to BL3-1.
-An illustration of how this is done in the ARM FVP port is given in the
-[User Guide], in the section "Memory layout on Base FVP".
+On FVP, we are setting the security state and the SPSR for the BL3-2
+entrypoint
+### Function : bl2_plat_set_bl33_ep_info() [mandatory]
+
+ Argument : image_info *, entry_point_info *
+ Return : void
+
+This function is called after loading BL3-3 image and it can be used to
+overwrite the entry point set by loader and also set the security state
+and SPSR which represents the entry point system state for BL3-3.
+
+On FVP, we are setting the security state and the SPSR for the BL3-3
+entrypoint
+
+### Function : bl2_plat_get_bl32_meminfo() [mandatory]
+
+ Argument : meminfo *
+ Return : void
+
+This function is used to get the memory limits where BL2 can load the
+BL3-2 image. The meminfo provided by this is used by load_image() to
+validate whether the BL3-2 image can be loaded with in the given
+memory from the given base.
+
+### Function : bl2_plat_get_bl33_meminfo() [mandatory]
+
+ Argument : meminfo *
+ Return : void
+
+This function is used to get the memory limits where BL2 can load the
+BL3-3 image. The meminfo provided by this is used by load_image() to
+validate whether the BL3-3 image can be loaded with in the given
+memory from the given base.
+
+### Function : bl2_plat_flush_bl31_params() [mandatory]
+
+ Argument : void
+ Return : void
+
+Once BL2 has populated all the structures that needs to be read by BL1
+and BL3-1 including the bl31_params structures and its sub-structures,
+the bl31_ep_info structure and any platform specific data. It flushes
+all these data to the main memory so that it is available when we jump to
+later Bootloader stages with MMU off
### Function : plat_get_ns_image_entrypoint() [mandatory]
@@ -783,7 +829,7 @@
should make no assumptions about the system state when it receives control.
2. Passing control to a normal world BL image, pre-loaded at a platform-
- specific address by BL2. BL3-1 uses the `el_change_info` structure that BL2
+ specific address by BL2. BL3-1 uses the `entry_point_info` structure that BL2
populated in memory to do this.
3. Providing runtime firmware services. Currently, BL3-1 only implements a
@@ -794,8 +840,11 @@
4. Optionally passing control to the BL3-2 image, pre-loaded at a platform-
specific address by BL2. BL3-1 exports a set of apis that allow runtime
services to specify the security state in which the next image should be
- executed and run the corresponding image. BL3-1 uses the `el_change_info`
- and `meminfo` structure populated by BL2 to do this.
+ executed and run the corresponding image. BL3-1 uses the `entry_point_info`
+ structure populated by BL2 to do this.
+
+If BL3-1 is a reset vector, It also needs to handle the reset as specified in
+section 2.2 before the tasks described above.
The following functions must be implemented by the platform port to enable BL3-1
to perform the above tasks.
@@ -803,26 +852,26 @@
### Function : bl31_early_platform_setup() [mandatory]
- Argument : meminfo *, void *, unsigned long
+ Argument : bl31_params *, void *
Return : void
This function executes with the MMU and data caches disabled. It is only called
by the primary CPU. The arguments to this function are:
-* The address of the `meminfo` structure populated by BL2.
+* The address of the `bl31_params` structure populated by BL2.
* An opaque pointer that the platform may use as needed.
-* The `MPIDR` of the primary CPU.
-The platform can copy the contents of the `meminfo` structure into a private
-variable if the original memory may be subsequently overwritten by BL3-1. The
-reference to this structure is made available to all BL3-1 code through the
-`bl31_plat_sec_mem_layout()` function.
+The platform can copy the contents of the `bl31_params` structure and its
+sub-structures into private variables if the original memory may be
+subsequently overwritten by BL3-1 and similarly the `void *` pointing
+to the platform data also needs to be saved.
-On the ARM FVP port, BL2 passes a pointer to a `bl31_args` structure populated
-in the secure DRAM at address `0x6000000` in the opaque pointer mentioned
-earlier. BL3-1 does not copy this information to internal data structures as it
-guarantees that the secure DRAM memory will not be overwritten. It maintains an
-internal reference to this information in the `bl2_to_bl31_args` variable.
+On the ARM FVP port, BL2 passes a pointer to a `bl31_params` structure populated
+in the secure DRAM at address `0x6000000` in the bl31_params * argument and it
+does not use opaque pointer mentioned earlier. BL3-1 does not copy this
+information to internal data structures as it guarantees that the secure
+DRAM memory will not be overwritten. It maintains an internal reference to this
+information in the `bl2_to_bl31_params` variable.
### Function : bl31_plat_arch_setup() [mandatory]
@@ -861,7 +910,7 @@
### Function : bl31_get_next_image_info() [mandatory]
Argument : unsigned int
- Return : el_change_info *
+ Return : entry_point_info *
This function may execute with the MMU and data caches enabled if the platform
port does the necessary initializations in `bl31_plat_arch_setup()`.
@@ -869,41 +918,11 @@
This function is called by `bl31_main()` to retrieve information provided by
BL2 for the next image in the security state specified by the argument. BL3-1
uses this information to pass control to that image in the specified security
-state. This function must return a pointer to the `el_change_info` structure
+state. This function must return a pointer to the `entry_point_info` structure
(that was copied during `bl31_early_platform_setup()`) if the image exists. It
should return NULL otherwise.
-### Function : bl31_plat_sec_mem_layout() [mandatory]
-
- Argument : void
- Return : meminfo *
-
-This function should only be called on the cold boot path. This function may
-execute with the MMU and data caches enabled if the platform port does the
-necessary initializations in `bl31_plat_arch_setup()`. It is only called by the
-primary CPU.
-
-The purpose of this function is to return a pointer to a `meminfo` structure
-populated with the extents of secure RAM available for BL3-1 to use. See
-`bl31_early_platform_setup()` above.
-
-
-### Function : bl31_plat_get_bl32_mem_layout() [mandatory]
-
- Argument : void
- Return : meminfo *
-
-This function should only be called on the cold boot path. This function may
-execute with the MMU and data caches enabled if the platform port does the
-necessary initializations in `bl31_plat_arch_setup()`. It is only called by the
-primary CPU.
-
-The purpose of this function is to return a pointer to a `meminfo` structure
-populated with the extents of memory available for BL3-2 to use. See
-`bl31_early_platform_setup()` above.
-
-
3.3 Power State Coordination Interface (in BL3-1)
------------------------------------------------
@@ -1117,6 +1136,135 @@
provided in the description of the `plat_get_aff_count()` and
`plat_get_aff_state()` functions above.
+3.4 Interrupt Management framework (in BL3-1)
+----------------------------------------------
+BL3-1 implements an Interrupt Management Framework (IMF) to manage interrupts
+generated in either security state and targeted to EL1 or EL2 in the non-secure
+state or EL3/S-EL1 in the secure state. The design of this framework is
+described in the [IMF Design Guide]
+
+A platform should export the following APIs to support the IMF. The following
+text briefly describes each api and its implementation on the FVP port. The API
+implementation depends upon the type of interrupt controller present in the
+platform. The FVP implements an ARM Generic Interrupt Controller (ARM GIC) as
+per the version 2.0 of the [ARM GIC Architecture Specification]
+
+### Function : plat_interrupt_type_to_line() [mandatory]
+
+ Argument : uint32_t, uint32_t
+ Return : uint32_t
+
+The ARM processor signals an interrupt exception either through the IRQ or FIQ
+interrupt line. The specific line that is signaled depends on how the interrupt
+controller (IC) reports different interrupt types from an execution context in
+either security state. The IMF uses this API to determine which interrupt line
+the platform IC uses to signal each type of interrupt supported by the framework
+from a given security state.
+
+The first parameter will be one of the `INTR_TYPE_*` values (see [IMF Design
+Guide]) indicating the target type of the interrupt, the second parameter is the
+security state of the originating execution context. The return result is the
+bit position in the `SCR_EL3` register of the respective interrupt trap: IRQ=1,
+FIQ=2.
+
+The FVP port configures the ARM GIC to signal S-EL1 interrupts as FIQs and
+Non-secure interrupts as IRQs from either security state.
+
+
+### Function : plat_ic_get_pending_interrupt_type() [mandatory]
+
+ Argument : void
+ Return : uint32_t
+
+This API returns the type of the highest priority pending interrupt at the
+platform IC. The IMF uses the interrupt type to retrieve the corresponding
+handler function. `INTR_TYPE_INVAL` is returned when there is no interrupt
+pending. The valid interrupt types that can be returned are `INTR_TYPE_EL3`,
+`INTR_TYPE_S_EL1` and `INTR_TYPE_NS`.
+
+The FVP port reads the _Highest Priority Pending Interrupt Register_
+(`GICC_HPPIR`) to determine the id of the pending interrupt. The type of interrupt
+depends upon the id value as follows.
+
+1. id < 1022 is reported as a S-EL1 interrupt
+2. id = 1022 is reported as a Non-secure interrupt.
+3. id = 1023 is reported as an invalid interrupt type.
+
+
+### Function : plat_ic_get_pending_interrupt_id() [mandatory]
+
+ Argument : void
+ Return : uint32_t
+
+This API returns the id of the highest priority pending interrupt at the
+platform IC. The IMF passes the id returned by this API to the registered
+handler for the pending interrupt if the `IMF_READ_INTERRUPT_ID` build time flag
+is set. INTR_ID_UNAVAILABLE is returned when there is no interrupt pending.
+
+The FVP port reads the _Highest Priority Pending Interrupt Register_
+(`GICC_HPPIR`) to determine the id of the pending interrupt. The id that is
+returned by API depends upon the value of the id read from the interrupt
+controller as follows.
+
+1. id < 1022. id is returned as is.
+2. id = 1022. The _Aliased Highest Priority Pending Interrupt Register_
+ (`GICC_AHPPIR`) is read to determine the id of the non-secure interrupt. This
+ id is returned by the API.
+3. id = 1023. `INTR_ID_UNAVAILABLE` is returned.
+
+
+### Function : plat_ic_acknowledge_interrupt() [mandatory]
+
+ Argument : void
+ Return : uint32_t
+
+This API is used by the CPU to indicate to the platform IC that processing of
+the highest pending interrupt has begun. It should return the id of the
+interrupt which is being processed.
+
+The FVP port reads the _Interrupt Acknowledge Register_ (`GICC_IAR`). This
+changes the state of the highest priority pending interrupt from pending to
+active in the interrupt controller. It returns the value read from the
+`GICC_IAR`. This value is the id of the interrupt whose state has been changed.
+
+The TSP uses this API to start processing of the secure physical timer
+interrupt.
+
+
+### Function : plat_ic_end_of_interrupt() [mandatory]
+
+ Argument : uint32_t
+ Return : void
+
+This API is used by the CPU to indicate to the platform IC that processing of
+the interrupt corresponding to the id (passed as the parameter) has
+finished. The id should be the same as the id returned by the
+`plat_ic_acknowledge_interrupt()` API.
+
+The FVP port writes the id to the _End of Interrupt Register_
+(`GICC_EOIR`). This deactivates the corresponding interrupt in the interrupt
+controller.
+
+The TSP uses this API to finish processing of the secure physical timer
+interrupt.
+
+
+### Function : plat_ic_get_interrupt_type() [mandatory]
+
+ Argument : uint32_t
+ Return : uint32_t
+
+This API returns the type of the interrupt id passed as the parameter.
+`INTR_TYPE_INVAL` is returned if the id is invalid. If the id is valid, a valid
+interrupt type (one of `INTR_TYPE_EL3`, `INTR_TYPE_S_EL1` and `INTR_TYPE_NS`) is
+returned depending upon how the interrupt has been configured by the platform
+IC.
+
+The FVP port configures S-EL1 interrupts as Group0 interrupts and Non-secure
+interrupts as Group1 interrupts. It reads the group value corresponding to the
+interrupt id from the relevant _Interrupt Group Register_ (`GICD_IGROUPRn`). It
+uses the group value to determine the type of interrupt.
+
4. C Library
-------------
@@ -1187,10 +1335,10 @@
operations such as loading a bootloader image.
The current implementation only allows for known images to be loaded by the
-firmware. These images are specified by using their names, as defined in the
-`platform.h` file. The platform layer (`plat_get_image_source()`) then returns
-a reference to a device and a driver-specific `spec` which will be understood
-by the driver to allow access to the image data.
+firmware. These images are specified by using their names, as defined in
+[include/plat/common/platform.h]. The platform layer (`plat_get_image_source()`)
+then returns a reference to a device and a driver-specific `spec` which will be
+understood by the driver to allow access to the image data.
The layer is designed in such a way that is it possible to chain drivers with
other drivers. For example, file-system drivers may be implemented on top of
@@ -1209,13 +1357,16 @@
_Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
-[User Guide]: user-guide.md
-[FreeBSD]: http://www.freebsd.org
+[ARM GIC Architecture Specification]: http://arminfo.emea.arm.com/help/topic/com.arm.doc.ihi0048b/IHI0048B_gic_architecture_specification.pdf
+[IMF Design Guide]: interrupt-framework-design.md
+[User Guide]: user-guide.md
+[FreeBSD]: http://www.freebsd.org
[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S
[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S
-[plat/fvp/platform.h]: ../plat/fvp/platform.h
-[plat/fvp/include/platform_macros.S]: ../plat/fvp/include/platform_macros.S
+[plat/fvp/include/platform_def.h]: ../plat/fvp/include/platform_def.h
+[plat/fvp/include/plat_macros.S]: ../plat/fvp/include/plat_macros.S
[plat/fvp/aarch64/plat_common.c]: ../plat/fvp/aarch64/plat_common.c
[plat/fvp/plat_pm.c]: ../plat/fvp/plat_pm.c
[include/runtime_svc.h]: ../include/runtime_svc.h
+[include/plat/common/platform.h]: ../include/plat/common/platform.h
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 484ffeb..85103b3 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -30,7 +30,7 @@
RAM. For best performance, use a machine with a quad-core processor running at
2.6GHz with 16GB of RAM.
-The software has been tested on Ubuntu 12.04.02 (64-bit). Packages used
+The software has been tested on Ubuntu 12.04.04 (64-bit). Packages used
for building the software were installed from that distribution unless
otherwise specified.
@@ -56,11 +56,11 @@
wget http://releases.linaro.org/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz
tar -xf gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz
-* The Device Tree Compiler (DTC) included with Linux kernel 3.13 is used
+* The Device Tree Compiler (DTC) included with Linux kernel 3.15-rc6 is used
to build the Flattened Device Tree (FDT) source files (`.dts` files)
provided with this software.
-* (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.17.
+* (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.18.
4. Building the Trusted Firmware
@@ -167,6 +167,12 @@
read using a platform GIC API. `INTR_ID_UNAVAILABLE` is passed instead if
this option set to 0. Default is 0.
+* `RESET_TO_BL31`: Enable BL3-1 entrypoint as the CPU reset vector in place
+ of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+ entrypoint) or 1 (CPU reset to BL3-1 entrypoint).
+ The default value is 0.
+
+
### Creating a Firmware Image Package
FIPs are automatically created as part of the build instructions described in
@@ -387,7 +393,7 @@
### Obtaining a Linux kernel
-The software has been verified using a Linux kernel based on version 3.13.
+The software has been verified using a Linux kernel based on version 3.15-rc6.
Patches have been applied in order to enable the CPU idle feature.
Preparing a Linux kernel for use on the FVPs with CPU idle support can
@@ -398,12 +404,11 @@
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Not all CPU idle features are included in the mainline kernel yet. To
- use these, add the patches from Sudeep Holla's kernel, based on
- Linux 3.13:
+ use these, add the patches from Sudeep Holla's kernel:
cd linux
- git remote add -f --tags arm64_idle_genfw_ref git://linux-arm.org/linux-skn.git
- git checkout -b cpuidle arm64_idle_genfw_ref
+ git remote add -f --tags arm64_idle_v3.15-rc6 git://linux-arm.org/linux-skn.git
+ git checkout -b cpuidle arm64_idle_v3.15-rc6
2. Build with the Linaro GCC tools.
@@ -473,10 +478,10 @@
1. Download and unpack the disk image.
- NOTE: The unpacked disk image grows to 2 GiB in size.
+ NOTE: The unpacked disk image grows to 3 GiB in size.
- wget http://releases.linaro.org/14.01/openembedded/aarch64/vexpress64-openembedded_lamp-armv8-gcc-4.8_20140126-596.img.gz
- gunzip vexpress64-openembedded_lamp-armv8-gcc-4.8_20140126-596.img.gz
+ wget http://releases.linaro.org/14.04/openembedded/aarch64/vexpress64-openembedded_lamp-armv8-gcc-4.8_20140417-630.img.gz
+ gunzip vexpress64-openembedded_lamp-armv8-gcc-4.8_20140417-630.img.gz
2. Make sure the Linux kernel has Virtio support enabled using
`make ARCH=arm64 menuconfig`.
@@ -516,9 +521,11 @@
to the real file must be provided.
On the Base FVPs:
+
-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
On the Foundation FVP:
+
--block-device="<path-to>/<file-system-image>"
@@ -537,14 +544,14 @@
1. Download the file-system image:
- wget http://releases.linaro.org/14.01/openembedded/aarch64/linaro-image-lamp-genericarmv8-20140127-635.rootfs.tar.gz
+ wget http://releases.linaro.org/14.04/openembedded/aarch64/linaro-image-lamp-genericarmv8-20140417-667.rootfs.tar.gz
2. Modify the Linaro image:
# Prepare for use as RAM-disk. Normally use MMC, NFS or VirtioBlock.
# Be careful, otherwise you could damage your host file-system.
mkdir tmp; cd tmp
- sudo sh -c "zcat ../linaro-image-lamp-genericarmv8-20140127-635.rootfs.tar.gz | cpio -id"
+ sudo sh -c "zcat ../linaro-image-lamp-genericarmv8-20140417-667.rootfs.tar.gz | cpio -id"
sudo ln -s sbin/init .
sudo sh -c "echo 'devtmpfs /dev devtmpfs mode=0755,nosuid 0 0' >> etc/fstab"
sudo sh -c "find . | cpio --quiet -H newc -o | gzip -3 -n > ../filesystem.cpio.gz"
@@ -561,9 +568,10 @@
FVPs (64-bit versions only).
* `Foundation_v8` (Version 2.0, Build 0.8.5206)
-* `FVP_Base_AEMv8A-AEMv8A` (Version 5.4, Build 0.8.5405)
-* `FVP_Base_Cortex-A57x4-A53x4` (Version 5.4, Build 0.8.5405)
-* `FVP_Base_Cortex-A57x1-A53x1` (Version 5.4, Build 0.8.5405)
+* `FVP_Base_AEMv8A-AEMv8A` (Version 5.6, Build 0.8.5602)
+* `FVP_Base_Cortex-A57x4-A53x4` (Version 5.6, Build 0.8.5602)
+* `FVP_Base_Cortex-A57x1-A53x1` (Version 5.6, Build 0.8.5602)
+* `FVP_Base_Cortex-A57x2-A53x4` (Version 5.6, Build 0.8.5602)
NOTE: The software will not work on Version 1.0 of the Foundation FVP.
The commands below would report an `unhandled argument` error in this case.
@@ -575,7 +583,8 @@
The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
downloaded for free from [ARM's website][ARM FVP website].
-### Running on the Foundation FVP
+
+### Running on the Foundation FVP with reset to BL1 entrypoint
The following `Foundation_v8` parameters should be used to boot Linux with
4 CPUs using the ARM Trusted Firmware.
@@ -603,27 +612,42 @@
The memory mapped addresses `0x0` and `0x8000000` correspond to the start of
trusted ROM and NOR FLASH0 respectively.
-### Running on the AEMv8 Base FVP
+### Notes regarding Base FVP configuration options
-The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
-with 8 CPUs using the ARM Trusted Firmware.
+1. The `-C bp.flashloader0.fname` parameter is used to load a Firmware Image
+Package at the start of NOR FLASH0 (see the "Building the Trusted Firmware"
+section above).
-NOTE: Using `cache_state_modelled=1` makes booting very slow. The software will
+2. Using `cache_state_modelled=1` makes booting very slow. The software will
still work (and run much faster) without this option but this will hide any
cache maintenance defects in the software.
-NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
+3. Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
section above).
-NOTE: The `-C bp.flashloader0.fname` parameter is used to load a Firmware Image
-Package at the start of NOR FLASH0 (see the "Building the Trusted Firmware"
-section above).
+4. Setting the `-C bp.secure_memory` parameter to `1` is only supported on
+Base FVP versions 5.4 and newer. Setting this parameter to `0` is also
+supported. The `-C bp.tzc_400.diagnostics=1` parameter is optional. It
+instructs the FVP to provide some helpful information if a secure memory
+violation occurs.
-NOTE: Setting the `-C bp.secure_memory` parameter to `1` is only supported on
-FVP versions 5.4 and newer. Setting this parameter to `0` is also supported.
-The `-C bp.tzc_400.diagnostics=1` parameter is optional. It instructs the FVP to
-provide some helpful information if a secure memory violation occurs.
+5. The `--data="<path-to><bl31/bl32/bl33-binary>"@base address of binaries`
+parameter is used to load bootloader images in the Base FVP memory (see the
+"Building the Trusted Firmware" section above). The base address used to
+load the binaries with --data should match the image base addresses in
+platform_def.h used while linking the images.
+BL3-2 image is only needed if BL3-1 has been built to expect a secure-EL1
+payload.
+
+
+### Running on the AEMv8 Base FVP with reset to BL1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
+with 8 CPUs using the ARM Trusted Firmware.
<path-to>/FVP_Base_AEMv8A-AEMv8A \
-C pctl.startup=0.0.0.0 \
@@ -637,28 +661,14 @@
-C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-### Running on the Cortex-A57-A53 Base FVP
+### Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to
boot Linux with 8 CPUs using the ARM Trusted Firmware.
-NOTE: Using `cache_state_modelled=1` makes booting very slow. The software will
-still work (and run much faster) without this option but this will hide any
-cache maintenance defects in the software.
-
-NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
-if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
-section above).
-
-NOTE: The `-C bp.flashloader0.fname` parameter is used to load a Firmware Image
-Package at the start of NOR FLASH0 (see the "Building the Trusted Firmware"
-section above).
-
-NOTE: Setting the `-C bp.secure_memory` parameter to `1` is only supported on
-FVP versions 5.4 and newer. Setting this parameter to `0` is also supported.
-The `-C bp.tzc_400.diagnostics=1` parameter is optional. It instructs the FVP to
-provide some helpful information if a secure memory violation occurs.
-
<path-to>/FVP_Base_Cortex-A57x4-A53x4 \
-C pctl.startup=0.0.0.0 \
-C bp.secure_memory=1 \
@@ -669,6 +679,70 @@
-C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+### Running on the AEMv8 Base FVP with reset to BL3-1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
+with 8 CPUs using the ARM Trusted Firmware.
+
+NOTE: Uses the `-c clusterX.cpuX.RVBAR=@base address of BL3-1` where X is
+the cluster number in clusterX and cpu number in cpuX is used to set the reset
+vector for each core.
+
+ <path-to>/FVP_Base_AEMv8A-AEMv8A \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C bp.pl011_uart0.untimed_fifos=1 \
+ -C cluster0.cpu0.RVBAR=0x04006000 \
+ -C cluster0.cpu1.RVBAR=0x04006000 \
+ -C cluster0.cpu2.RVBAR=0x04006000 \
+ -C cluster0.cpu3.RVBAR=0x04006000 \
+ -C cluster1.cpu0.RVBAR=0x04006000 \
+ -C cluster1.cpu1.RVBAR=0x04006000 \
+ -C cluster1.cpu2.RVBAR=0x04006000 \
+ -C cluster1.cpu3.RVBAR=0x04006000 \
+ --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04006000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04024000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
+### Running on the Cortex-A57-A53 Base FVP with reset to BL3-1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to
+boot Linux with 8 CPUs using the ARM Trusted Firmware.
+
+NOTE: Uses the `-c clusterX.cpuX.RVBARADDR=@base address of BL3-1` where X is
+the cluster number in clusterX and cpu number in cpuX is used to set the reset
+vector for each core.
+
+ <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C bp.pl011_uart0.untimed_fifos=1 \
+ -C cluster0.cpu0.RVBARADDR=0x04006000 \
+ -C cluster0.cpu1.RVBARADDR=0x04006000 \
+ -C cluster0.cpu2.RVBARADDR=0x04006000 \
+ -C cluster0.cpu3.RVBARADDR=0x04006000 \
+ -C cluster1.cpu0.RVBARADDR=0x04006000 \
+ -C cluster1.cpu1.RVBARADDR=0x04006000 \
+ -C cluster1.cpu2.RVBARADDR=0x04006000 \
+ -C cluster1.cpu3.RVBARADDR=0x04006000 \
+ --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04006000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04024000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
### Configuring the GICv2 memory map
The Base FVP models support GICv2 with the default model parameters at the
@@ -758,6 +832,6 @@
[Firmware Design]: ./firmware-design.md
[ARM FVP website]: http://www.arm.com/fvp
-[Linaro Toolchain]: http://releases.linaro.org/13.09/components/toolchain/binaries/
+[Linaro Toolchain]: http://releases.linaro.org/13.11/components/toolchain/binaries/
[EDK2]: http://github.com/tianocore/edk2
[DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php
