mirror of
https://git.rtems.org/rtems-docs/
synced 2025-10-19 07:27:07 +08:00
Initial reST documentation using Sphinx.
This commit is contained in:
Amar Takhar
1
new_chapters/index.rst
Normal file
1
new_chapters/index.rst
Normal file
@@ -0,0 +1 @@
|
||||
.. include:: new_chapters.rst
|
||||
493
new_chapters/new_chapters.rst
Normal file
493
new_chapters/new_chapters.rst
Normal file
@@ -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.h>
|
||||
...
|
||||
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
|
||||
19
new_chapters/wscript
Normal file
19
new_chapters/wscript
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user