summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters/error.t
blob: 331272bd6c4ac0e20aa2b6bb6984989caee55cce (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved. 
@c
@c  $Id$
@c

@chapter Error Reporting Support 

@section Introduction

These error reporting facilities are an RTEMS support
component that provide convenient facilities for handling
error conditions in an RTEMS application.
of each task using a period.  The services provided by the error
reporting support component are:

@itemize @bullet
@item @code{rtems_error} - Report an Error
@item @code{rtems_panic} - Report an Error and Panic
@item @code{rtems_status_text} - ASCII Version of RTEMS Status
@end itemize

@section Background

@subsection Error Handling in an Embedded System

Error handling in an embedded system is a difficult problem.  If the error
is severe, then the only recourse is to shut the system down in a safe
manner.  Other errors can be detected and compensated for.  The 
error reporting routines in this support component -- @code{rtems_error}
and @code{rtems_panic} assume that if the error is severe enough,
then the system should be shutdown.  If a simple shutdown with
some basic diagnostic information is not sufficient, then
these routines should not be used in that particular system.  In this case,
use the @code{rtems_status_text} routine to construct an application
specific error reporting routine.

@section Operations

@subsection Reporting an Error

The @code{rtems_error} and @code{rtems_panic} routines
can be used to print some diagnostic information and
shut the system down.  The @code{rtems_error} routine
is invoked with a user specified error level indicator.
This error indicator is used to determine if the system
should be shutdown after reporting this error.

@section Routines

This section details the error reporting support compenent's routine.
A subsection is dedicated to each of this manager's routines
and describes the calling sequence, related constants, usage,
and status codes.

@page
@subsection rtems_status_text - ASCII Version of RTEMS Status

@subheading CALLING SEQUENCE:

@ifset is-C
@example
const char *rtems_status_text(
  rtems_status_code status
);
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES:

Returns a pointer to a constant string that describes the given
RTEMS status code.

@subheading DESCRIPTION:

This routine returns a pointer to a string that describes
the RTEMS status code specified by @code{status}.

@subheading NOTES:

NONE

@page
@subsection rtems_error - Report an Error

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int rtems_error(
  int         error_code,
  const char *printf_format,
  ...
);
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES:

Returns the number of characters written.

@subheading DESCRIPTION:

This routine prints the requested information as specified by the
@code{printf_format} parameter and the zero or more optional arguments
following that parameter.  The @code{error_code} parameter is an error
number with either @code{RTEMS_ERROR_PANIC} or @code{RTEMS_ERROR_ABORT}
bitwise or'ed with it.  If the @code{RTEMS_ERROR_PANIC} bit is set, then
then the system is system is shutdown via a call to @code{_exit}.  
If the @code{RTEMS_ERROR_ABORT} bit is set, then
then the system is system is shutdown via a call to @code{abort}.

@subheading NOTES:

NONE

@page
@subsection rtems_panic - Report an Error and Panic

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int rtems_panic(
   const char *printf_format,
   ...
);
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES:

Returns the number of characters written.

@subheading DESCRIPTION:

This routine is a wrapper for the @code{rtems_error} routine with
an implied error level of @code{RTEMS_ERROR_PANIC}.  See 
@code{rtems_error} for more information.

@subheading NOTES:

NONE