From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/fatal_error.rst | 252 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 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..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 . + +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. + -- cgit v1.2.3