:orphan: .. COMMENT: %**end of header .. COMMENT: COPYRIGHT (c) 1989-2013. .. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: All rights reserved. .. COMMENT: Master file for the C User's Guide .. COMMENT: Joel's Questions .. COMMENT: 1. Why does paragraphindent only impact makeinfo? .. COMMENT: 2. Why does paragraphindent show up in HTML? .. COMMENT: COPYRIGHT (c) 1988-2002. .. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: All rights reserved. .. COMMENT: The following determines which set of the tables and figures we will use. .. COMMENT: We default to ASCII but if available TeX or HTML versions will .. COMMENT: be used instead. .. COMMENT: @clear use-html .. COMMENT: @clear use-tex .. COMMENT: The following variable says to use texinfo or html for the two column .. COMMENT: texinfo tables. For somethings the format does not look good in html. .. COMMENT: With our adjustment to the left column in TeX, it nearly always looks .. COMMENT: good printed. .. COMMENT: Custom whitespace adjustments. We could fiddle a bit more. .. COMMENT: variable substitution info: .. COMMENT: Note: At the moment we do not document the Ada interface but by building .. COMMENT: in the infrastructure Florist support should be simple to add. .. COMMENT: the language is @value{LANGUAGE} .. COMMENT: NOTE: don't use underscore in the name .. COMMENT: Title Page Stuff .. COMMENT: I don't really like having a short title page. -joel .. COMMENT: @shorttitlepage New Chapters ============ New Chapters ============ .. COMMENT: COPYRIGHT (c) 1988-2015. .. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: All rights reserved. .. COMMENT: The following puts a space somewhere on an otherwise empty page so we .. COMMENT: can force the copyright description onto a left hand page. COPYRIGHT © 1988 - 2015. On-Line Applications Research Corporation (OAR). The authors have used their best efforts in preparing this material. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. No warranty of any kind, expressed or implied, with regard to the software or the material contained in this document is provided. No liability arising out of the application or use of any product described in this document is assumed. The authors reserve the right to revise this material and to make changes from time to time in the content hereof without obligation to notify anyone of such revision or changes. The RTEMS Project is hosted at http://www.rtems.org. Any inquiries concerning RTEMS, its related support components, or its documentation should be directed to the Community Project hosted athttp://www.rtems.org. Any inquiries for commercial services including training, support, custom development, application development assistance should be directed tohttp://www.rtems.com. .. COMMENT: This prevents a black box from being printed on "overflow" lines. .. COMMENT: The alternative is to rework a sentence to avoid this problem. RTEMS POSIX API User’s Guide ############################ .. COMMENT: COPYRIGHT (c) 1988-2002. .. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: All rights reserved. Error Reporting Support ####################### 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: - ``rtems_error`` - Report an Error - ``rtems_panic`` - Report an Error and Panic - ``rtems_status_text`` - ASCII Version of RTEMS Status Background ========== 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 – ``rtems_error`` and ``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 ``rtems_status_text`` routine to construct an application specific error reporting routine. Operations ========== Reporting an Error ------------------ The ``rtems_error`` and ``rtems_panic`` routines can be used to print some diagnostic information and shut the system down. The ``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. 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. rtems_status_text - ASCII Version of RTEMS Status ------------------------------------------------- **CALLING SEQUENCE:** .. code:: c const char \*rtems_status_text( rtems_status_code status ); **STATUS CODES:** Returns a pointer to a constant string that describes the given RTEMS status code. **DESCRIPTION:** This routine returns a pointer to a string that describes the RTEMS status code specified by ``status``. **NOTES:** NONE rtems_error - Report an Error ----------------------------- **CALLING SEQUENCE:** .. code:: c int rtems_error( int error_code, const char \*printf_format, ... ); **STATUS CODES:** Returns the number of characters written. **DESCRIPTION:** This routine prints the requested information as specified by the``printf_format`` parameter and the zero or more optional arguments following that parameter. The ``error_code`` parameter is an error number with either ``RTEMS_ERROR_PANIC`` or ``RTEMS_ERROR_ABORT`` bitwise or’ed with it. If the ``RTEMS_ERROR_PANIC`` bit is set, then then the system is system is shutdown via a call to ``_exit``. If the ``RTEMS_ERROR_ABORT`` bit is set, then then the system is system is shutdown via a call to ``abort``. **NOTES:** NONE rtems_panic - Report an Error and Panic --------------------------------------- **CALLING SEQUENCE:** .. code:: c int rtems_panic( const char \*printf_format, ... ); **STATUS CODES:** Returns the number of characters written. **DESCRIPTION:** This routine is a wrapper for the ``rtems_error`` routine with an implied error level of ``RTEMS_ERROR_PANIC``. See``rtems_error`` for more information. **NOTES:** NONE .. COMMENT: COPYRIGHT (c) 1988-2002. .. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: All rights reserved. Monitor Task ############ Introduction ============ The monitor task is a simple interactive shell that allows the user to make inquries about he state of various system objects. The routines provided by the monitor task manager are: - ``rtems_monitor_init`` - Initialize the Monitor Task - ``rtems_monitor_wakeup`` - Wakeup the Monitor Task Background ========== There is no background information. Operations ========== Initializing the Monitor ------------------------ The monitor is initialized by calling ``rtems_monitor_init``. When initialized, the monitor is created as an independent task. An example of initializing the monitor is shown below: .. code:: c #include ... rtems_monitor_init(0); The "0" parameter to the ``rtems_monitor_init`` routine causes the monitor to immediately enter command mode. This parameter is a bitfield. If the monitor is to suspend itself on startup, then the ``RTEMS_MONITOR_SUSPEND`` bit should be set. Routines ======== This section details the monitor task manager’s routines. A subsection is dedicated to each of this manager’s routines and describes the calling sequence, related constants, usage, and status codes. rtems_monitor_init - Initialize the Monitor Task ------------------------------------------------ **CALLING SEQUENCE:** .. code:: c void rtems_monitor_init( unsigned32 monitor_flags ); **STATUS CODES: NONE** **DESCRIPTION:** This routine initializes the RTEMS monitor task. The``monitor_flags`` parameter indicates how the server task is to start. This parameter is a bitfield and has the following constants associated with it: - *RTEMS_MONITOR_SUSPEND* - suspend monitor on startup - *RTEMS_MONITOR_GLOBAL* - monitor should be global If the ``RTEMS_MONITOR_SUSPEND`` bit is set, then the monitor task will suspend itself after it is initialized. A subsequent call to ``rtems_monitor_wakeup`` will be required to activate it. **NOTES:** The monitor task is created with priority 1. If there are application tasks at priority 1, then there may be times when the monitor task is not executing. rtems_monitor_wakeup - Wakeup the Monitor Task ---------------------------------------------- **CALLING SEQUENCE:** .. code:: c void rtems_monitor_wakeup( void ); **STATUS CODES: NONE** **DESCRIPTION:** This routine is used to activate the monitor task if it is suspended. **NOTES:** NONE Monitor Interactive Commands ============================ The following commands are supported by the monitor task: - ``help`` - Obtain Help - ``pause`` - Pause Monitor for a Specified Number of Ticks - ``exit`` - Invoke a Fatal RTEMS Error - ``symbol`` - Show Entries from Symbol Table - ``continue`` - Put Monitor to Sleep Waiting for Explicit Wakeup - ``config`` - Show System Configuration - ``itask`` - List Init Tasks - ``mpci`` - List MPCI Config - ``task`` - Show Task Information - ``queue`` - Show Message Queue Information - ``extension`` - User Extensions - ``driver`` - Show Information About Named Drivers - ``dname`` - Show Information About Named Drivers - ``object`` - Generic Object Information - ``node`` - Specify Default Node for Commands That Take IDs help - Obtain Help ------------------ The ``help`` command prints out the list of commands. If invoked with a command name as the first argument, detailed help information on that command is printed. pause - Pause Monitor for a Specified Number of Ticks ----------------------------------------------------- The ``pause`` command cause the monitor task to suspend itself for the specified number of ticks. If this command is invoked with no arguments, then the task is suspended for 1 clock tick. exit - Invoke a Fatal RTEMS Error --------------------------------- The ``exit`` command invokes ``rtems_error_occurred`` directive with the specified error code. If this command is invoked with no arguments, then the ``rtems_error_occurred`` directive is invoked with an arbitrary error code. symbol - Show Entries from Symbol Table --------------------------------------- The ``symbol`` command lists the specified entries in the symbol table. If this command is invoked with no arguments, then all the symbols in the symbol table are printed. continue - Put Monitor to Sleep Waiting for Explicit Wakeup ----------------------------------------------------------- The ``continue`` command suspends the monitor task with no timeout. config - Show System Configuration ---------------------------------- The ``config`` command prints the system configuration. itask - List Init Tasks ----------------------- The ``itask`` command lists the tasks in the initialization tasks table. mpci - List MPCI Config ----------------------- The ``mpci`` command shows the MPCI configuration information task - Show Task Information ---------------------------- The ``task`` command prints out information about one or more tasks in the system. If invoked with no arguments, then information on all the tasks in the system is printed. queue - Show Message Queue Information -------------------------------------- The ``queue`` command prints out information about one or more message queues in the system. If invoked with no arguments, then information on all the message queues in the system is printed. extension - User Extensions --------------------------- The ``extension`` command prints out information about the user extensions. driver - Show Information About Named Drivers --------------------------------------------- The ``driver`` command prints information about the device driver table. dname - Show Information About Named Drivers -------------------------------------------- The ``dname`` command prints information about the named device drivers. object - Generic Object Information ----------------------------------- The ``object`` command prints information about RTEMS objects. node - Specify Default Node for Commands That Take IDs ------------------------------------------------------ The ``node`` command sets the default node for commands that look at object ID ranges. Command and Variable Index ########################## There are currently no Command and Variable Index entries. .. COMMENT: @printindex fn Concept Index ############# There are currently no Concept Index entries. .. COMMENT: @printindex cp