Skip to content

GitLab

Commit 81123e82 authored by Soby Mathew's avatar Soby Mathew
Browse files

Documentation updates for the new GIC drivers 

This patch updates the relevant documentation in ARM Trusted Firmware
for the new GIC drivers. The user-guide.md and porting-guide.md have been
updated as follows:

*  The build option to compile Trusted Firmware with different GIC drivers
   for FVP has been explained in the user-guide.md.

*  The implementation details of interrupt management framework porting
   APIs for GICv3 have been added in porting-guide.md.

*  The Linaro tracking kernel release does not work OOB in GICv3 mode.
   The instructions for changing UEFI configuration in order to run with
   the new GICv3 driver in ARM TF have been added to user-guide.md.

The interrupt-framework-design.md has been updated as follows:

*  Describes support for registering and handling interrupts targeted to EL3
   e.g. Group 0 interrupts in GICv3.

*  Describes the build option `TSP_NS_INTR_ASYNC_PREEMPT` in detail.

*  Describes preemption of TSP in S-EL1 by non secure interrupts and
   also possibly by higher priority EL3 interrupts.

*  Describes the normal world sequence for issuing `standard` SMC calls.

*  Modifies the document to correspond to the current state of interrupt
   handling in TSPD and TSP.

*  Modifies the various functions names in the document to reflect
   the current names used in code.

Change-Id: I78c9514b5be834f193405aad3c1752a4a9e27a6c
parent 8e4f8291
Expand all Show whitespace changes
Inline Side-by-side
docs/interrupt-framework-design.md
View file @ 81123e82
This diff is collapsed.
docs/porting-guide.md
View file @ 81123e82
......@@ -1451,9 +1451,12 @@ 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 in ARM standard
platforms. The API implementation depends upon the type of interrupt controller
present in the platform. ARM standard platforms implements an ARM Generic
Interrupt Controller (ARM GIC) as per the version 2.0 of the
[ARM GIC Architecture Specification].
present in the platform. ARM standard platform layer supports both [ARM Generic
Interrupt Controller version 2.0 (GICv2)][ARM GIC Architecture Specification 2.0]
and [3.0 (GICv3)][ARM GIC Architecture Specification 3.0]. Juno builds the ARM
Standard layer to use GICv2 and the FVP can be configured to use either GICv2 or
GICv3 depending on the build flag `FVP_USE_GIC_DRIVER` (See FVP platform
specific build options in [User Guide] for more details).
### Function : plat_interrupt_type_to_line() [mandatory]
......@@ -1465,7 +1468,7 @@ 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.
from a given security state. This API must be invoked at EL3.
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
......@@ -1473,8 +1476,19 @@ 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.
ARM standard platforms configure the ARM GIC to signal S-EL1 interrupts
as FIQs and Non-secure interrupts as IRQs from either security state.
In the case of ARM standard platforms using GICv2, S-EL1 interrupts are
configured as FIQs and Non-secure interrupts as IRQs from either security
state.
In the case of ARM standard platforms using GICv3, the interrupt line to be
configured depends on the security state of the execution context when the
interrupt is signalled and are as follows:
* The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ in
NS-EL0/1/2 context.
* The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQ
in the NS-EL0/1/2 context.
* The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2
context.
### Function : plat_ic_get_pending_interrupt_type() [mandatory]
......@@ -1486,16 +1500,27 @@ 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`.
`INTR_TYPE_S_EL1` and `INTR_TYPE_NS`. This API must be invoked at EL3.
ARM standard platforms read 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.
In the case of ARM standard platforms using GICv2, the _Highest Priority
Pending Interrupt Register_ (`GICC_HPPIR`) is read 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.
In the case of ARM standard platforms using GICv3, the system register
`ICC_HPPIR0_EL1`, _Highest Priority Pending group 0 Interrupt Register_,
is read to determine the id of the pending interrupt. The type of interrupt
depends upon the id value as follows.
1. id = `PENDING_G1S_INTID` (1020) is reported as a S-EL1 interrupt
2. id = `PENDING_G1NS_INTID` (1021) is reported as a Non-secure interrupt.
3. id = `GIC_SPURIOUS_INTERRUPT` (1023) is reported as an invalid interrupt type.
4. All other interrupt id's are reported as EL3 interrupt.
### Function : plat_ic_get_pending_interrupt_id() [mandatory]
......@@ -1506,17 +1531,35 @@ This API returns the id of the highest priority pending interrupt at the
platform IC. INTR_ID_UNAVAILABLE is returned when there is no interrupt
pending.
ARM standard platforms read 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.
In the case of ARM standard platforms using GICv2, the _Highest Priority
Pending Interrupt Register_ (`GICC_HPPIR`) is read 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.
(`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.
In the case of ARM standard platforms using GICv3, if the API is invoked from
EL3, the system register `ICC_HPPIR0_EL1`, _Highest Priority Pending Interrupt
group 0 Register_, is read 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 < `PENDING_G1S_INTID` (1020). id is returned as is.
2. id = `PENDING_G1S_INTID` (1020) or `PENDING_G1NS_INTID` (1021). The system
register `ICC_HPPIR1_EL1`, _Highest Priority Pending Interrupt group 1
Register_ is read to determine the id of the group 1 interrupt. This id
is returned by the API as long as it is a valid interrupt id
3. If the id is any of the special interrupt identifiers,
`INTR_ID_UNAVAILABLE` is returned.
When the API invoked from S-EL1 for GICv3 systems, the id read from system
register `ICC_HPPIR1_EL1`, _Highest Priority Pending group 1 Interrupt
Register_, is returned if is not equal to GIC_SPURIOUS_INTERRUPT (1023) else
`INTR_ID_UNAVAILABLE` is returned.
### Function : plat_ic_acknowledge_interrupt() [mandatory]
......@@ -1527,11 +1570,19 @@ 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.
This function in ARM standard platforms 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.
This function in ARM standard platforms using GICv2, 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.
In the case of ARM standard platforms using GICv3, if the API is invoked
from EL3, the function reads the system register `ICC_IAR0_EL1`, _Interrupt
Acknowledge Register group 0_. If the API is invoked from S-EL1, the function
reads the system register `ICC_IAR1_EL1`, _Interrupt Acknowledge Register
group 1_. The read changes the state of the highest pending interrupt from
pending to active in the interrupt controller. The value read is returned
and 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.
......@@ -1548,7 +1599,9 @@ finished. The id should be the same as the id returned by the
`plat_ic_acknowledge_interrupt()` API.
ARM standard platforms write the id to the _End of Interrupt Register_
(`GICC_EOIR`). This deactivates the corresponding interrupt in the interrupt
(`GICC_EOIR`) in case of GICv2, and to `ICC_EOIR0_EL1` or `ICC_EOIR1_EL1`
system register in case of GICv3 depending on where the API is invoked from,
EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt
controller.
The TSP uses this API to finish processing of the secure physical timer
......@@ -1564,13 +1617,17 @@ 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.
IC. This API must be invoked at EL3.
ARM standard platforms using GICv2 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.
This function in ARM standard platforms 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.
In the case of ARM standard platforms using GICv3, both the _Interrupt Group
Register_ (`GICD_IGROUPRn`) and _Interrupt Group Modifier Register_
(`GICD_IGRPMODRn`) is read to figure out whether the interrupt is configured
as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
3.5 Crash Reporting mechanism (in BL31)
......@@ -1716,7 +1773,8 @@ amount of open resources per driver.
_Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
[ARM GIC Architecture Specification]: http://arminfo.emea.arm.com/help/topic/com.arm.doc.ihi0048b/IHI0048B_gic_architecture_specification.pdf
[ARM GIC Architecture Specification 2.0]: http://arminfo.emea.arm.com/help/topic/com.arm.doc.ihi0048b/IHI0048B_gic_architecture_specification.pdf
[ARM GIC Architecture Specification 3.0]: http://arminfo.emea.arm.com/help/topic/com.arm.doc.ihi0069a/IHI0069A_gic_architecture_specification.pdf
[IMF Design Guide]: interrupt-framework-design.md
[User Guide]: user-guide.md
[FreeBSD]: http://www.freebsd.org
......
docs/user-guide.md
View file @ 81123e82
......@@ -13,6 +13,7 @@ Contents :
8. [Preparing the images to run on FVP](#8--preparing-the-images-to-run-on-fvp)
9. [Running the software on FVP](#9--running-the-software-on-fvp)
10. [Running the software on Juno](#10--running-the-software-on-juno)
11. [Changes required for booting Linux on FVP in GICv3 mode](#11--changes-required-for-booting-linux-on-fvp-in-gicv3-mode)
1. Introduction
......@@ -62,9 +63,14 @@ normal world firmware, Linux kernel and device tree, file system as well as any
additional micro-controller firmware required by the platform. This version of
Trusted Firmware is tested with the [Linaro 15.10 Release][Linaro Release Notes].
Note: Both the LSK kernel or the latest tracking kernel can be used along the
Note 1: Both the LSK kernel or the latest tracking kernel can be used with the
ARM Trusted Firmware, choose the one that best suits your needs.
Note 2: Currently to run the latest tracking kernel on FVP with GICv3 driver,
some modifications are required to UEFI. Refer
[here](#11--changes-required-for-booting-linux-on-fvp-in-gicv3-mode)
for more details.
The Trusted Firmware source code can then be found in the `arm-tf/` directory.
This is the full git repository cloned from Github. The revision checked out by
the `repo` tool is indicated by the manifest file. Depending on the manifest
......@@ -238,9 +244,10 @@ performed.
* `V`: Verbose build. If assigned anything other than 0, the build commands
are printed. Default is 0.
* `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM GIC
driver for implementing the platform GIC API. This API is used
* `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM
Legacy GIC driver for implementing the platform GIC API. This API is used
by the interrupt management framework. Default is 2 (that is, version 2.0).
This build option is deprecated.
* `ARM_CCI_PRODUCT_ID`: Choice of ARM CCI product used by the platform. This
is used to determine the number of valid slave interfaces available in the
......@@ -444,6 +451,16 @@ map is explained in the [Firmware Design].
set to 1 then Trusted Firmware will detect if an earlier version is in use.
Default is 1.
#### ARM FVP platform specific build options
* `FVP_USE_GIC_DRIVER` : Selects the GIC driver to be built. Options:
- `FVP_GICV2` : The GICv2 only driver is selected
- `FVP_GICV3` : The GICv3 only driver is selected (default option)
- `FVP_GICV3_LEGACY`: The Legacy GICv3 driver is selected (deprecated).
Note that if the FVP is configured for legacy VE memory map, then ARM
Trusted Firmware must be compiled with GICv2 only driver using
`FVP_USE_GIC_DRIVER=FVP_GICV2` build option.
### Creating a Firmware Image Package
......@@ -1096,8 +1113,9 @@ registers memory map (`0x1c010000`).
This register can be configured as described in the following sections.
NOTE: If the legacy VE GIC memory map is used, then the corresponding FDT and
BL33 images should be used.
NOTE: If the legacy VE GIC memory map is used, then Trusted Firmware must be
compiled with the GICv2 only driver, and the corresponding FDT and BL33 images
should be used.
#### Configuring AEMv8 Foundation FVP GIC for legacy VE memory map
......@@ -1255,6 +1273,23 @@ following command:
The Juno board should suspend to RAM and then wakeup after 10 seconds due to
wakeup interrupt from RTC.
11. Changes required for booting Linux on FVP in GICv3 mode
------------------------------------------------------------
In case the TF FVP port is built with the build option
`FVP_USE_GIC_DRIVER=FVP_GICV3`, then the GICv3 hardware cannot be used in
GICv2 legacy mode. The default build of UEFI for FVP in
[latest tracking kernel][Linaro Release Notes] configures GICv3 in GICv2 legacy
mode. This can be changed by setting the build flag
`gArmTokenSpaceGuid.PcdArmGicV3WithV2Legacy` to FALSE in
`uefi/edk2/ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc`.
Recompile UEFI as mentioned [here][FVP Instructions].
The GICv3 DTBs found in ARM Trusted Firmware source directory can be
used to test the GICv3 kernel on the respective FVP models.
- - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
......@@ -1266,6 +1301,7 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
[ARM Platforms Portal]: https://community.arm.com/groups/arm-development-platforms
[Linaro SW Instructions]: https://community.arm.com/docs/DOC-10803
[Juno Instructions]: https://community.arm.com/docs/DOC-10804
[FVP Instructions]: https://community.arm.com/docs/DOC-10831
[Juno Getting Started Guide]: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
[DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php
[mbed TLS Repository]: https://github.com/ARMmbed/mbedtls.git
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment