forked from Imagelibrary/rtems
Initial revision
This commit is contained in:
Joel Sherrill
180
doc/user/fatal.t
Normal file
180
doc/user/fatal.t
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user