From: Manish Pandey <manish.pandey2@arm.com>
Date: Wed, 2 Nov 2022 16:30:09 +0000 (+0000)
Subject: docs: document do_panic() and panic() helper functions
X-Git-Tag: baikal/aarch64/sdk5.9~26^2
X-Git-Url: https://git.baikalelectronics.ru/?a=commitdiff_plain;h=5988a807673c861ea2b14dbedfc9e25e0a9a6d4a;p=arm-tf.git

docs: document do_panic() and panic() helper functions

panic() and do_panic() are widely used helper functions called when
encountering a critical failure that cannot be recovered from.
Document them in porting guide. Also, remove panic() documentation
from PSCI guide(where it is unused anyways).

Signed-off-by: Manish Pandey <manish.pandey2@arm.com>
Change-Id: Ib0965cce56c03d0de5ac0d05d5714a6942793ede
---

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 6996c17db..210fb68ad 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -3156,6 +3156,34 @@ Register* (``GICD_IGROUPRn``) and *Interrupt Group Modifier Register*
 (``GICD_IGRPMODRn``) is read to figure out whether the interrupt is configured
 as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
 
+Common helper functions
+-----------------------
+
+Function : do_panic()
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : void
+    Return   : void
+
+This API is called from assembly files when encountering a critical failure that
+cannot be recovered from. It also invokes elx_panic() which allows to report a
+crash from lower exception level. This function assumes that it is invoked from
+a C runtime environment i.e. valid stack exists. This call **must not** return.
+
+Function : panic()
+~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : void
+    Return   : void
+
+This API called from C files when encountering a critical failure that cannot
+be recovered from. This function in turn prints backtrace (if enabled) and calls
+do_panic(). This call **must not** return.
+
 Crash Reporting mechanism (in BL31)
 -----------------------------------
 
diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst
index 37352659d..4d690a978 100644
--- a/docs/getting_started/psci-lib-integration-guide.rst
+++ b/docs/getting_started/psci-lib-integration-guide.rst
@@ -337,16 +337,6 @@ at address ``addr`` (first argument) address and of size ``size`` (second argume
 This function invalidates (flushes) the data cache for memory at address
 ``addr`` (first argument) address and of size ``size`` (second argument).
 
-**Function : do_panic()**
-
-::
-
-    Argument : void
-    Return   : void
-
-This function will be called by the PSCI library on encountering a critical
-failure that cannot be recovered from. This function **must not** return.
-
 CPU Context management API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~