mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-19 01:02:23 +08:00
253 lines
7.1 KiB
ReStructuredText
253 lines
7.1 KiB
ReStructuredText
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.
|
|
|