From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- c-user/fatal_error.rst | 253 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 c-user/fatal_error.rst (limited to 'c-user/fatal_error.rst') 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 . + +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. -- cgit v1.2.3