diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/components/ras.rst | 105 | ||||
-rw-r--r-- | docs/getting_started/build-options.rst | 9 | ||||
-rw-r--r-- | docs/porting-guide.rst | 4 |
3 files changed, 77 insertions, 41 deletions
diff --git a/docs/components/ras.rst b/docs/components/ras.rst index 871be2d76..8d003452c 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -1,45 +1,89 @@ Reliability, Availability, and Serviceability (RAS) Extensions -============================================================== +************************************************************** This document describes |TF-A| support for Arm Reliability, Availability, and Serviceability (RAS) extensions. RAS is a mandatory extension for Armv8.2 and later CPUs, and also an optional extension to the base Armv8.0 architecture. -In conjunction with the |EHF|, support for RAS extension enables firmware-first -paradigm for handling platform errors: exceptions resulting from errors in -Non-secure world are routed to and handled in EL3. -Said errors are Synchronous External Abort (SEA), Asynchronous External Abort -(signalled as SErrors), Fault Handling and Error Recovery interrupts. -The |EHF| document mentions various :ref:`error handling -use-cases <delegation-use-cases>` . - For the description of Arm RAS extensions, Standard Error Records, and the precise definition of RAS terminology, please refer to the Arm Architecture -Reference Manual. The rest of this document assumes familiarity with -architecture and terminology. +Reference Manual and `RAS Supplement`_. The rest of this document assumes +familiarity with architecture and terminology. + +There are two philosophies for handling RAS errors from Non-secure world point +of view. + +- :ref:`Firmware First Handling (FFH)` +- :ref:`Kernel First Handling (KFH)` + +.. _Firmware First Handling (FFH): + +Firmware First Handling (FFH) +============================= + +Introduction +------------ + +EA’s and Error interrupts corresponding to NS nodes are handled first in firmware + +- Errors signaled back to NS world via suitable mechanism +- Kernel is prohibited from accessing the RAS error records directly +- Firmware creates CPER records for kernel to navigate and process +- Firmware signals error back to Kernel via SDEI Overview -------- -As mentioned above, the RAS support in |TF-A| enables routing to and handling of -exceptions resulting from platform errors in EL3. It allows the platform to -define an External Abort handler, and to register RAS nodes and interrupts. RAS -framework also provides `helpers`__ for accessing Standard Error Records as -introduced by the RAS extensions. +FFH works in conjunction with `Exception Handling Framework`. Exceptions resulting from +errors in Non-secure world are routed to and handled in EL3. Said errors are Synchronous +External Abort (SEA), Asynchronous External Abort (signalled as SErrors), Fault Handling +and Error Recovery interrupts. +RAS Framework in TF-A allows the platform to define an external abort handler and to +register RAS nodes and interrupts. It also provides `helpers`__ for accessing Standard +Error Records as introduced by the RAS extensions + .. __: `Standard Error Record helpers`_ -The build option ``RAS_EXTENSION`` when set to ``1`` includes the RAS in run -time firmware; ``EL3_EXCEPTION_HANDLING`` and ``HANDLE_EA_EL3_FIRST_NS`` must also -be set ``1``. ``RAS_TRAP_NS_ERR_REC_ACCESS`` controls the access to the RAS -error record registers from Non-secure. +.. _Kernel First Handling (KFH): + +Kernel First Handling (KFH) +=========================== + +Introduction +------------ + +EA's originating/attributed to NS world are handled first in NS and Kernel navigates +the std error records directly. + +**KFH can be supported in a platform without TF-A being aware of it but there are few +corner cases where TF-A needs to have special handling, which is currently missing and +will be added in future** + +TF-A build options +================== + +- **ENABLE_FEAT_RAS**: Manage FEAT_RAS extension when switching the world. +- **RAS_FFH_SUPPORT**: Pull in necessary framework and platform hooks for Firmware first + handling(FFH) of RAS errors. +- **RAS_TRAP_NS_ERR_REC_ACCESS**: Trap Non-secure access of RAS error record registers. +- **RAS_EXTENSION**: Deprecated macro, equivalent to ENABLE_FEAT_RAS and RAS_FFH_SUPPORT + put together. + +RAS feature has dependency on some other TF-A build flags + +- **EL3_EXCEPTION_HANDLING**: Required for FFH +- **HANDLE_EA_EL3_FIRST_NS**: Required for FFH +- **FAULT_INJECTION_SUPPORT**: Required for testing RAS feature on fvp platform + +RAS Framework +============= + .. _ras-figure: .. image:: ../resources/diagrams/draw.io/ras.svg -See more on `Engaging the RAS framework`_. - Platform APIs ------------- @@ -191,19 +235,10 @@ doesn't return. Engaging the RAS framework -------------------------- -Enabling RAS support is a platform choice constructed from three distinct, but -related, build options: - -- ``RAS_EXTENSION=1`` includes the RAS framework in the run time firmware; - -- ``EL3_EXCEPTION_HANDLING=1`` enables handling of exceptions at EL3. See - `Interaction with Exception Handling Framework`_; - -- ``HANDLE_EA_EL3_FIRST_NS=1`` enables routing of External Aborts and SErrors, - resulting from errors in NS world, to EL3. +Enabling RAS support is a platform choice The RAS support in |TF-A| introduces a default implementation of -``plat_ea_handler``, the External Abort handler in EL3. When ``RAS_EXTENSION`` +``plat_ea_handler``, the External Abort handler in EL3. When ``RAS_FFH_SUPPORT`` is set to ``1``, it'll first call ``ras_ea_handler()`` function, which is the top-level RAS exception handler. ``ras_ea_handler`` is responsible for iterating to through platform-supplied error records, probe them, and when an error is @@ -239,4 +274,6 @@ for non-interrupt exceptions, they're explicit using :ref:`EHF APIs -------------- -*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2018-2023, Arm Limited and Contributors. All rights reserved.* + +.. _RAS Supplement: https://developer.arm.com/documentation/ddi0587/latest diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst index 6dd4ed21a..4eafb392b 100644 --- a/docs/getting_started/build-options.rst +++ b/docs/getting_started/build-options.rst @@ -775,15 +775,14 @@ Common build options - ``PSCI_OS_INIT_MODE``: Boolean flag to enable support for optional PSCI OS-initiated mode. This option defaults to 0. -- ``RAS_EXTENSION``: Numeric value to enable Armv8.2 RAS features. RAS features +- ``ENABLE_FEAT_RAS``: Numeric value to enable Armv8.2 RAS features. RAS features are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2 or later CPUs. This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism. - When ``RAS_EXTENSION`` is set to ``1``, ``HANDLE_EA_EL3_FIRST_NS`` must also be - set to ``1``. - - This option is disabled by default. +- ``RAS_FFH_SUPPORT``: Support to enable Firmware first handling of RAS errors + originating from NS world. When ``RAS_FFH_SUPPORT`` is set to ``1``, + ``HANDLE_EA_EL3_FIRST_NS`` and ``ENABLE_FEAT_RAS`` must also be set to ``1``. - ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 1225a9f79..1250071ef 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -3418,11 +3418,11 @@ The third parameter (``void *cookie``) is unused for now. The fourth parameter (``uint64_t flags``) indicates the preempted security state. These parameters are received from the top-level exception handler. -If ``RAS_EXTENSION`` is set to ``1``, the default implementation of this +If ``RAS_FFH_SUPPORT`` is set to ``1``, the default implementation of this function iterates through RAS handlers registered by the platform. If any of the RAS handlers resolve the External Abort, no further action is taken. -If ``RAS_EXTENSION`` is set to ``0``, or if none of the platform RAS handlers +If ``RAS_FFH_SUPPORT`` is set to ``0``, or if none of the platform RAS handlers could resolve the External Abort, the default implementation prints an error message, and panics. |