Split document into seperate files by section.

1 files changed, 252 insertions, 0 deletions

diff --git a/c_user/fatal_error.rst b/c_user/fatal_error.rst
new file mode 100644
index 0000000..2c540f1
--- /dev/null
+++ b/c_user/fatal_error.rst
@@ -0,0 +1,252 @@
+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
+
+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
+------------------------
+.. 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.
+
+FATAL_ERROR_OCCURRED - Invoke the fatal error handler
+-----------------------------------------------------
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_fatal_error_occurred
+
+.. code:: 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.
+
+FATAL - Invoke the fatal error handler with error source
+--------------------------------------------------------
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_fatal
+
+.. code:: 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``.
+
+EXCEPTION_FRAME_PRINT - Prints the exception frame
+--------------------------------------------------
+.. index:: exception frame
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_exception_frame_print
+
+.. code:: c
+
+    void rtems_exception_frame_print(
+    const rtems_exception_frame \*frame
+    );
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**DESCRIPTION:**
+
+Prints the exception frame via printk().
+
+FATAL_SOURCE_TEXT - Returns a text for a fatal source
+-----------------------------------------------------
+.. index:: fatal error
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_fatal_source_text
+
+.. code:: 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.
+
+INTERNAL_ERROR_TEXT - Returns a text for an internal error code
+---------------------------------------------------------------
+.. index:: fatal error
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_internal_error_text
+
+.. code:: 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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+