c-user: Split up fatal error manager

This makes it easier to automatically generate parts of the module
documentation in the future.

Update #3993.

7 files changed, 321 insertions, 302 deletions

diff --git a/c-user/fatal_error.rst b/c-user/fatal-error/background.rst
index 81cfa0c..571da10 100644
--- a/c-user/fatal_error.rst
+++ b/c-user/fatal-error/background.rst
@@ -2,35 +2,6 @@
 
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
-.. index:: fatal errors
-
-.. _fatal_error_manager:
-
-Fatal Error Manager
-*******************
-
-Introduction
-============
-
-The fatal error manager processes all fatal or irrecoverable errors and other
-sources of system termination (for example after :c:func:`exit()`).  Fatal
-errors are identified by the (fatal source, error code) pair.  The directives
-provided by the fatal error manager are:
-
-- rtems_fatal_ - Invoke the fatal error handler
-
-- rtems_panic_ - Print a message and invoke the fatal error handler
-
-- rtems_shutdown_executive_ - Shutdown RTEMS
-
-- rtems_exception_frame_print_ - Print the CPU exception frame
-
-- rtems_fatal_source_text_ - Return the fatal source text
-
-- rtems_internal_error_text_ - Return the error code text
-
-- rtems_fatal_error_occurred_ - Invoke the fatal error handler (deprecated)
-
 Background
 ==========
 
@@ -383,274 +354,3 @@ INTERNAL_ERROR_TOO_LARGE_TLS_SIZE (41)
     :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE <CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE>`.
     You can get the thread-local storage size of an application using the RTEMS
     tool ``rtems-execinfo``.
-
-Operations
-==========
-
-.. index:: _Terminate
-
-.. _Terminate:
-
-Announcing a Fatal Error
-------------------------
-
-The :c:func:`_Terminate()` internal error handler is invoked when the
-application or the executive itself determines that a fatal error has occurred
-or a final system state is reached (for example after :c:func:`rtems_fatal()`
-or :c:func:`exit()`).
-
-The first action of the internal error handler is to call the fatal extension of
-the user extensions.  For the initial extensions the following conditions are
-required
-
-- a valid stack pointer and enough stack space,
-
-- a valid code memory, and
-
-- valid read-only data.
-
-For the initial extensions the read-write data (including .bss segment) is not
-required on single processor configurations.  In SMP configurations, however,
-the read-write data must be initialized since this function must determine the
-state of the other processors and request them to shut-down if necessary.
-
-Non-initial extensions require in addition valid read-write data.  The board
-support package (BSP) may install an initial extension that performs a system
-reset.  In this case the non-initial extensions will be not called.
-
-The fatal extensions are called with three parameters:
-
-- the fatal source,
-
-- a legacy parameter which is always false, and
-
-- an error code with a fatal source dependent content.
-
-Once all fatal extensions executed, the error information will be stored to
-:c:data:`_Internal_errors_What_happened` and the system state is set to
-:c:macro:`SYSTEM_STATE_TERMINATED`.
-
-The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`.
-
-Directives
-==========
-
-This section details the fatal error manager's directives.  A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal
-
-.. _rtems_fatal:
-
-FATAL - Invoke the fatal error handler
---------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        void rtems_fatal(
-          rtems_fatal_source fatal_source,
-          rtems_fatal_code   error_code
-        ) RTEMS_NO_RETURN;
-
-DIRECTIVE STATUS CODES:
-    NONE - This function will not return to the caller.
-
-DESCRIPTION:
-    This directive terminates the system.
-
-NOTE:
-    Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
-    called.  Use :c:func:`exit()` in case these handlers should be invoked.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: panic
-.. index:: rtems_panic
-
-.. _rtems_panic:
-
-PANIC - Print a message and invoke the fatal error handler
-----------------------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        void rtems_panic(
-          const char *fmt,
-          ...
-        ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
-
-DIRECTIVE STATUS CODES:
-    NONE - This function will not return to the caller.
-
-DESCRIPTION:
-    This directive prints a message via :c:func:`printk` specified by the
-    format and optional parameters and then terminates the system with the
-    :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source.  The fatal code is set to
-    the format string address.
-
-NOTE:
-    Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
-    called.  Use :c:func:`exit()` in case these handlers should be invoked.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: shutdown RTEMS
-.. index:: rtems_shutdown_executive
-
-.. _rtems_shutdown_executive:
-
-SHUTDOWN_EXECUTIVE - Shutdown RTEMS
------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        void rtems_shutdown_executive(
-            uint32_t result
-        );
-
-DIRECTIVE STATUS CODES:
-    NONE - This function will not return to the caller.
-
-DESCRIPTION:
-    This directive is called when the application wishes to shutdown RTEMS.
-    The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
-    and the specified ``result`` code.
-
-NOTES:
-    This directive *must* be the last RTEMS directive invoked by an application
-    and it *does not return* to the caller.
-
-    This directive may be called any time.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: exception frame
-.. index:: rtems_exception_frame_print
-
-.. _rtems_exception_frame_print:
-
-EXCEPTION_FRAME_PRINT - Prints the exception frame
---------------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        void rtems_exception_frame_print(
-            const rtems_exception_frame *frame
-        );
-
-DIRECTIVE STATUS CODES:
-    NONE
-
-DESCRIPTION:
-    Prints the exception frame via ``printk()``.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: fatal error
-.. index:: rtems_fatal_source_text
-
-.. _rtems_fatal_source_text:
-
-FATAL_SOURCE_TEXT - Returns a text for a fatal source
------------------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        const char *rtems_fatal_source_text(
-            rtems_fatal_source source
-        );
-
-DIRECTIVE STATUS CODES:
-    The fatal source text or "?" in case the passed fatal source is invalid.
-
-DESCRIPTION:
-    Returns a text for a fatal source.  The text for fatal source is the
-    enumerator constant.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: fatal error
-.. index:: rtems_internal_error_text
-
-.. _rtems_internal_error_text:
-
-INTERNAL_ERROR_TEXT - Returns a text for an internal error code
----------------------------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        const char *rtems_internal_error_text(
-            rtems_fatal_code error
-        );
-
-DIRECTIVE STATUS CODES:
-    The error code text or "?" in case the passed error code is invalid.
-
-DESCRIPTION:
-    Returns a text for an internal error code.  The text for each internal
-    error code is the enumerator constant.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal_error_occurred
-
-.. _rtems_fatal_error_occurred:
-
-FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
-------------------------------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        void rtems_fatal_error_occurred(
-            uint32_t  the_error
-        ) RTEMS_NO_RETURN;
-
-DIRECTIVE STATUS CODES:
-    NONE - This function will not return to the caller.
-
-DESCRIPTION:
-    This directive processes fatal errors.  If the FATAL error extension is
-    defined in the configuration table, then the user-defined error extension
-    is called.  If configured and the provided FATAL error extension returns,
-    then the RTEMS default error handler is invoked.  This directive can be
-    invoked by RTEMS or by the user's application code including initialization
-    tasks, other tasks, and ISRs.
-
-NOTES:
-    This directive is deprecated and should not be used in new code.
-
-    This directive supports local operations only.
-
-    Unless the user-defined error extension takes special actions such as
-    restarting the calling task, this directive WILL NOT RETURN to the caller.
-
-    The user-defined extension for this directive may wish to initiate a global
-    shutdown.
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst
new file mode 100644
index 0000000..2d9a476
--- /dev/null
+++ b/c-user/fatal-error/directives.rst
@@ -0,0 +1,226 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+This section details the fatal error manager's directives.  A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: announce fatal error
+.. index:: fatal error, announce
+.. index:: rtems_fatal
+
+.. _rtems_fatal:
+
+FATAL - Invoke the fatal error handler
+--------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_fatal(
+          rtems_fatal_source fatal_source,
+          rtems_fatal_code   error_code
+        ) RTEMS_NO_RETURN;
+
+DIRECTIVE STATUS CODES:
+    NONE - This function will not return to the caller.
+
+DESCRIPTION:
+    This directive terminates the system.
+
+NOTE:
+    Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
+    called.  Use :c:func:`exit()` in case these handlers should be invoked.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: panic
+.. index:: rtems_panic
+
+.. _rtems_panic:
+
+PANIC - Print a message and invoke the fatal error handler
+----------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_panic(
+          const char *fmt,
+          ...
+        ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
+
+DIRECTIVE STATUS CODES:
+    NONE - This function will not return to the caller.
+
+DESCRIPTION:
+    This directive prints a message via :c:func:`printk` specified by the
+    format and optional parameters and then terminates the system with the
+    :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source.  The fatal code is set to
+    the format string address.
+
+NOTE:
+    Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
+    called.  Use :c:func:`exit()` in case these handlers should be invoked.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: shutdown RTEMS
+.. index:: rtems_shutdown_executive
+
+.. _rtems_shutdown_executive:
+
+SHUTDOWN_EXECUTIVE - Shutdown RTEMS
+-----------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_shutdown_executive(
+            uint32_t result
+        );
+
+DIRECTIVE STATUS CODES:
+    NONE - This function will not return to the caller.
+
+DESCRIPTION:
+    This directive is called when the application wishes to shutdown RTEMS.
+    The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
+    and the specified ``result`` code.
+
+NOTES:
+    This directive *must* be the last RTEMS directive invoked by an application
+    and it *does not return* to the caller.
+
+    This directive may be called any time.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: exception frame
+.. index:: rtems_exception_frame_print
+
+.. _rtems_exception_frame_print:
+
+EXCEPTION_FRAME_PRINT - Prints the exception frame
+--------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_exception_frame_print(
+            const rtems_exception_frame *frame
+        );
+
+DIRECTIVE STATUS CODES:
+    NONE
+
+DESCRIPTION:
+    Prints the exception frame via ``printk()``.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: fatal error
+.. index:: rtems_fatal_source_text
+
+.. _rtems_fatal_source_text:
+
+FATAL_SOURCE_TEXT - Returns a text for a fatal source
+-----------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        const char *rtems_fatal_source_text(
+            rtems_fatal_source source
+        );
+
+DIRECTIVE STATUS CODES:
+    The fatal source text or "?" in case the passed fatal source is invalid.
+
+DESCRIPTION:
+    Returns a text for a fatal source.  The text for fatal source is the
+    enumerator constant.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: fatal error
+.. index:: rtems_internal_error_text
+
+.. _rtems_internal_error_text:
+
+INTERNAL_ERROR_TEXT - Returns a text for an internal error code
+---------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        const char *rtems_internal_error_text(
+            rtems_fatal_code error
+        );
+
+DIRECTIVE STATUS CODES:
+    The error code text or "?" in case the passed error code is invalid.
+
+DESCRIPTION:
+    Returns a text for an internal error code.  The text for each internal
+    error code is the enumerator constant.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: announce fatal error
+.. index:: fatal error, announce
+.. index:: rtems_fatal_error_occurred
+
+.. _rtems_fatal_error_occurred:
+
+FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
+------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_fatal_error_occurred(
+            uint32_t  the_error
+        ) RTEMS_NO_RETURN;
+
+DIRECTIVE STATUS CODES:
+    NONE - This function will not return to the caller.
+
+DESCRIPTION:
+    This directive processes fatal errors.  If the FATAL error extension is
+    defined in the configuration table, then the user-defined error extension
+    is called.  If configured and the provided FATAL error extension returns,
+    then the RTEMS default error handler is invoked.  This directive can be
+    invoked by RTEMS or by the user's application code including initialization
+    tasks, other tasks, and ISRs.
+
+NOTES:
+    This directive is deprecated and should not be used in new code.
+
+    This directive supports local operations only.
+
+    Unless the user-defined error extension takes special actions such as
+    restarting the calling task, this directive WILL NOT RETURN to the caller.
+
+    The user-defined extension for this directive may wish to initiate a global
+    shutdown.
diff --git a/c-user/fatal-error/index.rst b/c-user/fatal-error/index.rst
new file mode 100644
index 0000000..89cbe30
--- /dev/null
+++ b/c-user/fatal-error/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: fatal errors
+
+.. _RTEMSAPIClassicFatal:
+
+Fatal Error Manager
+*******************
+
+.. toctree::
+
+    introduction
+    background
+    operations
+    directives
diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst
new file mode 100644
index 0000000..d862d4e
--- /dev/null
+++ b/c-user/fatal-error/introduction.rst
@@ -0,0 +1,25 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The fatal error manager processes all fatal or irrecoverable errors and other
+sources of system termination (for example after :c:func:`exit()`).  Fatal
+errors are identified by the (fatal source, error code) pair.  The directives
+provided by the fatal error manager are:
+
+- :ref:`rtems_fatal`
+
+- :ref:`rtems_panic`
+
+- :ref:`rtems_shutdown_executive`
+
+- :ref:`rtems_exception_frame_print`
+
+- :ref:`rtems_fatal_source_text`
+
+- :ref:`rtems_internal_error_text`
+
+- :ref:`rtems_fatal_error_occurred`
diff --git a/c-user/fatal-error/operations.rst b/c-user/fatal-error/operations.rst
new file mode 100644
index 0000000..77753d6
--- /dev/null
+++ b/c-user/fatal-error/operations.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+.. index:: _Terminate
+
+.. _Terminate:
+
+Announcing a Fatal Error
+------------------------
+
+The :c:func:`_Terminate()` internal error handler is invoked when the
+application or the executive itself determines that a fatal error has occurred
+or a final system state is reached (for example after :c:func:`rtems_fatal()`
+or :c:func:`exit()`).
+
+The first action of the internal error handler is to call the fatal extension of
+the user extensions.  For the initial extensions the following conditions are
+required
+
+- a valid stack pointer and enough stack space,
+
+- a valid code memory, and
+
+- valid read-only data.
+
+For the initial extensions the read-write data (including .bss segment) is not
+required on single processor configurations.  In SMP configurations, however,
+the read-write data must be initialized since this function must determine the
+state of the other processors and request them to shut-down if necessary.
+
+Non-initial extensions require in addition valid read-write data.  The board
+support package (BSP) may install an initial extension that performs a system
+reset.  In this case the non-initial extensions will be not called.
+
+The fatal extensions are called with three parameters:
+
+- the fatal source,
+
+- a legacy parameter which is always false, and
+
+- an error code with a fatal source dependent content.
+
+Once all fatal extensions executed, the error information will be stored to
+:c:data:`_Internal_errors_What_happened` and the system state is set to
+:c:macro:`SYSTEM_STATE_TERMINATED`.
+
+The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`.
diff --git a/c-user/index.rst b/c-user/index.rst
index 0a05c75..267d56c 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -44,7 +44,7 @@ RTEMS Classic API Guide (|version|).
 	region/index
 	dual-ported-memory/index
 	io/index
-	fatal_error
+	fatal-error/index
 	board_support_packages
 	user-extensions/index
 	config/index
diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst
index ae14fb0..88805f2 100644
--- a/c-user/initialization/introduction.rst
+++ b/c-user/initialization/introduction.rst
@@ -7,7 +7,7 @@ Introduction
 
 The Initialization Manager is responsible for initializing the Board Support
 Package, RTEMS, device drivers, the root filesystem and the application.  The
-:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
+:ref:`RTEMSAPIClassicFatal` is responsible for the system
 shutdown.
 
 The Initialization Manager provides only one directive: