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

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