diff --git a/docs/components/ras.rst b/docs/components/ras.rst index e237ebb92..747367a4c 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -10,6 +10,9 @@ precise definition of RAS terminology, please refer to the Arm Architecture Reference Manual and `RAS Supplement`_. The rest of this document assumes familiarity with architecture and terminology. +**IMPORTANT NOTE**: TF-A implementation assumes that if RAS extension is present +then FEAT_IESB is also implmented. + There are two philosophies for handling RAS errors from Non-secure world point of view. @@ -56,9 +59,19 @@ 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** +- KFH is the default handling mode if platform does not explicitly enable FFH mode. +- KFH mode does not need any EL3 involvement except for the reflection of errors back + to lower EL. This happens when there is an error (EA) in the system which is not yet + signaled to PE while executing at lower EL. During entry into EL3 the errors (EA) are + synchronized causing async EA to pend at EL3. + +Error Syncronization at EL3 entry +================================= + +During entry to EL3 from lower EL, if there is any pending async EAs they are either +reflected back to lower EL (KFH) or handled in EL3 itself (FFH). + +|Image 1| TF-A build options ================== @@ -78,6 +91,55 @@ RAS feature has dependency on some other TF-A build flags - **EL3_EXCEPTION_HANDLING**: Required for FFH - **FAULT_INJECTION_SUPPORT**: Required for testing RAS feature on fvp platform +TF-A Tests +========== + +RAS functionality is regularly tested in TF-A CI using `RAS test group`_ which has multiple +configurations for testing lower EL External aborts. + +All the tests are written in TF-A tests which runs as NS-EL2 payload. + +- **FFH without RAS extension** + + *fvp-ea-ffh,fvp-ea-ffh:fvp-tftf-fip.tftf-aemv8a-debug* + + Couple of tests, one each for sync EA and async EA from lower EL which gets handled in El3. + Inject External aborts(sync/async) which traps in EL3, FVP has a handler which gracefully + handles these errors and returns back to TF-A Tests + + Build Configs : **HANDLE_EA_EL3_FIRST_NS** , **PLATFORM_TEST_EA_FFH** + +- **FFH with RAS extension** + + Three Tests : + + - *fvp-ras-ffh,fvp-single-fault:fvp-tftf-fip.tftf-aemv8a.fi-debug* + + Inject an unrecoverable RAS error, which gets handled in EL3. + + - *fvp-ras-ffh,fvp-uncontainable:fvp-tftf.fault-fip.tftf-aemv8a.fi-debug* + + Inject uncontainable RAS errors which causes platform to panic. + + - *fvp-ras-ffh,fvp-ras-ffh-nested:fvp-tftf-fip.tftf-ras_ffh_nested-aemv8a.fi-debug* + + Test nested exception handling at El3 for synchronized async EAs. Inject an SError in lower EL + which remain pending until we enter EL3 through SMC call. At EL3 entry on encountering a pending + async EA it will handle the async EA first (nested exception) before handling the original SMC call. + +- **KFH with RAS extension** + + Couple of tests in the group : + + - *fvp-ras-kfh,fvp-ras-kfh:fvp-tftf-fip.tftf-aemv8a.fi-debug* + + Inject and handle RAS errors in TF-A tests (no El3 involvement) + + - *fvp-ras-kfh,fvp-ras-kfh-reflect:fvp-tftf-fip.tftf-ras_kfh_reflection-aemv8a.fi-debug* + + Reflection of synchronized errors from EL3 to TF-A tests, two tests one each for reflecting + in IRQ and SMC path. + RAS Framework ============= @@ -279,3 +341,6 @@ for non-interrupt exceptions, they're explicit using :ref:`EHF APIs *Copyright (c) 2018-2023, Arm Limited and Contributors. All rights reserved.* .. _RAS Supplement: https://developer.arm.com/documentation/ddi0587/latest +.. _RAS Test group: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/tree/group/tf-l3-boot-tests-ras?h=refs/heads/master + +.. |Image 1| image:: ../resources/diagrams/bl31-exception-entry-error-synchronization.png diff --git a/docs/resources/diagrams/bl31-exception-entry-error-synchronization.png b/docs/resources/diagrams/bl31-exception-entry-error-synchronization.png new file mode 100644 index 000000000..cdfdcb910 Binary files /dev/null and b/docs/resources/diagrams/bl31-exception-entry-error-synchronization.png differ