summaryrefslogtreecommitdiffstats
path: root/c-user/fatal_error.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-03 16:58:08 +1100
committerChris Johns <chrisj@rtems.org>2016-11-03 16:58:08 +1100
commit72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 (patch)
tree6b0e527e67141f8126ba56b8a3c1eb90aeed5849 /c-user/fatal_error.rst
parent6207c37d9c8a3d75e67c10671fe2c309c805bbed (diff)
downloadrtems-docs-72a62ad88f82fe1ffee50024db4dd0f3fa5806f7.tar.bz2
Rename all manuals with an _ to have a -. It helps released naming of files.
Diffstat (limited to 'c-user/fatal_error.rst')
-rw-r--r--c-user/fatal_error.rst253
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.