docs(ras): update RAS documentation
Add details about RAS error handling philosophies and its implementation
It also updates the tests introduced to verify them.
Signed-off-by: Manish Pandey <manish.pandey2@arm.com>
Change-Id: Iedc8c1e713dad05baadd58e5752df36fa00121a7
diff --git a/docs/components/ras.rst b/docs/components/ras.rst
index e237ebb..747367a 100644
--- a/docs/components/ras.rst
+++ b/docs/components/ras.rst
@@ -10,6 +10,9 @@
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 @@
EA's originating/attributed to NS world are handled first in NS and Kernel navigates
the std error records directly.
+- 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.
+
-**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**
+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 @@
- **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 @@
*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 0000000..cdfdcb9
--- /dev/null
+++ b/docs/resources/diagrams/bl31-exception-entry-error-synchronization.png
Binary files differ
