1 files changed, 253 insertions, 0 deletions
diff --git a/c-user/fatal_error.rst b/c-user/fatal_error.rst
new file mode 100644
index 0000000..6ffd43b
--- /dev/null
+++ b/c-user/fatal_error.rst
@@ -0,0 +1,253 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
+Fatal Error Manager
+###################
+
+.. index:: fatal errors
+
+Introduction
+============
+
+The fatal error manager processes all fatal or irrecoverable errors and other
+sources of system termination (for example after ``exit()``).  The directives
+provided by the fatal error manager are:
+
+- rtems_fatal_error_occurred_ - Invoke the fatal error handler
+
+- rtems_fatal_ - Invoke the fatal error handler with error source
+
+- rtems_exception_frame_print_ - Print the CPU exception frame
+
+- rtems_fatal_source_text_ - Return the falet source text
+
+- rtems_internal_error_text_ - Return the error code text
+
+Background
+==========
+.. index:: fatal error detection
+.. index:: fatal error processing
+.. index:: fatal error user extension
+
+The fatal error manager is called upon detection of an irrecoverable error
+condition by either RTEMS or the application software.  Fatal errors can be
+detected from three sources:
+
+- the executive (RTEMS)
+
+- user system code
+
+- user application code
+
+RTEMS automatically invokes the fatal error manager upon detection of an error
+it considers to be fatal.  Similarly, the user should invoke the fatal error
+manager upon detection of a fatal error.
+
+Each static or dynamic user extension set may include a fatal error handler.
+The fatal error handler in the static extension set can be used to provide
+access to debuggers and monitors which may be present on the target hardware.
+If any user-supplied fatal error handlers are installed, the fatal error
+manager will invoke them.  If no user handlers are configured or if all the
+user handler return control to the fatal error manager, then the RTEMS default
+fatal error handler is invoked.  If the default fatal error handler is invoked,
+then the system state is marked as failed.
+
+Although the precise behavior of the default fatal error handler is processor
+specific, in general, it will disable all maskable interrupts, place the error
+code in a known processor dependent place (generally either on the stack or in
+a register), and halt the processor.  The precise actions of the RTEMS fatal
+error are discussed in the Default Fatal Error Processing chapter of the
+Applications Supplement document for a specific target processor.
+
+Operations
+==========
+
+.. _Announcing a Fatal Error:
+
+Announcing a Fatal Error
+------------------------
+.. index:: _Internal_errors_What_happened
+
+The ``rtems_fatal_error_occurred`` directive is invoked when a fatal error is
+detected.  Before invoking any user-supplied fatal error handlers or the RTEMS
+fatal error handler, the ``rtems_fatal_error_occurred`` directive stores useful
+information in the variable ``_Internal_errors_What_happened``.  This structure
+contains three pieces of information:
+
+- the source of the error (API or executive core),
+
+- whether the error was generated internally by the executive, and a
+
+- a numeric code to indicate the error type.
+
+The error type indicator is dependent on the source of the error and whether or
+not the error was internally generated by the executive.  If the error was
+generated from an API, then the error code will be of that API's error or
+status codes.  The status codes for the RTEMS API are in
+cpukit/rtems/include/rtems/rtems/status.h.  Those for the POSIX API can be
+found in <errno.h>.
+
+The ``rtems_fatal_error_occurred`` directive is responsible for invoking an
+optional user-supplied fatal error handler and/or the RTEMS fatal error
+handler.  All fatal error handlers are passed an error code to describe the
+error detected.
+
+Occasionally, an application requires more sophisticated fatal error processing
+such as passing control to a debugger.  For these cases, a user-supplied fatal
+error handler can be specified in the RTEMS configuration table.  The User
+Extension Table field fatal contains the address of the fatal error handler to
+be executed when the ``rtems_fatal_error_occurred`` directive is called.  If
+the field is set to NULL or if the configured fatal error handler returns to
+the executive, then the default handler provided by RTEMS is executed.  This
+default handler will halt execution on the processor where the error occurred.
+
+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.
+
+.. _rtems_fatal_error_occurred:
+
+FATAL_ERROR_OCCURRED - Invoke the fatal error handler
+-----------------------------------------------------
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_fatal_error_occurred
+
+.. code-block:: c
+
+    void rtems_fatal_error_occurred(
+        uint32_t  the_error
+    );
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**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 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.
+
+.. _rtems_fatal:
+
+FATAL - Invoke the fatal error handler with error source
+--------------------------------------------------------
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_fatal
+
+.. code-block:: c
+
+    void rtems_fatal(
+       rtems_fatal_source source,
+       rtems_fatal_code   error
+    );
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive invokes the internal error handler with is internal set to
+false.  See also ``rtems_fatal_error_occurred``.
+
+.. _rtems_exception_frame_print:
+
+EXCEPTION_FRAME_PRINT - Prints the exception frame
+--------------------------------------------------
+.. index:: exception frame
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_exception_frame_print
+
+.. code-block:: c
+
+    void rtems_exception_frame_print(
+        const rtems_exception_frame *frame
+    );
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**DESCRIPTION:**
+
+Prints the exception frame via ``printk()``.
+
+.. _rtems_fatal_source_text:
+
+FATAL_SOURCE_TEXT - Returns a text for a fatal source
+-----------------------------------------------------
+.. index:: fatal error
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_fatal_source_text
+
+.. 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.
+
+.. _rtems_internal_error_text:
+
+INTERNAL_ERROR_TEXT - Returns a text for an internal error code
+---------------------------------------------------------------
+.. index:: fatal error
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_internal_error_text
+
+.. 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.