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 6996c17dbacf18992d10d19fdf7ba58b04de7946..210fb68ad399878ee1221f03b14a1b59d8416b61 100644 (file)
--- 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 37352659da64968ecab6dc46a754913a0a5ef5f4..4d690a978b8f22521b485232ef9e5d32e1396c77 100644 (file)
--- 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~