From 5daabd23cfd13662e74ce8d069204882eb1fbad9 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Fri, 15 Jan 2016 23:41:06 -0500 Subject: Initial reST documentation using Sphinx. --- new_chapters/index.rst | 1 + new_chapters/new_chapters.rst | 493 ++++++++++++++++++++++++++++++++++++++++++ new_chapters/wscript | 19 ++ 3 files changed, 513 insertions(+) create mode 100644 new_chapters/index.rst create mode 100644 new_chapters/new_chapters.rst create mode 100644 new_chapters/wscript (limited to 'new_chapters') diff --git a/new_chapters/index.rst b/new_chapters/index.rst new file mode 100644 index 0000000..4473847 --- /dev/null +++ b/new_chapters/index.rst @@ -0,0 +1 @@ +.. include:: new_chapters.rst diff --git a/new_chapters/new_chapters.rst b/new_chapters/new_chapters.rst new file mode 100644 index 0000000..b92e7f8 --- /dev/null +++ b/new_chapters/new_chapters.rst @@ -0,0 +1,493 @@ +: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 diff --git a/new_chapters/wscript b/new_chapters/wscript new file mode 100644 index 0000000..650b8e5 --- /dev/null +++ b/new_chapters/wscript @@ -0,0 +1,19 @@ +from sys import path +from os.path import abspath +path.append(abspath('../common/')) + +from waf import cmd_configure, cmd_build + +def configure(ctx): + cmd_configure(ctx) + +def build(ctx): + + sub = { + "VERSION": "1.0", + "RELEASE": "5.0.0", + "DOC": "New Chapters", + "FILE_DOC": "rtemsnew_chapters", + } + + cmd_build(ctx, sub) -- cgit v1.2.3