From 8ef6ea80ef8f8e9ac5a0dfa11687329101e7bb67 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Wed, 27 Jan 2016 17:50:19 +1100 Subject: Clean ups. --- c_user/fatal_error.rst | 187 ++++++++++++++++++++++++------------------------- 1 file changed, 92 insertions(+), 95 deletions(-) (limited to 'c_user/fatal_error.rst') diff --git a/c_user/fatal_error.rst b/c_user/fatal_error.rst index b4c221a..c556a64 100644 --- a/c_user/fatal_error.rst +++ b/c_user/fatal_error.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Fatal Error Manager ################### @@ -7,12 +11,18 @@ Introduction ============ The fatal error manager processes all fatal or irrecoverable errors and other -sources of system termination (for example after exit()). The directives +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_error_occurred_ - Invoke the fatal error handler + +- rtems_fatal_ - Invoke the fatal error handler with error source -- ``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 ========== @@ -20,10 +30,9 @@ Background .. 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 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) @@ -31,85 +40,74 @@ sources: - 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. +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 +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 +- 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. +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. +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 ----------------------------------------------------- @@ -123,7 +121,7 @@ FATAL_ERROR_OCCURRED - Invoke the fatal error handler .. code:: c void rtems_fatal_error_occurred( - uint32_t the_error + uint32_t the_error ); **DIRECTIVE STATUS CODES** @@ -132,24 +130,24 @@ 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. +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. +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. -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 -------------------------------------------------------- @@ -163,8 +161,8 @@ FATAL - Invoke the fatal error handler with error source .. code:: c void rtems_fatal( - rtems_fatal_source source, - rtems_fatal_code error + rtems_fatal_source source, + rtems_fatal_code error ); **DIRECTIVE STATUS CODES** @@ -176,6 +174,8 @@ NONE 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 @@ -187,7 +187,7 @@ EXCEPTION_FRAME_PRINT - Prints the exception frame .. code:: c void rtems_exception_frame_print( - const rtems_exception_frame \*frame + const rtems_exception_frame *frame ); **DIRECTIVE STATUS CODES** @@ -196,7 +196,9 @@ NONE **DESCRIPTION:** -Prints the exception frame via printk(). +Prints the exception frame via ``printk()``. + +.. _rtems_fatal_source_text: FATAL_SOURCE_TEXT - Returns a text for a fatal source ----------------------------------------------------- @@ -208,8 +210,8 @@ FATAL_SOURCE_TEXT - Returns a text for a fatal source .. code:: c - const char \*rtems_fatal_source_text( - rtems_fatal_source source + const char *rtems_fatal_source_text( + rtems_fatal_source source ); **DIRECTIVE STATUS CODES** @@ -221,6 +223,8 @@ The fatal source text or "?" in case the passed fatal source is invalid. 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 @@ -231,8 +235,8 @@ INTERNAL_ERROR_TEXT - Returns a text for an internal error code .. code:: c - const char \*rtems_internal_error_text( - rtems_fatal_code error + const char *rtems_internal_error_text( + rtems_fatal_code error ); **DIRECTIVE STATUS CODES** @@ -243,10 +247,3 @@ The error code text or "?" in case the passed error code is invalid. 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