source: rtems/doc/user/fatal.t @ 1906a36

4.11
Last change on this file since 1906a36 was 1906a36, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 18, 2012 at 6:51:10 PM

score: Change _Internal_error_Occurred()

Call the fatal handlers of the user extensions before the update of
_Internal_errors_What_happened. This reduces the requirements on the
execution context further. Now a valid read-write data is only required
after the call to the fatal handlers.

  • Property mode set to 100644
File size: 6.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5
6@chapter Fatal Error Manager
7
8@cindex fatal errors
9
10@section Introduction
11
12The fatal error manager processes all fatal or irrecoverable errors and other
13sources of system termination (for example after exit()).  The directives
14provided by the fatal error manager are:
15
16@itemize @bullet
17@item @code{@value{DIRPREFIX}fatal_error_occurred} - Invoke the fatal error handler
18@item @code{@value{DIRPREFIX}fatal} - Invoke the fatal error handler with error source
19@end itemize
20
21@section Background
22
23@cindex fatal error detection
24@cindex fatal error processing
25@cindex fatal error user extension
26
27The fatal error manager is called upon detection of
28an irrecoverable error condition by either RTEMS or the
29application software.  Fatal errors can be detected from three
30sources:
31
32@itemize @bullet
33@item the executive (RTEMS)
34@item user system code
35@item user application code
36@end itemize
37
38RTEMS automatically invokes the fatal error manager
39upon detection of an error it considers to be fatal.  Similarly,
40the user should invoke the fatal error manager upon detection of
41a fatal error.
42
43Each static or dynamic user extension set may include
44a fatal error handler.  The fatal error handler in the static
45extension set can be used to provide access to debuggers and
46monitors which may be present on the target hardware.  If any
47user-supplied fatal error handlers are installed, the fatal
48error manager will invoke them.  If no user handlers are
49configured or if all the user handler return control to the
50fatal error manager, then the RTEMS default fatal error handler
51is invoked.  If the default fatal error handler is invoked, then
52the system state is marked as failed.
53
54Although the precise behavior of the default fatal
55error handler is processor specific, in general, it will disable
56all maskable interrupts, place the error code in a known
57processor dependent place (generally either on the stack or in a
58register), and halt the processor.  The precise actions of the
59RTEMS fatal error are discussed in the Default Fatal Error
60Processing chapter of the Applications Supplement document for
61a specific target processor.
62
63@section Operations
64
65@subsection Announcing a Fatal Error
66
67@findex _Internal_errors_What_happened
68
69The @code{@value{DIRPREFIX}fatal_error_occurred} directive is invoked when a
70fatal error is detected.  Before invoking any user-supplied
71fatal error handlers or the RTEMS fatal error handler, the
72@code{@value{DIRPREFIX}fatal_error_occurred}
73directive stores useful information in the
74variable @code{_Internal_errors_What_happened}.  This @value{STRUCTURE}
75contains three pieces of information:
76
77@itemize @bullet
78@item the source of the error (API or executive core),
79
80@item whether the error was generated internally by the
81executive, and a
82
83@item a numeric code to indicate the error type.
84@end itemize
85
86The error type indicator is dependent on the source
87of the error and whether or not the error was internally
88generated by the executive.  If the error was generated
89from an API, then the error code will be of that API's
90error or status codes.  The status codes for the RTEMS
91API are in cpukit/rtems/include/rtems/rtems/status.h.  Those
92for the POSIX API can be found in <errno.h>.
93
94The @code{@value{DIRPREFIX}fatal_error_occurred} directive is responsible
95for invoking an optional user-supplied fatal error handler
96and/or the RTEMS fatal error handler.  All fatal error handlers
97are passed an error code to describe the error detected.
98
99Occasionally, an application requires more
100sophisticated fatal error processing such as passing control to
101a debugger.  For these cases, a user-supplied fatal error
102handler can be specified in the RTEMS configuration table.  The
103User Extension Table field fatal contains the address of the
104fatal error handler to be executed when the
105@code{@value{DIRPREFIX}fatal_error_occurred}
106directive is called.  If the field is set to NULL or if the
107configured fatal error handler returns to the executive, then
108the default handler provided by RTEMS is executed.  This default
109handler will halt execution on the processor where the error
110occurred.
111
112@section Directives
113
114This section details the fatal error manager's
115directives.  A subsection is dedicated to each of this manager's
116directives and describes the calling sequence, related
117constants, usage, and status codes.
118
119@c
120@c
121@c
122@page
123@subsection FATAL_ERROR_OCCURRED - Invoke the fatal error handler
124
125@cindex announce fatal error
126@cindex fatal error, announce
127
128@subheading CALLING SEQUENCE:
129
130@ifset is-C
131@findex rtems_fatal_error_occurred
132@example
133void rtems_fatal_error_occurred(
134  uint32_t  the_error
135);
136@end example
137@end ifset
138
139@ifset is-Ada
140@example
141procedure Fatal_Error_Occurred (
142   The_Error : in     RTEMS.Unsigned32
143);
144@end example
145@end ifset
146
147@subheading DIRECTIVE STATUS CODES
148
149NONE
150
151@subheading DESCRIPTION:
152
153This directive processes fatal errors.  If the FATAL
154error extension is defined in the configuration table, then the
155user-defined error extension is called.  If configured and the
156provided FATAL error extension returns, then the RTEMS default
157error handler is invoked.  This directive can be invoked by
158RTEMS or by the user's application code including initialization
159tasks, other tasks, and ISRs.
160
161@subheading NOTES:
162
163This directive supports local operations only.
164
165Unless the user-defined error extension takes special
166actions such as restarting the calling task, this directive WILL
167NOT RETURN to the caller.
168
169The user-defined extension for this directive may
170wish to initiate a global shutdown.
171
172@c
173@c
174@c
175@page
176@subsection FATAL - Invoke the fatal error handler with error source
177
178@cindex announce fatal error
179@cindex fatal error, announce
180
181@subheading CALLING SEQUENCE:
182
183@ifset is-C
184@findex rtems_fatal
185@example
186void rtems_fatal(
187  rtems_fatal_source source,
188  rtems_fatal_code error
189);
190@end example
191@end ifset
192
193@subheading DIRECTIVE STATUS CODES
194
195NONE
196
197@subheading DESCRIPTION:
198
199This directive invokes the internal error handler with is internal set to
200false.  See also @code{@value{DIRPREFIX}fatal_error_occurred}.
201
202@c
203@c
204@c
205@page
206@subsection INTERNAL_ERROR_DESCRIPTION - Returns a description for an internal error code
207
208@cindex fatal error
209
210@subheading CALLING SEQUENCE:
211
212@ifset is-C
213@findex rtems_internal_error_description
214@example
215const char *rtems_internal_error_description(
216  rtems_fatal_code error
217);
218@end example
219@end ifset
220
221@subheading DIRECTIVE STATUS CODES
222
223The error code description or "?" in case the passed error code is invalid.
224
225@subheading DESCRIPTION:
226
227Returns a description for an internal error code.
Note: See TracBrowser for help on using the repository browser.