@c @c COPYRIGHT (c) 1988-1998. @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