Merge "Fix broken links to various sections across docs" into integration
This commit is contained in:
commit
f0c24e3e80
|
@ -80,8 +80,8 @@ SMC interface
|
||||||
The communication with the 9p layer in BL31 is made through an SMC conduit
|
The communication with the 9p layer in BL31 is made through an SMC conduit
|
||||||
(`SMC Calling Convention`_), using a specific SiP Function Id. An NS
|
(`SMC Calling Convention`_), using a specific SiP Function Id. An NS
|
||||||
shared buffer is used to pass path string parameters, or e.g. to exchange
|
shared buffer is used to pass path string parameters, or e.g. to exchange
|
||||||
data on a read operation. Refer to `ARM SiP Services`_ for a description
|
data on a read operation. Refer to :ref:`ARM SiP Services <arm sip services>`
|
||||||
of the SMC interface.
|
for a description of the SMC interface.
|
||||||
|
|
||||||
Security considerations
|
Security considerations
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
|
@ -10,13 +10,9 @@ of the following exceptions when targeted at EL3:
|
||||||
- Asynchronous External Aborts
|
- Asynchronous External Aborts
|
||||||
|
|
||||||
|TF-A|'s handling of synchronous ``SMC`` exceptions raised from lower ELs is
|
|TF-A|'s handling of synchronous ``SMC`` exceptions raised from lower ELs is
|
||||||
described in the `Firmware Design document`__. However, the |EHF| changes the
|
described in the :ref:`Firmware Design document <handling-an-smc>`. However, the
|
||||||
semantics of `interrupt handling`__ and `synchronous exceptions`__ other than
|
|EHF| changes the semantics of `Interrupt handling`_ and :ref:`synchronous
|
||||||
SMCs.
|
exceptions <Effect on SMC calls>` other than SMCs.
|
||||||
|
|
||||||
.. __: firmware-design.rst#handling-an-smc
|
|
||||||
.. __: `Interrupt handling`_
|
|
||||||
.. __: `Effect on SMC calls`_
|
|
||||||
|
|
||||||
The |EHF| is selected by setting the build option ``EL3_EXCEPTION_HANDLING`` to
|
The |EHF| is selected by setting the build option ``EL3_EXCEPTION_HANDLING`` to
|
||||||
``1``, and is only available for AArch64 systems.
|
``1``, and is only available for AArch64 systems.
|
||||||
|
@ -77,10 +73,9 @@ On any given system, all of the above handling models may be employed
|
||||||
independently depending on platform choice and the nature of the exception
|
independently depending on platform choice and the nature of the exception
|
||||||
received.
|
received.
|
||||||
|
|
||||||
.. [#spd] Not to be confused with `Secure Payload Dispatcher`__, which is an
|
.. [#spd] Not to be confused with :ref:`Secure Payload Dispatcher
|
||||||
EL3 component that operates in EL3 on behalf of Secure OS.
|
<firmware_design_sel1_spd>`, which is an EL3 component that operates in EL3
|
||||||
|
on behalf of Secure OS.
|
||||||
.. __: firmware-design.rst#secure-el1-payloads-and-dispatchers
|
|
||||||
|
|
||||||
The role of Exception Handling Framework
|
The role of Exception Handling Framework
|
||||||
----------------------------------------
|
----------------------------------------
|
||||||
|
@ -139,6 +134,8 @@ unstacked in strictly the reverse order. For interrupts, the GIC ensures this is
|
||||||
the case; for non-interrupts, the |EHF| monitors and asserts this. See
|
the case; for non-interrupts, the |EHF| monitors and asserts this. See
|
||||||
`Transition of priority levels`_.
|
`Transition of priority levels`_.
|
||||||
|
|
||||||
|
.. _interrupt-handling:
|
||||||
|
|
||||||
Interrupt handling
|
Interrupt handling
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
|
@ -151,15 +148,12 @@ implications:
|
||||||
sufficient priority are signalled as FIQs, and therefore will be routed to
|
sufficient priority are signalled as FIQs, and therefore will be routed to
|
||||||
EL3. As a result, S-EL1 software cannot expect to handle Non-secure
|
EL3. As a result, S-EL1 software cannot expect to handle Non-secure
|
||||||
interrupts at S-EL1. Essentially, this deprecates the routing mode described
|
interrupts at S-EL1. Essentially, this deprecates the routing mode described
|
||||||
as `CSS=0, TEL3=0`__.
|
as :ref:`CSS=0, TEL3=0 <EL3 interrupts>`.
|
||||||
|
|
||||||
.. __: interrupt-framework-design.rst#el3-interrupts
|
|
||||||
|
|
||||||
In order for S-EL1 software to handle Non-secure interrupts while having
|
In order for S-EL1 software to handle Non-secure interrupts while having
|
||||||
|EHF| enabled, the dispatcher must adopt a model where Non-secure interrupts
|
|EHF| enabled, the dispatcher must adopt a model where Non-secure interrupts
|
||||||
are received at EL3, but are then `synchronously`__ handled over to S-EL1.
|
are received at EL3, but are then :ref:`synchronously <sp-synchronous-int>`
|
||||||
|
handled over to S-EL1.
|
||||||
.. __: interrupt-framework-design.rst#secure-payload
|
|
||||||
|
|
||||||
- On GICv2 systems, it's required that the build option ``GICV2_G0_FOR_EL3`` is
|
- On GICv2 systems, it's required that the build option ``GICV2_G0_FOR_EL3`` is
|
||||||
set to ``1`` so that *Group 0* interrupts target EL3.
|
set to ``1`` so that *Group 0* interrupts target EL3.
|
||||||
|
@ -283,15 +277,13 @@ The interrupt handler should have the following signature:
|
||||||
typedef int (*ehf_handler_t)(uint32_t intr_raw, uint32_t flags, void *handle,
|
typedef int (*ehf_handler_t)(uint32_t intr_raw, uint32_t flags, void *handle,
|
||||||
void *cookie);
|
void *cookie);
|
||||||
|
|
||||||
The parameters are as obtained from the top-level `EL3 interrupt handler`__.
|
The parameters are as obtained from the top-level :ref:`EL3 interrupt handler
|
||||||
|
<el3-runtime-firmware>`.
|
||||||
|
|
||||||
.. __: interrupt-framework-design.rst#el3-runtime-firmware
|
The :ref:`SDEI dispatcher<SDEI: Software Delegated Exception Interface>`, for
|
||||||
|
example, expects the platform to allocate two different priority levels—
|
||||||
The `SDEI dispatcher`__, for example, expects the platform to allocate two
|
``PLAT_SDEI_CRITICAL_PRI``, and ``PLAT_SDEI_NORMAL_PRI`` —and registers the
|
||||||
different priority levels—``PLAT_SDEI_CRITICAL_PRI``, and
|
same handler to handle both levels.
|
||||||
``PLAT_SDEI_NORMAL_PRI``—and registers the same handler to handle both levels.
|
|
||||||
|
|
||||||
.. __: sdei.rst
|
|
||||||
|
|
||||||
Interrupt handling example
|
Interrupt handling example
|
||||||
--------------------------
|
--------------------------
|
||||||
|
@ -374,11 +366,9 @@ Activating and Deactivating priorities
|
||||||
|
|
||||||
A priority level is said to be *active* when an exception of that priority is
|
A priority level is said to be *active* when an exception of that priority is
|
||||||
being handled: for interrupts, this is implied when the interrupt is
|
being handled: for interrupts, this is implied when the interrupt is
|
||||||
acknowledged; for non-interrupt exceptions, such as SErrors or `SDEI explicit
|
acknowledged; for non-interrupt exceptions, such as SErrors or :ref:`SDEI
|
||||||
dispatches`__, this has to be done via calling ``ehf_activate_priority()``. See
|
explicit dispatches <explicit-dispatch-of-events>`, this has to be done via
|
||||||
`Run-time flow`_.
|
calling ``ehf_activate_priority()``. See `Run-time flow`_.
|
||||||
|
|
||||||
.. __: sdei.rst#explicit-dispatch-of-events
|
|
||||||
|
|
||||||
Conversely, when the dispatcher has reached a logical resolution for the cause
|
Conversely, when the dispatcher has reached a logical resolution for the cause
|
||||||
of the exception, the corresponding priority level ought to be deactivated. As
|
of the exception, the corresponding priority level ought to be deactivated. As
|
||||||
|
@ -457,6 +447,8 @@ calls to these APIs are subject to the following conditions:
|
||||||
|
|
||||||
If these are violated, a panic will result.
|
If these are violated, a panic will result.
|
||||||
|
|
||||||
|
.. _Effect on SMC calls:
|
||||||
|
|
||||||
Effect on SMC calls
|
Effect on SMC calls
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
|
@ -542,10 +534,8 @@ The following is an example flow for interrupts:
|
||||||
interrupts belonging to different dispatchers.
|
interrupts belonging to different dispatchers.
|
||||||
|
|
||||||
#. The |EHF|, during its initialisation, registers a top-level interrupt handler
|
#. The |EHF|, during its initialisation, registers a top-level interrupt handler
|
||||||
with the `Interrupt Management Framework`__ for EL3 interrupts. This also
|
with the :ref:`Interrupt Management Framework<el3-runtime-firmware>` for EL3
|
||||||
results in setting the routing bits in ``SCR_EL3``.
|
interrupts. This also results in setting the routing bits in ``SCR_EL3``.
|
||||||
|
|
||||||
.. __: interrupt-framework-design.rst#el3-runtime-firmware
|
|
||||||
|
|
||||||
#. When an interrupt belonging to a dispatcher fires, GIC raises an EL3/Group 0
|
#. When an interrupt belonging to a dispatcher fires, GIC raises an EL3/Group 0
|
||||||
interrupt, and is taken to EL3.
|
interrupt, and is taken to EL3.
|
||||||
|
|
|
@ -286,6 +286,8 @@ inserts to order memory updates before updating mask, then writes to the GIC
|
||||||
*Priority Mask Register*, and make sure memory updates are visible before
|
*Priority Mask Register*, and make sure memory updates are visible before
|
||||||
potential trigger due to mask update.
|
potential trigger due to mask update.
|
||||||
|
|
||||||
|
.. _plat_ic_get_interrupt_id:
|
||||||
|
|
||||||
Function: unsigned int plat_ic_get_interrupt_id(unsigned int raw); [optional]
|
Function: unsigned int plat_ic_get_interrupt_id(unsigned int raw); [optional]
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
|
@ -205,6 +205,8 @@ will only allow SDEI calls to be made from:
|
||||||
|
|
||||||
See the function ``sdei_client_el()`` in ``sdei_private.h``.
|
See the function ``sdei_client_el()`` in ``sdei_private.h``.
|
||||||
|
|
||||||
|
.. _explicit-dispatch-of-events:
|
||||||
|
|
||||||
Explicit dispatch of events
|
Explicit dispatch of events
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
|
|
|
@ -6,11 +6,9 @@ Foreword
|
||||||
|
|
||||||
Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
|
Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
|
||||||
|
|
||||||
- SPM based on the PSA FF-A specification (`Secure Partition Manager`__).
|
- SPM based on the PSA FF-A specification (:ref:`Secure Partition Manager`).
|
||||||
- SPM based on the MM interface.
|
- SPM based on the MM interface.
|
||||||
|
|
||||||
.. __: secure-partition-manager.html
|
|
||||||
|
|
||||||
Both implementations differ in their architectures and only one can be selected
|
Both implementations differ in their architectures and only one can be selected
|
||||||
at build time.
|
at build time.
|
||||||
|
|
||||||
|
|
|
@ -833,9 +833,7 @@ References
|
||||||
|
|
||||||
.. _[2]:
|
.. _[2]:
|
||||||
|
|
||||||
[2] `Secure Partition Manager using MM interface`__
|
[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>`
|
||||||
|
|
||||||
.. __: secure-partition-manager-mm.html
|
|
||||||
|
|
||||||
.. _[3]:
|
.. _[3]:
|
||||||
|
|
||||||
|
|
|
@ -957,6 +957,8 @@ Function ID call type and OEN onto a specific service handler in the
|
||||||
|
|
||||||
|Image 1|
|
|Image 1|
|
||||||
|
|
||||||
|
.. _handling-an-smc:
|
||||||
|
|
||||||
Handling an SMC
|
Handling an SMC
|
||||||
~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -1300,6 +1302,8 @@ In other words, the reset handler should be able to detect whether an action has
|
||||||
already been performed and act as appropriate. Possible courses of actions are,
|
already been performed and act as appropriate. Possible courses of actions are,
|
||||||
e.g. skip the action the second time, or undo/redo it.
|
e.g. skip the action the second time, or undo/redo it.
|
||||||
|
|
||||||
|
.. _configuring-secure-interrupts:
|
||||||
|
|
||||||
Configuring secure interrupts
|
Configuring secure interrupts
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
||||||
|
|
|
@ -150,10 +150,8 @@ EL3 interrupts
|
||||||
|
|
||||||
However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is
|
However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is
|
||||||
invalid as EL3 interrupts are unconditionally routed to EL3, and EL3
|
invalid as EL3 interrupts are unconditionally routed to EL3, and EL3
|
||||||
interrupts will always preempt Secure EL1/EL0 execution. See `exception
|
interrupts will always preempt Secure EL1/EL0 execution. See :ref:`exception
|
||||||
handling`__ documentation.
|
handling<interrupt-handling>` documentation.
|
||||||
|
|
||||||
.. __: exception-handling.rst#interrupt-handling
|
|
||||||
|
|
||||||
#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in
|
#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in
|
||||||
Secure-EL1/Secure-EL0. This is a valid routing model as secure software
|
Secure-EL1/Secure-EL0. This is a valid routing model as secure software
|
||||||
|
@ -303,6 +301,8 @@ This section describes in detail the role of each software component (see
|
||||||
`Software components`_) during the registration of a handler for an interrupt
|
`Software components`_) during the registration of a handler for an interrupt
|
||||||
type.
|
type.
|
||||||
|
|
||||||
|
.. _el3-runtime-firmware:
|
||||||
|
|
||||||
EL3 runtime firmware
|
EL3 runtime firmware
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -901,14 +901,14 @@ it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the
|
||||||
|
|
||||||
|Image 2|
|
|Image 2|
|
||||||
|
|
||||||
Secure payload
|
.. _sp-synchronous-int:
|
||||||
~~~~~~~~~~~~~~
|
|
||||||
|
Secure payload interrupt handling
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The SP should implement one or both of the synchronous and asynchronous
|
The SP should implement one or both of the synchronous and asynchronous
|
||||||
interrupt handling models depending upon the interrupt routing model it has
|
interrupt handling models depending upon the interrupt routing model it has
|
||||||
chosen (as described in section `Secure Payload`__).
|
chosen (as described in section :ref:`Secure Payload <sp-int-registration>`).
|
||||||
|
|
||||||
.. __: #sp-int-registration
|
|
||||||
|
|
||||||
In the synchronous model, it should begin handling a Secure-EL1 interrupt after
|
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
|
receiving control from the SPD service at an entrypoint agreed upon during build
|
||||||
|
|
|
@ -346,16 +346,14 @@ Common build options
|
||||||
- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
|
- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
|
||||||
inherent support for specific EL3 type interrupts. Setting this build option
|
inherent support for specific EL3 type interrupts. Setting this build option
|
||||||
to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
|
to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
|
||||||
by `platform abstraction layer`__ and `Interrupt Management Framework`__.
|
by :ref:`platform abstraction layer<platform Interrupt Controller API>` and
|
||||||
|
:ref:`Interrupt Management Framework<Interrupt Management Framework>`.
|
||||||
This allows GICv2 platforms to enable features requiring EL3 interrupt type.
|
This allows GICv2 platforms to enable features requiring EL3 interrupt type.
|
||||||
This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
|
This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
|
||||||
the Secure Payload interrupts needs to be synchronously handed over to Secure
|
the Secure Payload interrupts needs to be synchronously handed over to Secure
|
||||||
EL1 for handling. The default value of this option is ``0``, which means the
|
EL1 for handling. The default value of this option is ``0``, which means the
|
||||||
Group 0 interrupts are assumed to be handled by Secure EL1.
|
Group 0 interrupts are assumed to be handled by Secure EL1.
|
||||||
|
|
||||||
.. __: platform-interrupt-controller-API.rst
|
|
||||||
.. __: interrupt-framework-design.rst
|
|
||||||
|
|
||||||
- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError
|
- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError
|
||||||
Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to
|
Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to
|
||||||
``0`` (default), these exceptions will be trapped in the current exception
|
``0`` (default), these exceptions will be trapped in the current exception
|
||||||
|
|
|
@ -2482,9 +2482,7 @@ FVP can be configured to use either GICv2 or GICv3 depending on the build flag
|
||||||
``FVP_USE_GIC_DRIVER`` (See :ref:`build_options_arm_fvp_platform` for more
|
``FVP_USE_GIC_DRIVER`` (See :ref:`build_options_arm_fvp_platform` for more
|
||||||
details).
|
details).
|
||||||
|
|
||||||
See also: `Interrupt Controller Abstraction APIs`__.
|
See also: :ref:`Interrupt Controller Abstraction APIs<Platform Interrupt Controller API>`.
|
||||||
|
|
||||||
.. __: ../design/platform-interrupt-controller-API.rst
|
|
||||||
|
|
||||||
Function : plat_interrupt_type_to_line() [mandatory]
|
Function : plat_interrupt_type_to_line() [mandatory]
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
@ -2609,9 +2607,7 @@ 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 raw, unmodified
|
the highest pending interrupt has begun. It should return the raw, unmodified
|
||||||
value obtained from the interrupt controller when acknowledging an interrupt.
|
value obtained from the interrupt controller when acknowledging an interrupt.
|
||||||
The actual interrupt number shall be extracted from this raw value using the API
|
The actual interrupt number shall be extracted from this raw value using the API
|
||||||
`plat_ic_get_interrupt_id()`__.
|
`plat_ic_get_interrupt_id()<plat_ic_get_interrupt_id>`.
|
||||||
|
|
||||||
.. __: ../design/platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
|
|
||||||
|
|
||||||
This function in Arm standard platforms using GICv2, reads the *Interrupt
|
This function in Arm standard platforms using GICv2, reads the *Interrupt
|
||||||
Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
|
Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
|
||||||
|
|
|
@ -635,7 +635,7 @@ boot Linux with 4 CPUs using the AArch32 build of TF-A.
|
||||||
|
|
||||||
*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
|
*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
|
||||||
|
|
||||||
.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
|
.. _TB_FW_CONFIG for FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
|
||||||
.. _Arm's website: `FVP models`_
|
.. _Arm's website: `FVP models`_
|
||||||
.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
|
.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
|
||||||
.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06
|
.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06
|
||||||
|
|
Loading…
Reference in New Issue