From ae68ff085724dd35d60151bd153e80b8b0776873 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 27 May 1997 12:40:11 +0000 Subject: Initial revision --- doc/user/fatal.t | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 doc/user/fatal.t (limited to 'doc/user/fatal.t') diff --git a/doc/user/fatal.t b/doc/user/fatal.t new file mode 100644 index 0000000000..4f15684195 --- /dev/null +++ b/doc/user/fatal.t @@ -0,0 +1,180 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Fatal Error Manager, Fatal Error Manager Introduction, IO_CONTROL - Special device services, Top +@end ifinfo +@chapter Fatal Error Manager +@ifinfo +@menu +* Fatal Error Manager Introduction:: +* Fatal Error Manager Background:: +* Fatal Error Manager Operations:: +* Fatal Error Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Fatal Error Manager Introduction, Fatal Error Manager Background, Fatal Error Manager, Fatal Error Manager +@end ifinfo +@section Introduction + +The fatal error manager processes all fatal or +irrecoverable errors. The directive provided by the fatal error +manager is: + +@itemize @bullet +@item @code{fatal_error_occurred} - Invoke the fatal error handler +@end itemize + + + +@ifinfo +@node Fatal Error Manager Background, Fatal Error Manager Operations, Fatal Error Manager Introduction, Fatal Error Manager +@end ifinfo +@section Background + +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: + +@itemize @bullet +@item the executive (RTEMS) +@item user system code +@item user application code +@end itemize + +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 status 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 C Applications Supplement document for +a specific target processor. + +@ifinfo +@node Fatal Error Manager Operations, Announcing a Fatal Error, Fatal Error Manager Background, Fatal Error Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Fatal Error:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Fatal Error, Fatal Error Manager Directives, Fatal Error Manager Operations, Fatal Error Manager Operations +@end ifinfo +@subsection Announcing a Fatal Error + +The 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 +fatal_error_occurred directive stores useful information in the +variable _Internal_errors_What_happened. This structure +contains three pieces of information: + +@itemize @bullet +@item the source of the error (API or executive core), + +@item whether the error was generated internally by the +executive, and a + +@item a numeric code to indicate the error type. +@end itemize + +The error type indicator is dependent on the source +of the error and whether or not the error was internally +generated by the executive. + +The fatal_error_directive 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 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. + +@ifinfo +@node Fatal Error Manager Directives, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Announcing a Fatal Error, Fatal Error Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* FATAL_ERROR_OCCURRED - Invoke the fatal error handler:: +@end menu +@end ifinfo + +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. + +@page +@ifinfo +@node FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Scheduling Concepts, Fatal Error Manager Directives, Fatal Error Manager Directives +@end ifinfo +@subsection FATAL_ERROR_OCCURRED - Invoke the fatal error handler + +@subheading CALLING SEQUENCE: + +@example +void volatile rtems_fatal_error_occurred( + rtems_unsigned32 the_error +); +@end example + +@subheading DIRECTIVE STATUS CODES + +NONE + +@subheading 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. + +@subheading 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. -- cgit v1.2.3