summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1997-05-27 12:40:11 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1997-05-27 12:40:11 +0000
commitae68ff085724dd35d60151bd153e80b8b0776873 (patch)
tree2f1535a0497f5b872a4744ae13c9264b77e89c11 /doc/user
parentb65131dc23672b24c32d76081c5917f2f38d93fe (diff)
downloadrtems-ae68ff085724dd35d60151bd153e80b8b0776873.tar.bz2
Initial revision
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/Makefile59
-rw-r--r--doc/user/bsp.t377
-rw-r--r--doc/user/c_user.texi159
-rw-r--r--doc/user/clock.t356
-rw-r--r--doc/user/concepts.t322
-rw-r--r--doc/user/conf.t752
-rw-r--r--doc/user/dirstat.texi40
-rw-r--r--doc/user/dpmem.t324
-rw-r--r--doc/user/event.t351
-rw-r--r--doc/user/example.texi103
-rw-r--r--doc/user/fatal.t180
-rw-r--r--doc/user/glossary.texi772
-rw-r--r--doc/user/init.t408
-rw-r--r--doc/user/intr.t300
-rw-r--r--doc/user/io.t528
-rw-r--r--doc/user/mp.t628
-rw-r--r--doc/user/msg.t714
-rw-r--r--doc/user/overview.t578
-rw-r--r--doc/user/part.t423
-rw-r--r--doc/user/preface.texi173
-rw-r--r--doc/user/region.t601
-rw-r--r--doc/user/rtemsarc.gifbin0 -> 7653 bytes
-rw-r--r--doc/user/rtemspie.gifbin0 -> 31070 bytes
-rw-r--r--doc/user/rtmon.t1148
-rw-r--r--doc/user/schedule.t426
-rw-r--r--doc/user/sem.t722
-rw-r--r--doc/user/signal.t354
-rw-r--r--doc/user/states.gifbin0 -> 31256 bytes
-rw-r--r--doc/user/task.t1313
-rw-r--r--doc/user/timer.t441
-rw-r--r--doc/user/userext.t649
31 files changed, 13201 insertions, 0 deletions
diff --git a/doc/user/Makefile b/doc/user/Makefile
new file mode 100644
index 0000000000..4830a70879
--- /dev/null
+++ b/doc/user/Makefile
@@ -0,0 +1,59 @@
+#
+# COPYRIGHT (c) 1996.
+# On-Line Applications Research Corporation (OAR).
+# All rights reserved.
+#
+
+include ../Make.config
+
+PROJECT=c_user
+
+all:
+
+COMMON_FILES=../common/cpright.texi
+FILES= bsp.texi c_user.texi clock.texi concepts.texi conf.texi \
+dirstat.texi dpmem.texi event.texi example.texi fatal.texi \
+glossary.texi init.texi intr.texi io.texi mp.texi msg.texi overview.texi \
+part.texi preface.texi region.texi rtmon.texi schedule.texi sem.texi \
+signal.texi task.texi timer.texi userext.texi $(COMMON_FILES)
+
+all:
+
+INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*)
+
+info: c_user
+ cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL)
+
+c_user: $(FILES)
+ $(MAKEINFO) $(PROJECT).texi
+
+vinfo: info
+ $(INFO) -f $(PROJECT)
+
+dvi: $(PROJECT).dvi
+ps: $(PROJECT).ps
+
+$(PROJECT).ps: $(PROJECT).dvi
+ dvips -o $(PROJECT).ps $(PROJECT).dvi
+ cp $(PROJECT).ps $(PS_INSTALL)
+
+dv: dvi
+ $(XDVI) $(PROJECT).dvi
+
+view: ps
+ $(GHOSTVIEW) $(PROJECT).ps
+
+$(PROJECT).dvi: $(FILES)
+ $(TEXI2DVI) $(PROJECT).texi
+
+html:
+ -mkdir $(WWW_INSTALL)/c_user
+ cp rtemsarc.gif rtemspie.gif states.gif $(WWW_INSTALL)/c_user
+ $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
+ $(PROJECT).texi
+
+clean:
+ rm -f *.o $(PROG) *.txt core *.html
+ rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
+ rm -f c_user c_user-* _*
+
diff --git a/doc/user/bsp.t b/doc/user/bsp.t
new file mode 100644
index 0000000000..85b87f1078
--- /dev/null
+++ b/doc/user/bsp.t
@@ -0,0 +1,377 @@
+@c
+@c COPYRIGHT (c) 1988-1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Board Support Packages, Board Support Packages Introduction, RATE_MONOTONIC_GET_STATUS - Obtain status information on period, Top
+@end ifinfo
+@chapter Board Support Packages
+@ifinfo
+@menu
+* Board Support Packages Introduction::
+* Board Support Packages Reset and Initialization::
+* Board Support Packages Device Drivers::
+* Board Support Packages User Extensions::
+* Board Support Packages Multiprocessor Communications Interface (MPCI)::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Board Support Packages Introduction, Board Support Packages Reset and Initialization, Board Support Packages, Board Support Packages
+@end ifinfo
+@section Introduction
+
+A board support package (BSP) is a collection of
+user-provided facilities which interface RTEMS and an
+application with a specific hardware platform. These facilities
+may include hardware initialization, device drivers, user
+extensions, and a Multiprocessor Communications Interface
+(MPCI). However, a minimal BSP need only support processor
+reset and initialization and, if needed, a clock tick.
+
+@ifinfo
+@node Board Support Packages Reset and Initialization, Interrupt Stack Requirements, Board Support Packages Introduction, Board Support Packages
+@end ifinfo
+@section Reset and Initialization
+@ifinfo
+@menu
+* Interrupt Stack Requirements::
+* Processors with a Separate Interrupt Stack::
+* Processors without a Separate Interrupt Stack::
+@end menu
+@end ifinfo
+
+An RTEMS based application is initiated or
+re-initiated when the processor is reset. This initialization
+code is responsible for preparing the target platform for the
+RTEMS application. Although the exact actions performed by the
+initialization code are highly processor and target dependent,
+the logical functionality of these actions are similar across a
+variety of processors and target platforms.
+
+Normally, the application's initialization is
+performed at two separate times: before the call to
+initialize_executive (reset application initialization) and
+after initialize_executive in the user's initialization tasks
+(local and global application initialization). The order of the
+startup procedure is as follows:
+
+@enumerate
+@item Reset application initialization.
+@item Call to initialize_executive
+@item Local and global application initialization.
+@end enumerate
+
+The reset application initialization code is executed
+first when the processor is reset. All of the hardware must be
+initialized to a quiescent state by this software before
+initializing RTEMS. When in quiescent state, devices do not
+generate any interrupts or require any servicing by the
+application. Some of the hardware components may be initialized
+in this code as well as any application initialization that does
+not involve calls to RTEMS directives.
+
+The processor's Interrupt Vector Table which will be
+used by the application may need to be set to the required value
+by the reset application initialization code. Because
+interrupts are enabled automatically by RTEMS as part of the
+initialize_executive directive, the Interrupt Vector Table MUST
+be set before this directive is invoked to insure correct
+interrupt vectoring. The processor's Interrupt Vector Table
+must be accessible by RTEMS as it will be modified by the
+interrupt_catch directive. On some CPUs, RTEMS installs it's
+own Interrupt Vector Table as part of initialization and thus
+these requirements are met automatically. The reset code which
+is executed before the call to initialize_executive has the
+following requirements:
+
+@itemize @bullet
+@item Must not make any RTEMS directive calls.
+
+@item If the processor supports multiple privilege levels,
+must leave the processor in the most privileged, or supervisory,
+state.
+
+@item Must allocate a stack of at least MINIMUM_STACK_SIZE
+bytes and initialize the stack pointer for the
+initialize_executive directive.
+
+@item Must initialize the processor's Interrupt Vector Table.
+
+@item Must disable all maskable interrupts.
+
+@item If the processor supports a separate interrupt stack,
+must allocate the interrupt stack and initialize the interrupt
+stack pointer.
+@end itemize
+
+The initialize_executive directive does not return to
+the initialization code, but causes the highest priority
+initialization task to begin execution. Initialization tasks
+are used to perform both local and global application
+initialization which is dependent on RTEMS facilities. The user
+initialization task facility is typically used to create the
+application's set of tasks.
+
+@ifinfo
+@node Interrupt Stack Requirements, Processors with a Separate Interrupt Stack, Board Support Packages Reset and Initialization, Board Support Packages Reset and Initialization
+@end ifinfo
+@subsection Interrupt Stack Requirements
+
+The worst-case stack usage by interrupt service
+routines must be taken into account when designing an
+application. If the processor supports interrupt nesting, the
+stack usage must include the deepest nest level. The worst-case
+stack usage must account for the following requirements:
+
+@itemize @bullet
+@item Processor's interrupt stack frame
+
+@item Processor's subroutine call stack frame
+
+@item RTEMS system calls
+
+@item Registers saved on stack
+
+@item Application subroutine calls
+@end itemize
+
+The size of the interrupt stack must be greater than
+or equal to the constant MINIMUM_STACK_SIZE.
+
+@ifinfo
+@node Processors with a Separate Interrupt Stack, Processors without a Separate Interrupt Stack, Interrupt Stack Requirements, Board Support Packages Reset and Initialization
+@end ifinfo
+@subsection Processors with a Separate Interrupt Stack
+
+Some processors support a separate stack for
+interrupts. When an interrupt is vectored and the interrupt is
+not nested, the processor will automatically switch from the
+current stack to the interrupt stack. The size of this stack is
+based solely on the worst-case stack usage by interrupt service
+routines.
+
+The dedicated interrupt stack for the entire
+application is supplied and initialized by the reset and
+initialization code of the user's board support package. Since
+all ISRs use this stack, the stack size must take into account
+the worst case stack usage by any combination of nested ISRs.
+
+@ifinfo
+@node Processors without a Separate Interrupt Stack, Board Support Packages Device Drivers, Processors with a Separate Interrupt Stack, Board Support Packages Reset and Initialization
+@end ifinfo
+@subsection Processors without a Separate Interrupt Stack
+
+Some processors do not support a separate stack for
+interrupts. In this case, without special assistance every
+task's stack must include enough space to handle the task's
+worst-case stack usage as well as the worst-case interrupt stack
+usage. This is necessary because the worst-case interrupt
+nesting could occur while any task is executing.
+
+On many processors without dedicated hardware managed
+interrupt stacks, RTEMS manages a dedicated interrupt stack in
+software. If this capability is supported on a CPU, then it is
+logically equivalent to the processor supporting a separate
+interrupt stack in hardware.
+
+@ifinfo
+@node Board Support Packages Device Drivers, Clock Tick Device Driver, Processors without a Separate Interrupt Stack, Board Support Packages
+@end ifinfo
+@section Device Drivers
+@ifinfo
+@menu
+* Clock Tick Device Driver::
+@end menu
+@end ifinfo
+
+Device drivers consist of control software for
+special peripheral devices and provide a logical interface for
+the application developer. The RTEMS I/O manager provides
+directives which allow applications to access these device
+drivers in a consistent fashion. A Board Support Package may
+include device drivers to access the hardware on the target
+platform. These devices typically include serial and parallel
+ports, counter/timer peripherals, real-time clocks, disk
+interfaces, and network controllers.
+
+For more information on device drivers, refer to the
+I/O Manager chapter.
+
+@ifinfo
+@node Clock Tick Device Driver, Board Support Packages User Extensions, Board Support Packages Device Drivers, Board Support Packages Device Drivers
+@end ifinfo
+@subsection Clock Tick Device Driver
+
+Most RTEMS applications will include a clock tick
+device driver which invokes the clock_tick directive at regular
+intervals. The clock tick is necessary if the application is to
+utilize timeslicing, the clock manager, the timer manager, the
+rate monotonic manager, or the timeout option on blocking
+directives.
+
+The clock tick is usually provided as an interrupt
+from a counter/timer or a real-time clock device. When a
+counter/timer is used to provide the clock tick, the device is
+typically programmed to operate in continuous mode. This mode
+selection causes the device to automatically reload the initial
+count and continue the countdown without programmer
+intervention. This reduces the overhead required to manipulate
+the counter/timer in the clock tick ISR and increases the
+accuracy of tick occurrences. The initial count can be based on
+the microseconds_per_tick field in the RTEMS Configuration
+Table. An alternate approach is to set the initial count for a
+fixed time period (such as one millisecond) and have the ISR
+invoke clock_tick on the microseconds_per_tick boundaries.
+Obviously, this can induce some error if the configured
+microseconds_per_tick is not evenly divisible by the chosen
+clock interrupt quantum.
+
+It is important to note that the interval between
+clock ticks directly impacts the granularity of RTEMS timing
+operations. In addition, the frequency of clock ticks is an
+important factor in the overall level of system overhead. A
+high clock tick frequency results in less processor time being
+available for task execution due to the increased number of
+clock tick ISRs.
+
+@ifinfo
+@node Board Support Packages User Extensions, Board Support Packages Multiprocessor Communications Interface (MPCI), Clock Tick Device Driver, Board Support Packages
+@end ifinfo
+@section User Extensions
+
+RTEMS allows the application developer to augment
+selected features by invoking user-supplied extension routines
+when the following system events occur:
+
+@itemize @bullet
+@item Task creation
+@item Task initiation
+@item Task reinitiation
+@item Task deletion
+@item Task context switch
+@item Post task context switch
+@item Task begin
+@item Task exits
+@item Fatal error detection
+@end itemize
+
+User extensions can be used to implement a wide variety of
+functions including execution profiling, non-standard
+coprocessor support, debug support, and error detection and
+recovery. For example, the context of a non-standard numeric
+coprocessor may be maintained via the user extensions. In this
+example, the task creation and deletion extensions are
+responsible for allocating and deallocating the context area,
+the task initiation and reinitiation extensions would be
+responsible for priming the context area, and the task context
+switch extension would save and restore the context of the
+device.
+
+For more information on user extensions, refer to the
+User Extensions chapter.
+
+@ifinfo
+@node Board Support Packages Multiprocessor Communications Interface (MPCI), Tightly-Coupled Systems, Board Support Packages User Extensions, Board Support Packages
+@end ifinfo
+@section Multiprocessor Communications Interface (MPCI)
+@ifinfo
+@menu
+* Tightly-Coupled Systems::
+* Loosely-Coupled Systems::
+* Systems with Mixed Coupling::
+* Heterogeneous Systems::
+@end menu
+@end ifinfo
+
+RTEMS requires that an MPCI layer be provided when a
+multiple node application is developed. This MPCI layer must
+provide an efficient and reliable communications mechanism
+between the multiple nodes. Tasks on different nodes
+communicate and synchronize with one another via the MPCI. Each
+MPCI layer must be tailored to support the architecture of the
+target platform.
+
+For more information on the MPCI, refer to the
+Multiprocessing Manager chapter.
+
+@ifinfo
+@node Tightly-Coupled Systems, Loosely-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI), Board Support Packages Multiprocessor Communications Interface (MPCI)
+@end ifinfo
+@subsection Tightly-Coupled Systems
+
+A tightly-coupled system is a multiprocessor
+configuration in which the processors communicate solely via
+shared global memory. The MPCI can simply place the RTEMS
+packets in the shared memory space. The two primary
+considerations when designing an MPCI for a tightly-coupled
+system are data consistency and informing another node of a
+packet.
+
+The data consistency problem may be solved using
+atomic "test and set" operations to provide a "lock" in the
+shared memory. It is important to minimize the length of time
+any particular processor locks a shared data structure.
+
+The problem of informing another node of a packet can
+be addressed using one of two techniques. The first technique
+is to use an interprocessor interrupt capability to cause an
+interrupt on the receiving node. This technique requires that
+special support hardware be provided by either the processor
+itself or the target platform. The second technique is to have
+a node poll for arrival of packets. The drawback to this
+technique is the overhead associated with polling.
+
+@ifinfo
+@node Loosely-Coupled Systems, Systems with Mixed Coupling, Tightly-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI)
+@end ifinfo
+@subsection Loosely-Coupled Systems
+
+A loosely-coupled system is a multiprocessor
+configuration in which the processors communicate via some type
+of communications link which is not shared global memory. The
+MPCI sends the RTEMS packets across the communications link to
+the destination node. The characteristics of the communications
+link vary widely and have a significant impact on the MPCI
+layer. For example, the bandwidth of the communications link
+has an obvious impact on the maximum MPCI throughput.
+
+The characteristics of a shared network, such as
+Ethernet, lend themselves to supporting an MPCI layer. These
+networks provide both the point-to-point and broadcast
+capabilities which are expected by RTEMS.
+
+@ifinfo
+@node Systems with Mixed Coupling, Heterogeneous Systems, Loosely-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI)
+@end ifinfo
+@subsection Systems with Mixed Coupling
+
+A mixed-coupling system is a multiprocessor
+configuration in which the processors communicate via both
+shared memory and communications links. A unique characteristic
+of mixed-coupling systems is that a node may not have access to
+all communication methods. There may be multiple shared memory
+areas and communication links. Therefore, one of the primary
+functions of the MPCI layer is to efficiently route RTEMS
+packets between nodes. This routing may be based on numerous
+algorithms. In addition, the router may provide alternate
+communications paths in the event of an overload or a partial
+failure.
+
+@ifinfo
+@node Heterogeneous Systems, User Extensions Manager, Systems with Mixed Coupling, Board Support Packages Multiprocessor Communications Interface (MPCI)
+@end ifinfo
+@subsection Heterogeneous Systems
+
+Designing an MPCI layer for a heterogeneous system
+requires special considerations by the developer. RTEMS is
+designed to eliminate many of the problems associated with
+sharing data in a heterogeneous environment. The MPCI layer
+need only address the representation of thirty-two (32) bit
+unsigned quantities.
+
+For more information on supporting a heterogeneous
+system, refer the Supporting Heterogeneous Environments in the
+Multiprocessing Manager chapter.
diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi
new file mode 100644
index 0000000000..625f9f934d
--- /dev/null
+++ b/doc/user/c_user.texi
@@ -0,0 +1,159 @@
+\input ../texinfo/texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename c_user
+@syncodeindex vr fn
+@synindex ky cp
+@paragraphindent 0
+@c @smallbook
+@c %**end of header
+
+@c
+@c COPYRIGHT (c) 1988-1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@c
+@c Master file for the C User's Guide
+@c
+
+@c Joel's Questions
+@c
+@c 1. Why does paragraphindent only impact makeinfo?
+@c 2. Why does paragraphindent show up in HTML?
+@c
+
+@include ../common/setup.texi
+
+@ignore
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* RTEMS C User: (c_user). The C User's Guide
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@end ignore
+
+@c variable substitution info:
+@c
+@c @set RTEMS-LANGUAGE C
+@c the language is @value{RTEMS-LANGUAGE}
+@c NOTE: don't use underscore in the name
+@c
+
+@c
+@c Title Page Stuff
+@c
+
+@set edition 4.0.0a
+@set update-date 25 April 1997
+@set update-month April 1997
+
+@c
+@c I don't really like having a short title page. --joel
+@c
+@c @shorttitlepage RTEMS Applications C User's Guide
+
+@setchapternewpage odd
+@settitle RTEMS C User's Guide
+@titlepage
+@finalout
+
+@title RTEMS Applications C User's Guide
+@subtitle Edition @value{edition}, for RTEMS 4.0.0
+@sp 1
+@subtitle @value{update-month}
+@author On-Line Applications Research Corporation
+@page
+@include ../common/cpright.texi
+@end titlepage
+
+@c This prevents a black box from being printed on "overflow" lines.
+@c The alternative is to rework a sentence to avoid this problem.
+
+@include preface.texi
+@include overview.texi
+@include concepts.texi
+@include init.texi
+@include task.texi
+@include intr.texi
+@include clock.texi
+@include timer.texi
+@include sem.texi
+@include msg.texi
+@include event.texi
+@include signal.texi
+@include part.texi
+@include region.texi
+@include dpmem.texi
+@include io.texi
+@include fatal.texi
+@include schedule.texi
+@include rtmon.texi
+@include bsp.texi
+@include userext.texi
+@include conf.texi
+@include mp.texi
+@include dirstat.texi
+@include example.texi
+@include glossary.texi
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top c_user
+
+This is the online version of the RTEMS C User's Guide.
+
+@menu
+* Preface::
+* Overview::
+* Key Concepts::
+* Initialization Manager::
+* Task Manager::
+* Interrupt Manager::
+* Clock Manager::
+* Timer Manager::
+* Semaphore Manager::
+* Message Manager::
+* Event Manager::
+* Signal Manager::
+* Partition Manager::
+* Region Manager::
+* Dual-Ported Memory Manager::
+* I/O Manager::
+* Fatal Error Manager::
+* Scheduling Concepts::
+* Rate Monotonic Manager::
+* Board Support Packages::
+* User Extensions Manager::
+* Configuring a System::
+* Multiprocessing Manager::
+* Directive Status Codes::
+* Example Application::
+* Glossary::
+* Command and Variable Index::
+* Concept Index::
+@end menu
+
+@end ifinfo
+@c
+@c
+@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
+@c
+
+@node Command and Variable Index, Concept Index, Glossary, Top
+@unnumbered Command and Variable Index
+
+There are currently no Command and Variable Index entries.
+
+@c @printindex fn
+
+@node Concept Index, , Command and Variable Index, Top
+@unnumbered Concept Index
+
+There are currently no Concept Index entries.
+@c @printindex cp
+
+@contents
+@bye
+
diff --git a/doc/user/clock.t b/doc/user/clock.t
new file mode 100644
index 0000000000..f90d5c20b6
--- /dev/null
+++ b/doc/user/clock.t
@@ -0,0 +1,356 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Clock Manager, Clock Manager Introduction, INTERRUPT_CATCH - Establish an ISR, Top
+@end ifinfo
+@chapter Clock Manager
+@ifinfo
+@menu
+* Clock Manager Introduction::
+* Clock Manager Background::
+* Clock Manager Operations::
+* Clock Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Clock Manager Introduction, Clock Manager Background, Clock Manager, Clock Manager
+@end ifinfo
+@section Introduction
+
+The clock manager provides support for time of day
+and other time related capabilities. The directives provided by
+the clock manager are:
+
+@itemize @bullet
+@item @code{clock_set} - Set system date and time
+@item @code{clock_get} - Get system date and time information
+@item @code{clock_tick} - Announce a clock tick
+@end itemize
+
+@ifinfo
+@node Clock Manager Background, Required Support, Clock Manager Introduction, Clock Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Required Support::
+* Time and Date Data Structures::
+* Clock Tick and Timeslicing::
+* Delays::
+* Timeouts::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Required Support, Time and Date Data Structures, Clock Manager Background, Clock Manager Background
+@end ifinfo
+@subsection Required Support
+
+For the features provided by the clock manager to be
+utilized, periodic timer interrupts are required. Therefore, a
+real-time clock or hardware timer is necessary to create the
+timer interrupts. The clock_tick directive is normally called
+by the timer ISR to announce to RTEMS that a system clock tick
+has occurred. Elapsed time is measured in ticks. A tick is
+defined to be an integral number of microseconds which is
+specified by the user in the Configuration Table.
+
+@ifinfo
+@node Time and Date Data Structures, Clock Tick and Timeslicing, Required Support, Clock Manager Background
+@end ifinfo
+@subsection Time and Date Data Structures
+
+The clock facilities of the clock manager operate
+upon calendar time. These directives utilize the following date
+and time structure for the native time and date format:
+
+@example
+struct rtems_tod_control @{
+ rtems_unsigned32 year; /* greater than 1987 */
+ rtems_unsigned32 month; /* 1 - 12 */
+ rtems_unsigned32 day; /* 1 - 31 */
+ rtems_unsigned32 hour; /* 0 - 23 */
+ rtems_unsigned32 minute; /* 0 - 59 */
+ rtems_unsigned32 second; /* 0 - 59 */
+ rtems_unsigned32 ticks; /* elapsed between seconds */
+@};
+
+typedef struct rtems_tod_control rtems_time_of_day;
+@end example
+
+
+The native date and time format is the only format
+supported when setting the system date and time using the
+clock_get directive. Some applications expect to operate on a
+"UNIX-style" date and time data structure. The clock_get
+directive can optionally return the current date and time in the
+following structure:
+
+@example
+@group
+typedef struct @{
+ rtems_unsigned32 seconds; /* seconds since RTEMS epoch*/
+ rtems_unsigned32 microseconds; /* since last second */
+@} rtems_clock_time_value_control;
+@end group
+@end example
+
+
+The seconds field in this structure is the number of
+seconds since the RTEMS epoch of January 1, 1988.
+
+@ifinfo
+@node Clock Tick and Timeslicing, Delays, Time and Date Data Structures, Clock Manager Background
+@end ifinfo
+@subsection Clock Tick and Timeslicing
+
+Timeslicing is a task scheduling discipline in which
+tasks of equal priority are executed for a specific period of
+time before control of the CPU is passed to another task. It is
+also sometimes referred to as the automatic round-robin
+scheduling algorithm. The length of time allocated to each task
+is known as the quantum or timeslice.
+
+The system's timeslice is defined as an integral
+number of ticks, and is specified in the Configuration Table.
+The timeslice is defined for the entire system of tasks, but
+timeslicing is enabled and disabled on a per task basis.
+
+The clock_tick directive implements timeslicing by
+decrementing the running task's time-remaining counter when both
+timeslicing and preemption are enabled. If the task's timeslice
+has expired, then that task will be preempted if there exists a
+ready task of equal priority.
+
+@ifinfo
+@node Delays, Timeouts, Clock Tick and Timeslicing, Clock Manager Background
+@end ifinfo
+@subsection Delays
+
+A sleep timer allows a task to delay for a given
+interval or up until a given time, and then wake and continue
+execution. This type of timer is created automatically by the
+task_wake_after and task_wake_when directives and, as a result,
+does not have an RTEMS ID. Once activated, a sleep timer cannot
+be explicitly deleted. Each task may activate one and only one
+sleep timer at a time.
+
+@ifinfo
+@node Timeouts, Clock Manager Operations, Delays, Clock Manager Background
+@end ifinfo
+@subsection Timeouts
+
+Timeouts are a special type of timer automatically
+created when the timeout option is used on the
+message_queue_receive, event_receive, semaphore_obtain and
+region_get_segment directives. Each task may have one and only
+one timeout active at a time. When a timeout expires, it
+unblocks the task with a timeout status code.
+
+@ifinfo
+@node Clock Manager Operations, Announcing a Tick, Timeouts, Clock Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Announcing a Tick::
+* Setting the Time::
+* Obtaining the Time::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Announcing a Tick, Setting the Time, Clock Manager Operations, Clock Manager Operations
+@end ifinfo
+@subsection Announcing a Tick
+
+RTEMS provides the clock_tick directive which is
+called from the user's real-time clock ISR to inform RTEMS that
+a tick has elapsed. The tick frequency value, defined in
+microseconds, is a configuration parameter found in the
+Configuration Table. RTEMS divides one million microseconds
+(one second) by the number of microseconds per tick to determine
+the number of calls to the clock_tick directive per second. The
+frequency of clock_tick calls determines the resolution
+(granularity) for all time dependent RTEMS actions. For
+example, calling clock_tick ten times per second yields a higher
+resolution than calling clock_tick two times per second. The
+clock_tick directive is responsible for maintaining both
+calendar time and the dynamic set of timers.
+
+@ifinfo
+@node Setting the Time, Obtaining the Time, Announcing a Tick, Clock Manager Operations
+@end ifinfo
+@subsection Setting the Time
+
+The clock_set directive allows a task or an ISR to
+set the date and time maintained by RTEMS. If setting the date
+and time causes any outstanding timers to pass their deadline,
+then the expired timers will be fired during the invocation of
+the clock_set directive.
+
+@ifinfo
+@node Obtaining the Time, Clock Manager Directives, Setting the Time, Clock Manager Operations
+@end ifinfo
+@subsection Obtaining the Time
+
+The clock_get directive allows a task or an ISR to
+obtain the current date and time or date and time related
+information. The current date and time can be returned in
+either native or UNIX-style format. Additionally, the
+application can obtain date and time related information such as
+the number of seconds since the RTEMS epoch, the number of ticks
+since the executive was initialized, and the number of ticks per
+second. The information returned by the clock_get directive is
+dependent on the option selected by the caller. The following
+options are available:
+
+@itemize @bullet
+@item CLOCK_GET_TOD - obtain native style date and time
+@item CLOCK_GET_TIME_VALUE - obtain UNIX-style date and time
+@item CLOCK_GET_TICKS_SINCE_BOOT - obtain number of ticks since RTEMS was initialized
+@item CLOCK_GET_SECONDS_SINCE_EPOCH - obtain number of seconds since RTEMS epoch
+@item CLOCK_GET_TICKS_PER_SECOND - obtain number of clock ticks per second
+@end itemize
+
+Calendar time operations will return an error code if
+invoked before the date and time have been set.
+
+@ifinfo
+@node Clock Manager Directives, CLOCK_SET - Set system date and time, Obtaining the Time, Clock Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* CLOCK_SET - Set system date and time::
+* CLOCK_GET - Get system date and time information::
+* CLOCK_TICK - Announce a clock tick::
+@end menu
+@end ifinfo
+
+This section details the clock manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@ifinfo
+@node CLOCK_SET - Set system date and time, CLOCK_GET - Get system date and time information, Clock Manager Directives, Clock Manager Directives
+@end ifinfo
+@subsection CLOCK_SET - Set system date and time
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_clock_set(
+ rtems_time_of_day *time_buffer
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - date and time set successfully@*
+@code{INVALID_TIME_OF_DAY} - invalid time of day
+
+@subheading DESCRIPTION:
+
+This directive sets the system date and time. The
+date, time, and ticks in the time_buffer structure are all
+range-checked, and an error is returned if any one is out of its
+valid range.
+
+@subheading NOTES:
+
+Years before 1988 are invalid.
+
+The system date and time are based on the configured
+tick rate (number of microseconds in a tick).
+
+Setting the time forward may cause a higher priority
+task, blocked waiting on a specific time, to be made ready. In
+this case, the calling task will be preempted after the next
+clock tick.
+
+Re-initializing RTEMS causes the system date and time
+to be reset to an uninitialized state. Another call to
+clock_set is required to re-initialize the system date and time
+to application specific specifications.
+
+@page
+@ifinfo
+@node CLOCK_GET - Get system date and time information, CLOCK_TICK - Announce a clock tick, CLOCK_SET - Set system date and time, Clock Manager Directives
+@end ifinfo
+@subsection CLOCK_GET - Get system date and time information
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_clock_get(
+ rtems_clock_get_options option,
+ void *time_buffer
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - current time obtained successfully@*
+@code{NOT_DEFINED} - system date and time is not set
+
+@subheading DESCRIPTION:
+
+This directive obtains the system date and time. If
+the caller is attempting to obtain the date and time (i.e.
+option is set to either CLOCK_GET_SECONDS_SINCE_EPOCH,
+CLOCK_GET_TOD, or CLOCK_GET_TIME_VALUE) and the date and time
+has not been set with a previous call to clock_set, then the
+NOT_DEFINED status code is returned. The caller can always
+obtain the number of ticks per second (option is
+CLOCK_GET_TICKS_PER_SECOND) and the number of ticks since the
+executive was initialized option is CLOCK_GET_TICKS_SINCE_BOOT).
+
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be
+preempted. Re-initializing RTEMS causes the system date and
+time to be reset to an uninitialized state. Another call to
+clock_set is required to re-initialize the system date and time
+to application specific specifications.
+
+@page
+@ifinfo
+@node CLOCK_TICK - Announce a clock tick, Timer Manager, CLOCK_GET - Get system date and time information, Clock Manager Directives
+@end ifinfo
+@subsection CLOCK_TICK - Announce a clock tick
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_clock_tick( void );
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - current time obtained successfully
+
+@subheading DESCRIPTION:
+
+This directive announces to RTEMS that a system clock
+tick has occurred. The directive is usually called from the
+timer interrupt ISR of the local processor. This directive
+maintains the system date and time, decrements timers for
+delayed tasks, timeouts, rate monotonic periods, and implements
+timeslicing.
+
+@subheading NOTES:
+
+This directive is typically called from an ISR.
+
+The microseconds_per_tick and ticks_per_timeslice
+parameters in the Configuration Table contain the number of
+microseconds per tick and number of ticks per timeslice,
+respectively.
+
diff --git a/doc/user/concepts.t b/doc/user/concepts.t
new file mode 100644
index 0000000000..fabcfdf57d
--- /dev/null
+++ b/doc/user/concepts.t
@@ -0,0 +1,322 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@c
+@c The following figure was replaced with an ASCII equivalent.
+@c Figure 2-1 Object ID Composition
+@c
+@ifinfo
+@node Key Concepts, Key Concepts Introduction, Overview Manual Organization, Top
+@end ifinfo
+@chapter Key Concepts
+@ifinfo
+@menu
+* Key Concepts Introduction::
+* Key Concepts Objects::
+* Key Concepts Communication and Synchronization::
+* Key Concepts Time::
+* Key Concepts Memory Management::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Key Concepts Introduction, Key Concepts Objects, Key Concepts, Key Concepts
+@end ifinfo
+@section Introduction
+
+The facilities provided by RTEMS are built upon a
+foundation of very powerful concepts. These concepts must be
+understood before the application developer can efficiently
+utilize RTEMS. The purpose of this chapter is to familiarize
+one with these concepts.
+
+@ifinfo
+@node Key Concepts Objects, Key Concepts Communication and Synchronization, Key Concepts Introduction, Key Concepts
+@end ifinfo
+@section Objects
+
+RTEMS provides directives which can be used to
+dynamically create, delete, and manipulate a set of predefined
+object types. These types include tasks, message queues,
+semaphores, memory regions, memory partitions, timers, ports,
+and rate monotonic periods. The object-oriented nature of RTEMS
+encourages the creation of modular applications built upon
+re-usable "building block" routines.
+
+All objects are created on the local node as required
+by the application and have an RTEMS assigned ID. All objects
+have a user-assigned name. Although a relationship exists
+between an object's name and its RTEMS assigned ID, the name and
+ID are not identical. Object names are completely arbitrary and
+selected by the user as a meaningful "tag" which may commonly
+reflect the object's use in the application. Conversely, object
+IDs are designed to facilitate efficient object manipulation by
+the executive.
+
+An object name is an unsigned thirty-two bit entity
+associated with the object by the user. Although not required
+by RTEMS, object names are typically composed of four ASCII
+characters which help identify that object. For example, a task
+which causes a light to blink might be called "LITE". Utilities
+are provided to build an object name from four ASCII characters
+and to decompose an object name into four ASCII characters.
+However, it is not required that the application use ASCII
+characters to build object names. For example, if an
+application requires one-hundred tasks, it would be difficult to
+assign meaningful ASCII names to each task. A more convenient
+approach would be to name them the binary values one through
+one-hundred, respectively.
+
+@need 3000
+
+An object ID is a unique unsigned thirty-two bit
+entity composed of three parts: object class, node, and index.
+The most significant six bits are the object class. The next
+ten bits are the number of the node on which this object was
+created. The node number is always one (1) in a single
+processor system. The least significant sixteen bits form an
+identifier within a particular object type. This identifier,
+called the object index, ranges in value from 1 to the maximum
+number of objects configured for this object type.
+
+@ifset use-ascii
+ASCII
+@example
+@group
+ 31 26 25 16 15 0
+ +-----------+------------------+-------------------------------+
+ | | | |
+ | Class | Node | Index |
+ | | | |
+ +-----------+------------------+-------------------------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+@tex
+\centerline{\vbox{\offinterlineskip\halign{
+\strut#&
+\hbox to 0.50in{\enskip#}&
+\hbox to 0.50in{\enskip#}&
+#&
+\hbox to 0.50in{\enskip#}&
+\hbox to 0.50in{\enskip#}&
+#&
+\hbox to 1.00in{\enskip#}&
+\hbox to 1.00in{\enskip#}&
+#\cr
+\multispan{9}\cr
+\multispan{2}31\hfil&\multispan{2}\hfil26\enskip&
+ \multispan{1}\enskip25\hfil&\multispan{2}\hfil16\enskip&
+ \multispan{1}\enskip15\hfil&\multispan{2}\hfil0\cr
+&&&&&&&&&\cr
+}}\hfil}
+\centerline{\vbox{\offinterlineskip\halign{
+\strut\vrule#&
+\hbox to 0.50in{\enskip#}&
+\hbox to 0.50in{\enskip#}&
+\vrule#&
+\hbox to 0.50in{\enskip#}&
+\hbox to 0.50in{\enskip#}&
+\vrule#&
+\hbox to 0.50in{\enskip#}&
+\hbox to 0.50in{\enskip#}&
+\vrule#\cr
+\multispan{9}\cr
+\noalign{\hrule}
+&&&&&&&&&\cr
+&\multispan{2}\hfil Class\hfil&&
+ \multispan{2}\hfil Node\hfil&&
+ \multispan{2}\hfil Index\hfil&\cr
+&&&&&&&&&\cr
+\noalign{\hrule}
+}}\hfil}
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=6 WIDTH="60%" BORDER=0>
+<TR><TD ALIGN=left><STRONG>31</STRONG></TD>
+ <TD ALIGN=right><STRONG>26</STRONG></TD>
+ <TD ALIGN=left><STRONG>25</STRONG></TD>
+ <TD ALIGN=right><STRONG>16</STRONG></TD>
+ <TD ALIGN=left><STRONG>15</STRONG></TD>
+ <TD ALIGN=right><STRONG>0</STRONG></TD></TR>
+ </TABLE>
+</CENTER>
+<CENTER>
+ <TABLE COLS=6 WIDTH="60%" BORDER=2>
+<TR><TD ALIGN=center COLSPAN=2>Class</TD>
+ <TD ALIGN=center COLSPAN=2>Node</TD>
+ <TD ALIGN=center COLSPAN=2>Index</TD></TD>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+
+The three components of an object ID make it possible
+to quickly locate any object in even the most complicated
+multiprocessor system. Object ID's are associated with an
+object by RTEMS when the object is created and the corresponding
+ID is returned by the appropriate object create directive. The
+object ID is required as input to all directives involving
+objects, except those which create an object or obtain the ID of
+an object.
+
+The object identification directives can be used to
+dynamically obtain a particular object's ID given its name.
+This mapping is accomplished by searching the name table
+associated with this object type. If the name is non-unique,
+then the ID associated with the first occurrence of the name
+will be returned to the application. Since object IDs are
+returned when the object is created, the object identification
+directives are not necessary in a properly designed single
+processor application.
+
+An object control block is a data structure defined
+by RTEMS which contains the information necessary to manage a
+particular object type. For efficiency reasons, the format of
+each object type's control block is different. However, many of
+the fields are similar in function. The number of each type of
+control block is application dependent and determined by the
+values specified in the user's Configuration Table. An object
+control block is allocated at object create time and freed when
+the object is deleted. With the exception of user extension
+routines, object control blocks are not directly manipulated by
+user applications.
+
+@ifinfo
+@node Key Concepts Communication and Synchronization, Key Concepts Time, Key Concepts Objects, Key Concepts
+@end ifinfo
+@section Communication and Synchronization
+
+In real-time multitasking applications, the ability
+for cooperating execution threads to communicate and synchronize
+with each other is imperative. A real-time executive should
+provide an application with the following capabilities:
+
+@itemize @bullet
+@item Data transfer between cooperating tasks
+@item Data transfer between tasks and ISRs
+@item Synchronization of cooperating tasks
+@item Synchronization of tasks and ISRs
+@end itemize
+
+Most RTEMS managers can be used to provide some form
+of communication and/or synchronization. However, managers
+dedicated specifically to communication and synchronization
+provide well established mechanisms which directly map to the
+application's varying needs. This level of flexibility allows
+the application designer to match the features of a particular
+manager with the complexity of communication and synchronization
+required. The following managers were specifically designed for
+communication and synchronization:
+
+@itemize @bullet
+@item Semaphore
+@item Message Queue
+@item Event
+@item Signal
+@end itemize
+
+The semaphore manager supports mutual exclusion
+involving the synchronization of access to one or more shared
+user resources. Binary semaphores may utilize the optional
+priority inheritance algorithm to avoid the problem of priority
+inversion. The message manager supports both communication and
+synchronization, while the event manager primarily provides a
+high performance synchronization mechanism. The signal manager
+supports only asynchronous communication and is typically used
+for exception handling.
+
+@ifinfo
+@node Key Concepts Time, Key Concepts Memory Management, Key Concepts Communication and Synchronization, Key Concepts
+@end ifinfo
+@section Time
+
+The development of responsive real-time applications
+requires an understanding of how RTEMS maintains and supports
+time-related operations. The basic unit of time in RTEMS is
+known as a tick. The frequency of clock ticks is completely
+application dependent and determines the granularity and
+accuracy of all interval and calendar time operations.
+
+By tracking time in units of ticks, RTEMS is capable
+of supporting interval timing functions such as task delays,
+timeouts, timeslicing, the delayed execution of timer service
+routines, and the rate monotonic scheduling of tasks. An
+interval is defined as a number of ticks relative to the current
+time. For example, when a task delays for an interval of ten
+ticks, it is implied that the task will not execute until ten
+clock ticks have occurred.
+
+A characteristic of interval timing is that the
+actual interval period may be a fraction of a tick less than the
+interval requested. This occurs because the time at which the
+delay timer is set up occurs at some time between two clock
+ticks. Therefore, the first countdown tick occurs in less than
+the complete time interval for a tick. This can be a problem if
+the clock granularity is large.
+
+The rate monotonic scheduling algorithm is a hard
+real-time scheduling methodology. This methodology provides
+rules which allows one to guarantee that a set of independent
+periodic tasks will always meet their deadlines -- even under
+transient overload conditions. The rate monotonic manager
+provides directives built upon the Clock Manager's interval
+timer support routines.
+
+Interval timing is not sufficient for the many
+applications which require that time be kept in wall time or
+true calendar form. Consequently, RTEMS maintains the current
+date and time. This allows selected time operations to be
+scheduled at an actual calendar date and time. For example, a
+task could request to delay until midnight on New Year's Eve
+before lowering the ball at Times Square.
+
+Obviously, the directives which use intervals or wall
+time cannot operate without some external mechanism which
+provides a periodic clock tick. This clock tick is typically
+provided by a real time clock or counter/timer device.
+
+@ifinfo
+@node Key Concepts Memory Management, Initialization Manager, Key Concepts Time, Key Concepts
+@end ifinfo
+@section Memory Management
+
+RTEMS memory management facilities can be grouped
+into two classes: dynamic memory allocation and address
+translation. Dynamic memory allocation is required by
+applications whose memory requirements vary through the
+application's course of execution. Address translation is
+needed by applications which share memory with another CPU or an
+intelligent Input/Output processor. The following RTEMS
+managers provide facilities to manage memory:
+
+@itemize @bullet
+@item Region
+
+@item Partition
+
+@item Dual Ported Memory
+@end itemize
+
+RTEMS memory management features allow an application
+to create simple memory pools of fixed size buffers and/or more
+complex memory pools of variable size segments. The partition
+manager provides directives to manage and maintain pools of
+fixed size entities such as resource control blocks.
+Alternatively, the region manager provides a more general
+purpose memory allocation scheme that supports variable size
+blocks of memory which are dynamically obtained and freed by the
+application. The dual-ported memory manager provides executive
+support for address translation between internal and external
+dual-ported RAM address space.
diff --git a/doc/user/conf.t b/doc/user/conf.t
new file mode 100644
index 0000000000..126d9b584b
--- /dev/null
+++ b/doc/user/conf.t
@@ -0,0 +1,752 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Configuring a System, Configuring a System Configuration Table, EXTENSION_DELETE - Delete a extension set, Top
+@end ifinfo
+@chapter Configuring a System
+@ifinfo
+@menu
+* Configuring a System Configuration Table::
+* Configuring a System RTEMS API Configuration Table::
+* Configuring a System POSIX API Configuration Table::
+* Configuring a System CPU Dependent Information Table::
+* Configuring a System Initialization Task Table::
+* Configuring a System Driver Address Table::
+* Configuring a System User Extensions Table::
+* Configuring a System Multiprocessor Configuration Table::
+* Configuring a System Multiprocessor Communications Interface Table::
+* Configuring a System Determining Memory Requirements::
+* Configuring a System Sizing the RTEMS RAM Workspace::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Configuring a System Configuration Table, Configuring a System RTEMS API Configuration Table, Configuring a System, Configuring a System
+@end ifinfo
+@section Configuration Table
+
+The RTEMS Configuration Table is used to tailor an
+application for its specific needs. For example, the user can
+configure the number of device drivers or which APIs may be used.
+THe address of the user-defined Configuration Table is passed as an
+argument to the initialize_executive directive, which MUST be
+the first RTEMS directive called. The RTEMS Configuration Table
+is defined in the following C structure:
+
+@example
+@group
+typedef struct @{
+ void *work_space_start;
+ rtems_unsigned32 work_space_size;
+ rtems_unsigned32 maximum_extensions;
+ rtems_unsigned32 microseconds_per_tick;
+ rtems_unsigned32 ticks_per_timeslice;
+ rtems_unsigned32 maximum_devices;
+ rtems_unsigned32 number_of_device_drivers;
+ rtems_driver_address_table *Device_driver_table;
+ rtems_extensions_table *User_extension_table;
+ rtems_multiprocessing_table *User_multiprocessing_table;
+ rtems_api_configuration_table *RTEMS_api_configuration;
+ posix_api_configuration_table *POSIX_api_configuration;
+@} rtems_configuration_table;
+@end group
+@end example
+
+@table @b
+@item work_space_start
+is the address of the RTEMS RAM Workspace.
+This area contains items such as the
+various object control blocks (TCBs, QCBs, ...) and task stacks.
+If the address is not aligned on a four-word boundary, then
+RTEMS will invoke the fatal error handler during
+initialize_executive.
+
+@item work_space_size
+is the calculated size of the
+RTEMS RAM Workspace. The section Sizing the RTEMS RAM Workspace
+details how to arrive at this number.
+
+@item microseconds_per_tick
+is number of microseconds per clock tick.
+
+@item ticks_per_timeslice
+is the number of clock ticks for a timeslice.
+
+@item maximum_devices
+is the maximum number of devices that can be registered.
+
+@item number_of_device_drivers
+is the number of device drivers for the system. There should be
+the same number of entries in the Device Driver Table. If this field
+is zero, then the User_driver_address_table entry should be NULL.
+
+@item Device_driver_table
+is the address of the Device Driver Table. This table contains the entry
+points for each device driver. If the number_of_device_drivers field is zero,
+then this entry should be NULL. The format of this table will be
+discussed below.
+
+@item User_extension_table
+is the address of the User
+Extension Table. This table contains the entry points for the
+static set of optional user extensions. If no user extensions
+are configured, then this entry should be NULL. The format of
+this table will be discussed below.
+
+@item User_multiprocessing_table
+is the address of the Multiprocessor Configuration Table. This
+table contains information needed by RTEMS only when used in a multiprocessor
+configuration. This field must be NULL when RTEMS is used in a
+single processor configuration.
+
+@item RTEMS_api_configuration
+is the address of the RTEMS API Configuration Table. This table
+contains information needed by the RTEMS API. This field should be
+NULL if the RTEMS API is not used. [NOTE: Currently the RTEMS API
+is required to support support components such as BSPs and libraries
+which use this API.]
+
+@item POSIX_api_configuration
+is the address of the POSIX API Configuration Table. This table
+contains information needed by the POSIX API. This field should be
+NULL if the POSIX API is not used.
+
+@end table
+
+@ifinfo
+@node Configuring a System RTEMS API Configuration Table, Configuring a System POSIX API Configuration Table, Configuring a System Configuration Table, Configuring a System
+@end ifinfo
+@section RTEMS API Configuration Table
+
+The RTEMS API Configuration Table is used to configure the
+managers which constitute the RTEMS API for a particular application.
+For example, the user can configure the maximum number of tasks for
+this application. The RTEMS API Configuration Table is defined in
+the following C structure:
+
+@example
+@group
+typedef struct @{
+ rtems_unsigned32 maximum_tasks;
+ rtems_unsigned32 maximum_timers;
+ rtems_unsigned32 maximum_semaphores;
+ rtems_unsigned32 maximum_message_queues;
+ rtems_unsigned32 maximum_partitions;
+ rtems_unsigned32 maximum_regions;
+ rtems_unsigned32 maximum_ports;
+ rtems_unsigned32 maximum_periods;
+ rtems_unsigned32 number_of_initialization_tasks;
+ rtems_initialization_tasks_table *User_initialization_tasks_table;
+@} rtems_api_configuration_table;
+@end group
+@end example
+
+@table @b
+@item maximum_tasks
+is the maximum number of tasks that
+can be concurrently active (created) in the system including
+initialization tasks.
+
+@item maximum_timers
+is the maximum number of timers
+that can be concurrently active in the system.
+
+@item maximum_semaphores
+is the maximum number of
+semaphores that can be concurrently active in the system.
+
+@item maximum_message_queues
+is the maximum number of
+message queues that can be concurrently active in the system.
+
+@item maximum_partitions
+is the maximum number of
+partitions that can be concurrently active in the system.
+
+@item maximum_regions
+is the maximum number of regions
+that can be concurrently active in the system.
+
+@item maximum_ports
+is the maximum number of ports into
+dual-port memory areas that can be concurrently active in the
+system.
+
+@item number_of_initialization_tasks
+is the number of initialization tasks configured. At least one
+initialization task must be configured.
+
+@item User_initialization_tasks_table
+is the address of the Initialization Task Table. This table contains the
+information needed to create and start each of the
+initialization tasks. The format of this table will be discussed below.
+
+@end table
+
+@ifinfo
+@node Configuring a System POSIX API Configuration Table, Configuring a System CPU Dependent Information Table, Configuring a System RTEMS API Configuration Table, Configuring a System
+@end ifinfo
+@section POSIX API Configuration Table
+
+The POSIX API Configuration Table is used to configure the
+managers which constitute the POSIX API for a particular application.
+For example, the user can configure the maximum number of threads for
+this application. The POSIX API Configuration Table is defined in
+the following C structure:
+
+@example
+@group
+typedef struct @{
+ void *(*entry)(void *);
+@} posix_initialization_threads_table;
+
+typedef struct @{
+ int maximum_threads;
+ int maximum_mutexes;
+ int maximum_condition_variables;
+ int maximum_keys;
+ int maximum_queued_signals;
+ int number_of_initialization_tasks;
+ posix_initialization_threads_table *User_initialization_tasks_table;
+@} posix_api_configuration_table;
+@end group
+@end example
+
+@table @b
+@item maximum_threads
+is the maximum number of threads that
+can be concurrently active (created) in the system including
+initialization threads.
+
+@item maximum_mutexes
+is the maximum number of mutexes that can be concurrently
+active in the system.
+
+@item maximum_condition_variables
+is the maximum number of condition variables that can be
+concurrently active in the system.
+
+@item maximum_keys
+is the maximum number of keys that can be concurrently active in the system.
+
+@item maximum_queued_signals
+is the maximum number of queued signals that can be concurrently
+pending in the system.
+
+@item number_of_initialization_threads
+is the number of initialization threads configured. At least one
+initialization threads must be configured.
+
+@item User_initialization_threads_table
+is the address of the Initialization Threads Table. This table contains the
+information needed to create and start each of the initialization threads.
+The format of each entry in this table is defined in the
+posix_initialization_threads_table structure.
+
+@end table
+
+@ifinfo
+@node Configuring a System CPU Dependent Information Table, Configuring a System Initialization Task Table, Configuring a System POSIX API Configuration Table, Configuring a System
+@end ifinfo
+@section CPU Dependent Information Table
+
+The CPU Dependent Information Table is used to
+describe processor dependent information required by RTEMS.
+This table is generally used to supply RTEMS with information
+only known by the Board Support Package. The contents of this
+table are discussed in the CPU Dependent Information Table
+chapter of the C Applications Supplement document for a specific
+target processor.
+
+@ifinfo
+@node Configuring a System Initialization Task Table, Configuring a System Driver Address Table, Configuring a System CPU Dependent Information Table, Configuring a System
+@end ifinfo
+@section Initialization Task Table
+
+The Initialization Task Table is used to describe
+each of the user initialization tasks to the Initialization
+Manager. The table contains one entry for each initialization
+task the user wishes to create and start. The fields of this
+data structure directly correspond to arguments to the
+task_create and task_start directives. The number of entries is
+found in the number_of_initialization_tasks entry in the
+Configuration Table. The format of each entry in the
+Initialization Task Table is defined in the following C
+structure:
+
+@example
+typedef struct @{
+ rtems_name name;
+ rtems_unsigned32 stack_size;
+ rtems_task_priority initial_priority;
+ rtems_attribute attribute_set;
+ rtems_task_entry entry_point;
+ rtems_mode mode_set;
+ rtems_task_argument argument;
+@} rtems_initialization_tasks_table;
+@end example
+
+@table @b
+@item name
+is the name of this initialization task.
+
+@item stack_size
+is the size of the stack for this initialization task.
+
+@item initial_priority
+is the priority of this initialization task.
+
+@item attribute_set
+is the attribute set used during creation of this initialization task.
+
+@item entry_point
+is the address of the entry point of this initialization task.
+
+@item mode_set
+is the initial execution mode of this initialization task.
+
+@item argument
+is the initial argument for this initialization task.
+
+@end table
+
+A typical declaration for an Initialization Task Table might appear as follows:
+
+@example
+rtems_initialization_tasks_table
+Initialization_tasks[2] = @{
+ @{ INIT_1_NAME,
+ 1024,
+ 1,
+ DEFAULT_ATTRIBUTES,
+ Init_1,
+ DEFAULT_MODES,
+ 1
+
+ @},
+ @{ INIT_2_NAME,
+ 1024,
+ 250,
+ FLOATING_POINT,
+ Init_2,
+ INTERRUPT_LEVEL(0)|NO_PREEMPT,
+ 2
+
+ @}
+@};
+@end example
+
+@ifinfo
+@node Configuring a System Driver Address Table, Configuring a System User Extensions Table, Configuring a System Initialization Task Table, Configuring a System
+@end ifinfo
+@section Driver Address Table
+
+The Device Driver Table is used to inform the I/O
+Manager of the set of entry points for each device driver
+configured in the system. The table contains one entry for each
+device driver required by the application. The number of
+entries is defined in the number_of_device_drivers entry in the
+Configuration Table. The format of each entry in the Device
+Driver Table is defined in the following C structure:
+
+@example
+typedef struct @{
+ rtems_device_driver_entry initialization;
+ rtems_device_driver_entry open;
+ rtems_device_driver_entry close;
+ rtems_device_driver_entry read;
+ rtems_device_driver_entry write;
+ rtems_device_driver_entry control;
+@} rtems_driver_address_table;
+@end example
+
+@table @b
+@item initialization
+is the address of the entry point called by io_initialize
+to initialize a device driver and its associated devices.
+
+@item open
+is the address of the entry point called by io_open.
+
+@item close
+is the address of the entry point called by io_close.
+
+@item read
+is the address of the entry point called by io_read.
+
+@item write
+is the address of the entry point called by io_write.
+
+@item control
+is the address of the entry point called by io_control.
+
+@end table
+
+Driver entry points configured as NULL will always
+return a status code of SUCCESSFUL. No user code will be
+executed in this situation.
+
+A typical declaration for a Device Driver Table might appear as follows:
+
+@example
+rtems_driver_address_table Driver_table[2] = @{
+ @{ tty_initialize, tty_open, tty_close, /* major = 0 */
+ tty_read, tty_write, tty_control
+ @},
+ @{ lp_initialize, lp_open, lp_close, /* major = 1 */
+ NULL, lp_write, lp_control
+ @}
+@};
+@end example
+
+More information regarding the construction and
+operation of device drivers is provided in the I/O Manager
+chapter.
+
+@ifinfo
+@node Configuring a System User Extensions Table, Configuring a System Multiprocessor Configuration Table, Configuring a System Driver Address Table, Configuring a System
+@end ifinfo
+@section User Extensions Table
+
+The User Extensions Table is used to inform RTEMS of
+the optional user-supplied static extension set. This table
+contains one entry for each possible extension. The entries are
+called at critical times in the life of the system and
+individual tasks. The application may create dynamic extensions
+in addition to this single static set. The format of each entry
+in the User Extensions Table is defined in the following C
+structure:
+
+@example
+typedef struct @{
+ User_extensions_thread_create_extension thread_create;
+ User_extensions_thread_start_extension thread_start;
+ User_extensions_thread_restart_extension thread_restart;
+ User_extensions_thread_delete_extension thread_delete;
+ User_extensions_thread_switch_extension thread_switch;
+ User_extensions_thread_post_switch_extension thread_post_switch;
+ User_extensions_thread_begin_extension thread_begin;
+ User_extensions_thread_exitted_extension thread_exitted;
+ User_extensions_fatal_error_extension fatal;
+@} User_extensions_Table;
+@end example
+
+@table @b
+
+@item thread_create
+is the address of the
+user-supplied subroutine for the TASK_CREATE extension. If this
+extension for task creation is defined, it is called from the
+task_create directive. A value of NULL indicates that no
+extension is provided.
+
+@item thread_start
+is the address of the user-supplied
+subroutine for the TASK_START extension. If this extension for
+task initiation is defined, it is called from the task_start
+directive. A value of NULL indicates that no extension is
+provided.
+
+@item thread_restart
+is the address of the user-supplied
+subroutine for the TASK_RESTART extension. If this extension
+for task re-initiation is defined, it is called from the
+task_restart directive. A value of NULL indicates that no
+extension is provided.
+
+@item thread_delete
+is the address of the user-supplied
+subroutine for the TASK_DELETE extension. If this RTEMS
+extension for task deletion is defined, it is called from the
+task_delete directive. A value of NULL indicates that no
+extension is provided.
+
+@item thread_switch
+is the address of the user-supplied
+subroutine for the task context switch extension. This
+subroutine is called from RTEMS dispatcher after the current
+task has been swapped out but before the new task has been
+swapped in. A value of NULL indicates that no extension is
+provided. As this routine is invoked after saving the current
+task's context and before restoring the heir task's context, it
+is not necessary for this routine to save and restore any
+registers.
+
+@item thread_post_switch
+is the address of the
+user-supplied subroutine for the post task context switch
+extension. This subroutine is called from RTEMS dispatcher in
+the context of the task which has just been swapped in.
+
+@item thread_begin
+is the address of the user-supplied
+subroutine which is invoked immediately before a task begins
+execution. It is invoked in the context of the beginning task.
+A value of NULL indicates that no extension is provided.
+
+@item thread_exitted
+is the address of the user-supplied
+subroutine which is invoked when a task exits. This procedure
+is responsible for some action which will allow the system to
+continue execution (i.e. delete or restart the task) or to
+terminate with a fatal error. If this field is set to NULL, the
+default RTEMS task_exitted handler will be invoked.
+
+@item fatal
+is the address of the user-supplied
+subroutine for the FATAL extension. This RTEMS extension of
+fatal error handling is called from the fatal_error_occurred
+directive. If the user's fatal error handler returns or if this
+entry is NULL then the default RTEMS fatal error handler will be
+executed.
+
+@end table
+
+A typical declaration for a User Extension Table
+which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
+FATAL extension might appear as follows:
+
+@example
+rtems_extensions_table User_extensions = @{
+ task_create_extension,
+ NULL,
+ NULL,
+ task_delete_extension,
+ task_switch_extension,
+ NULL,
+ NULL,
+ fatal_extension
+@};
+@end example
+
+More information regarding the user extensions is
+provided in the User Extensions chapter.
+
+@ifinfo
+@node Configuring a System Multiprocessor Configuration Table, Configuring a System Multiprocessor Communications Interface Table, Configuring a System User Extensions Table, Configuring a System
+@end ifinfo
+@section Multiprocessor Configuration Table
+
+The Multiprocessor Configuration Table contains
+information needed when using RTEMS in a multiprocessor
+configuration. Many of the details associated with configuring
+a multiprocessor system are dependent on the multiprocessor
+communications layer provided by the user. The address of the
+Multiprocessor Configuration Table should be placed in the
+User_multiprocessing_table entry in the primary Configuration
+Table. Further details regarding many of the entries in the
+Multiprocessor Configuration Table will be provided in the
+Multiprocessing chapter. The format of the Multiprocessor
+Configuration Table is defined in the following C structure:
+
+@example
+typedef struct @{
+ rtems_unsigned32 node;
+ rtems_unsigned32 maximum_nodes;
+ rtems_unsigned32 maximum_global_objects;
+ rtems_unsigned32 maximum_proxies;
+ rtems_mpci_table *User_mpci_table;
+@} rtems_multiprocessing_table;
+@end example
+
+@table @b
+@item node
+is a unique processor identifier
+and is used in routing messages between nodes in a
+multiprocessor configuration. Each processor must have a unique
+node number. RTEMS assumes that node numbers start at one and
+increase sequentially. This assumption can be used to advantage
+by the user-supplied MPCI layer. Typically, this requirement is
+made when the node numbers are used to calculate the address of
+inter-processor communication links. Zero should be avoided as
+a node number because some MPCI layers use node zero to
+represent broadcasted packets. Thus, it is recommended that
+node numbers start at one and increase sequentially.
+
+@item maximum_nodes
+is the number of processor nodes in the system.
+
+@item maximum_global_objects
+is the maximum number of global objects which can exist at any
+given moment in the entire system. If this parameter is not the
+same on all nodes in the system, then a fatal error is generated
+to inform the user that the system is inconsistent.
+
+@item maximum_proxies
+is the maximum number of proxies which can exist at any given moment
+on this particular node. A proxy is a substitute task control block
+which represent a task residing on a remote node when that task blocks
+on a remote object. Proxies are used in situations in which delayed
+interaction is required with a remote node.
+
+@item User_mpci_table
+is the address of the Multiprocessor Communications Interface
+Table. This table contains the entry points of user-provided functions
+which constitute the multiprocessor communications layer. This table
+must be provided in multiprocessor configurations with all
+entries configured. The format of this table and details
+regarding its entries can be found in the next section.
+
+@end table
+
+@ifinfo
+@node Configuring a System Multiprocessor Communications Interface Table, Configuring a System Determining Memory Requirements, Configuring a System Multiprocessor Configuration Table, Configuring a System
+@end ifinfo
+@section Multiprocessor Communications Interface Table
+
+The format of this table is defined in the following C structure:
+
+@example
+typedef struct @{
+ rtems_unsigned32 default_timeout; /* in ticks */
+ rtems_unsigned32 maximum_packet_size;
+ rtems_mpci_initialization_entry initialization;
+ rtems_mpci_get_packet_entry get_packet;
+ rtems_mpci_return_packet_entry return_packet;
+ rtems_mpci_send_entry send;
+ rtems_mpci_receive_entry receive;
+@} rtems_mpci_table;
+@end example
+
+@table @b
+@item default_timeout
+is the default maximum length of time a task should block waiting for
+a response to a directive which results in communication with a remote node.
+The maximum length of time is a function the user supplied
+multiprocessor communications layer and the media used. This
+timeout only applies to directives which would not block if the
+operation were performed locally.
+
+@item maximum_packet_size
+is the size in bytes of the longest packet which the MPCI layer is capable
+of sending. This value should represent the total number of bytes available
+for a RTEMS interprocessor messages.
+
+@item initialization
+is the address of the entry point for the initialization procedure of the
+user supplied multiprocessor communications layer.
+
+@item get_packet
+is the address of the entry point for the procedure called by RTEMS to
+obtain a packet from the user supplied multiprocessor communications layer.
+
+@item return_packet
+is the address of the entry point for the procedure called by RTEMS to
+return a packet to the user supplied multiprocessor communications layer.
+
+@item send
+is the address of the entry point for the procedure called by RTEMS to
+send an envelope to another node. This procedure is part of the user
+supplied multiprocessor communications layer.
+
+@item receive
+is the address of the entry point for the
+procedure called by RTEMS to retrieve an envelope containing a
+message from another node. This procedure is part of the user
+supplied multiprocessor communications layer.
+
+@end table
+
+More information regarding the required functionality of these
+entry points is provided in the Multiprocessor chapter.
+
+@ifinfo
+@node Configuring a System Determining Memory Requirements, Configuring a System Sizing the RTEMS RAM Workspace, Configuring a System Multiprocessor Communications Interface Table, Configuring a System
+@end ifinfo
+@section Determining Memory Requirements
+
+Since memory is a critical resource in many real-time
+embedded systems, RTEMS was specifically designed to allow
+unused managers to be excluded from the run-time environment.
+This allows the application designer the flexibility to tailor
+RTEMS to most efficiently meet system requirements while still
+satisfying even the most stringent memory constraints. As
+result, the size of the RTEMS executive is application
+dependent. A Memory Requirements worksheet is provided in the C
+Applications Supplement document for a specific target
+processor. This worksheet can be used to calculate the memory
+requirements of a custom RTEMS run-time environment. To insure
+that enough memory is allocated for future versions of RTEMS,
+the application designer should round these memory requirements
+up. The following managers may be optionally excluded:
+
+@itemize @bullet
+@item signal
+@item region
+@item dual ported memory
+@item event
+@item multiprocessing
+@item partition
+@item timer
+@item semaphore
+@item message
+@item rate monotonic
+@end itemize
+
+RTEMS based applications must somehow provide memory
+for RTEMS' code and data space. Although RTEMS' data space must
+be in RAM, its code space can be located in either ROM or RAM.
+In addition, the user must allocate RAM for the RTEMS RAM
+Workspace. The size of this area is application dependent and
+can be calculated using the formula provided in the Memory
+Requirements chapter of the C Applications Supplement document
+for a specific target processor.
+
+All RTEMS data variables and routine names used by
+RTEMS begin with the underscore ( _ ) character followed by an
+upper-case letter. If RTEMS is linked with an application, then
+the application code should NOT contain any symbols which begin
+with the underscore character and followed by an upper-case
+letter to avoid any naming conflicts. All RTEMS directive names
+should be treated as reserved words.
+
+@ifinfo
+@node Configuring a System Sizing the RTEMS RAM Workspace, Multiprocessing Manager, Configuring a System Determining Memory Requirements, Configuring a System
+@end ifinfo
+@section Sizing the RTEMS RAM Workspace
+
+The RTEMS RAM Workspace is a user-specified block of
+memory reserved for use by RTEMS. The application should NOT
+modify this memory. This area consists primarily of the RTEMS
+data structures whose exact size depends upon the values
+specified in the Configuration Table. In addition, task stacks
+and floating point context areas are dynamically allocated from
+the RTEMS RAM Workspace.
+
+The starting address of the RTEMS RAM Workspace must
+be aligned on a four-byte boundary. Failure to properly align
+the workspace area will result in the fatal_error_occurred
+directive being invoked with the INVALID_ADDRESS error code.
+
+A worksheet is provided in the Memory Requirements
+chapter of the C Applications Supplement document for a specific
+target processor to assist the user in calculating the minimum
+size of the RTEMS RAM Workspace for each application. The value
+calculated with this worksheet is the minimum value that should
+be specified as the work_space_size parameter of the
+Configuration Table. The user is cautioned that future versions
+of RTEMS may not have the same memory requirements per object.
+Although the value calculated is sufficient for a particular
+target processor and release of RTEMS, memory usage is subject
+to change across versions and target processors. The user is
+advised to allocate somewhat more memory than the worksheet
+recommends to insure compatibility with future releases for a
+specific target processor and other target processors. To avoid
+problems, the user should recalculate the memory requirements
+each time one of the following events occurs:
+
+@itemize @bullet
+@item a configuration parameter is modified,
+@item task or interrupt stack requirements change,
+@item task floating point attribute is altered,
+@item RTEMS is upgraded, or
+@item the target processor is changed.
+@end itemize
+
+Failure to provide enough space in the RTEMS RAM
+Workspace will result in the fatal_error_occurred directive
+being invoked with the appropriate error code.
diff --git a/doc/user/dirstat.texi b/doc/user/dirstat.texi
new file mode 100644
index 0000000000..b703ec5043
--- /dev/null
+++ b/doc/user/dirstat.texi
@@ -0,0 +1,40 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Directive Status Codes, Example Application, MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Top
+@end ifinfo
+@chapter Directive Status Codes
+@table @b
+@item @b{SUCCESSFUL} - successful completion
+@item @b{TASK_EXITTED} - returned from a task
+@item @b{MP_NOT_CONFIGURED} - multiprocessing not configured
+@item @b{INVALID_NAME} - invalid object name
+@item @b{INVALID_ID} - invalid object id
+@item @b{TOO_MANY} - too many
+@item @b{TIMEOUT} - timed out waiting
+@item @b{OBJECT_WAS_DELETED} - object was deleted while waiting
+@item @b{INVALID_SIZE} - invalid specified size
+@item @b{INVALID_ADDRESS} - invalid address specified
+@item @b{INVALID_NUMBER} - number was invalid
+@item @b{NOT_DEFINED} - item not initialized
+@item @b{RESOURCE_IN_USE} - resources outstanding
+@item @b{UNSATISFIED} - request not satisfied
+@item @b{INCORRECT_STATE} - task is in wrong state
+@item @b{ALREADY_SUSPENDED} - task already in state
+@item @b{ILLEGAL_ON_SELF} - illegal for calling task
+@item @b{ILLEGAL_ON_REMOTE_OBJECT} - illegal for remote object
+@item @b{CALLED_FROM_ISR} - invalid environment
+@item @b{INVALID_PRIORITY} - invalid task priority
+@item @b{INVALID_CLOCK} - invalid time buffer
+@item @b{INVALID_NODE} - invalid node id
+@item @b{NOT_CONFIGURED} - directive not configured
+@item @b{NOT_OWNER_OF_RESOURCE} - not owner of resource
+@item @b{NOT_IMPLEMENTED} - directive not implemented
+@item @b{INTERNAL_ERROR} - RTEMS inconsistency detected
+@item @b{NO_MEMORY} - could not get enough memory
+@end table
+
diff --git a/doc/user/dpmem.t b/doc/user/dpmem.t
new file mode 100644
index 0000000000..9432323b02
--- /dev/null
+++ b/doc/user/dpmem.t
@@ -0,0 +1,324 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Dual-Ported Memory Manager, Dual-Ported Memory Manager Introduction, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Top
+@end ifinfo
+@chapter Dual-Ported Memory Manager
+@ifinfo
+@menu
+* Dual-Ported Memory Manager Introduction::
+* Dual-Ported Memory Manager Background::
+* Dual-Ported Memory Manager Operations::
+* Dual-Ported Memory Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager, Dual-Ported Memory Manager
+@end ifinfo
+@section Introduction
+
+The dual-ported memory manager provides a mechanism
+for converting addresses between internal and external
+representations for multiple dual-ported memory areas (DPMA).
+The directives provided by the dual-ported memory manager are:
+
+@itemize @bullet
+@item @code{port_create} - Create a port
+@item @code{port_ident} - Get ID of a port
+@item @code{port_delete} - Delete a port
+@item @code{port_external_to_internal} - Convert external to internal address
+@item @code{port_internal_to_external} - Convert internal to external address
+@end itemize
+
+@ifinfo
+@node Dual-Ported Memory Manager Background, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager
+@end ifinfo
+@section Background
+
+A dual-ported memory area (DPMA) is an contiguous
+block of RAM owned by a particular processor but which can be
+accessed by other processors in the system. The owner accesses
+the memory using internal addresses, while other processors must
+use external addresses. RTEMS defines a port as a particular
+mapping of internal and external addresses.
+
+There are two system configurations in which
+dual-ported memory is commonly found. The first is
+tightly-coupled multiprocessor computer systems where the
+dual-ported memory is shared between all nodes and is used for
+inter-node communication. The second configuration is computer
+systems with intelligent peripheral controllers. These
+controllers typically utilize the DPMA for high-performance data
+transfers.
+
+@ifinfo
+@node Dual-Ported Memory Manager Operations, Creating a Port, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Port::
+* Obtaining Port IDs::
+* Converting an Address::
+* Deleting a DPMA Port::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Operations
+@end ifinfo
+@subsection Creating a Port
+
+The port_create directive creates a port into a DPMA
+with the user-defined name. The user specifies the association
+between internal and external representations for the port being
+created. RTEMS allocates a Dual-Ported Memory Control Block
+(DPCB) from the DPCB free list to maintain the newly created
+DPMA. RTEMS also generates a unique dual-ported memory port ID
+which is returned to the calling task. RTEMS does not
+initialize the dual-ported memory area or access any memory
+within it.
+
+@ifinfo
+@node Obtaining Port IDs, Converting an Address, Creating a Port, Dual-Ported Memory Manager Operations
+@end ifinfo
+@subsection Obtaining Port IDs
+
+When a port is created, RTEMS generates a unique port
+ID and assigns it to the created port until it is deleted. The
+port ID may be obtained by either of two methods. First, as the
+result of an invocation of the port_create directive, the task
+ID is stored in a user provided location. Second, the port ID
+may be obtained later using the port_ident directive. The port
+ID is used by other dual-ported memory manager directives to
+access this port.
+
+@ifinfo
+@node Converting an Address, Deleting a DPMA Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations
+@end ifinfo
+@subsection Converting an Address
+
+The port_external_to_internal directive is used to
+convert an address from external to internal representation for
+the specified port. The port_internal_to_external directive is
+used to convert an address from internal to external
+representation for the specified port. If an attempt is made to
+convert an address which lies outside the specified DPMA, then
+the address to be converted will be returned.
+
+@ifinfo
+@node Deleting a DPMA Port, Dual-Ported Memory Manager Directives, Converting an Address, Dual-Ported Memory Manager Operations
+@end ifinfo
+@subsection Deleting a DPMA Port
+
+A port can be removed from the system and returned to
+RTEMS with the port_delete directive. When a port is deleted,
+its control block is returned to the DPCB free list.
+
+@ifinfo
+@node Dual-Ported Memory Manager Directives, PORT_CREATE - Create a port, Deleting a DPMA Port, Dual-Ported Memory Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* PORT_CREATE - Create a port::
+* PORT_IDENT - Get ID of a port::
+* PORT_DELETE - Delete a port::
+* PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address::
+* PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address::
+@end menu
+@end ifinfo
+
+This section details the dual-ported memory manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node PORT_CREATE - Create a port, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives, Dual-Ported Memory Manager Directives
+@end ifinfo
+@subsection PORT_CREATE - Create a port
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_port_create(
+ rtems_name name,
+ void *internal_start,
+ void *external_start,
+ rtems_unsigned32 length,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - port created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{INVALID_ADDRESS} - address not on four byte boundary@*
+@code{TOO_MANY} - too many DP memory areas created
+
+@subheading DESCRIPTION:
+
+This directive creates a port which resides on the
+local node for the specified DPMA. The assigned port id is
+returned in id. This port id is used as an argument to other
+dual-ported memory manager directives to convert addresses
+within this DPMA.
+
+For control and maintenance of the port, RTEMS
+allocates and initializes an DPCB from the DPCB free pool. Thus
+memory from the dual-ported memory area is not used to store the
+DPCB.
+
+@subheading NOTES:
+
+The internal_address and external_address parameters
+must be on a four byte boundary.
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node PORT_IDENT - Get ID of a port, PORT_DELETE - Delete a port, PORT_CREATE - Create a port, Dual-Ported Memory Manager Directives
+@end ifinfo
+@subsection PORT_IDENT - Get ID of a port
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_port_ident(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - port identified successfully@*
+@code{INVALID_NAME} - port name not found
+
+@subheading DESCRIPTION:
+
+This directive obtains the port id associated with
+the specified name to be acquired. If the port name is not
+unique, then the port id will match one of the DPMAs with that
+name. However, this port id is not guaranteed to correspond to
+the desired DPMA. The port id is used to access this DPMA in
+other dual-ported memory area related directives.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+@page
+@ifinfo
+@node PORT_DELETE - Delete a port, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives
+@end ifinfo
+@subsection PORT_DELETE - Delete a port
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_port_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - port deleted successfully@*
+@code{INVALID_ID} - invalid port id
+
+@subheading DESCRIPTION:
+
+This directive deletes the dual-ported memory area
+specified by id. The DPCB for the deleted dual-ported memory
+area is reclaimed by RTEMS.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The calling task does not have to be the task that
+created the port. Any local task that knows the port id can
+delete the port.
+
+@page
+@ifinfo
+@node PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, PORT_DELETE - Delete a port, Dual-Ported Memory Manager Directives
+@end ifinfo
+@subsection PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_port_external_to_internal(
+ rtems_id id,
+ void *external,
+ void **internal
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - always successful
+
+@subheading DESCRIPTION:
+
+This directive converts a dual-ported memory address
+from external to internal representation for the specified port.
+If the given external address is invalid for the specified
+port, then the internal address is set to the given external
+address.
+
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, I/O Manager, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, Dual-Ported Memory Manager Directives
+@end ifinfo
+@subsection PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_port_internal_to_external(
+ rtems_id id,
+ void *internal,
+ void **external
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - always successful
+
+@subheading DESCRIPTION:
+
+This directive converts a dual-ported memory address
+from internal to external representation so that it can be
+passed to owner of the DPMA represented by the specified port.
+If the given internal address is an invalid dual-ported address,
+then the external address is set to the given internal address.
+
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the calling task to be
+preempted.
+
+
+
+
+
diff --git a/doc/user/event.t b/doc/user/event.t
new file mode 100644
index 0000000000..0ec198a5c0
--- /dev/null
+++ b/doc/user/event.t
@@ -0,0 +1,351 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Event Manager, Event Manager Introduction, MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, Top
+@end ifinfo
+@chapter Event Manager
+@ifinfo
+@menu
+* Event Manager Introduction::
+* Event Manager Background::
+* Event Manager Operations::
+* Event Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Event Manager Introduction, Event Manager Background, Event Manager, Event Manager
+@end ifinfo
+@section Introduction
+
+The event manager provides a high performance method
+of intertask communication and synchronization. The directives
+provided by the event manager are:
+
+@itemize @bullet
+@item @code{event_send} - Send event set to a task
+@item @code{event_receive} - Receive event condition
+@end itemize
+
+@ifinfo
+@node Event Manager Background, Event Sets, Event Manager Introduction, Event Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Event Sets::
+* Building an Event Set or Condition::
+* Building an EVENT_RECEIVE Option Set::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Event Sets, Building an Event Set or Condition, Event Manager Background, Event Manager Background
+@end ifinfo
+@subsection Event Sets
+
+An event flag is used by a task (or ISR) to inform
+another task of the occurrence of a significant situation.
+Thirty-two event flags are associated with each task. A
+collection of one or more event flags is referred to as an event
+set. The application developer should remember the following
+key characteristics of event operations when utilizing the event
+manager:
+
+@itemize @bullet
+@item Events provide a simple synchronization facility.
+
+@item Events are aimed at tasks.
+
+@item Tasks can wait on more than one event simultaneously.
+
+@item Events are independent of one another.
+
+@item Events do not hold or transport data.
+
+@item Events are not queued. In other words, if an event is
+sent more than once before being received, the second and
+subsequent send operations have no effect.
+@end itemize
+
+An event set is posted when it is directed (or sent)
+to a task. A pending event is an event that has been posted but
+not received. An event condition is used to specify the events
+which the task desires to receive and the algorithm which will
+be used to determine when the request is satisfied. An event
+condition is satisfied based upon one of two algorithms which
+are selected by the user. The EVENT_ANY algorithm states that
+an event condition is satisfied when at least a single requested
+event is posted. The EVENT_ALL algorithm states that an event
+condition is satisfied when every requested event is posted.
+
+@ifinfo
+@node Building an Event Set or Condition, Building an EVENT_RECEIVE Option Set, Event Sets, Event Manager Background
+@end ifinfo
+@subsection Building an Event Set or Condition
+
+An event set or condition is built by a bitwise OR of
+the desired events. The set of valid events is EVENT_0 through
+EVENT_31. If an event is not explicitly specified in the set or
+condition, then it is not present. Events are specifically
+designed to be mutually exclusive, therefore bitwise OR and
+addition operations are equivalent as long as each event appears
+exactly once in the event set list.
+
+For example, when sending the event set consisting of
+EVENT_6, EVENT_15, and EVENT_31, the event parameter to the
+event_send directive should be EVENT_6 | EVENT_15 | EVENT_31.
+
+@ifinfo
+@node Building an EVENT_RECEIVE Option Set, Event Manager Operations, Building an Event Set or Condition, Event Manager Background
+@end ifinfo
+@subsection Building an EVENT_RECEIVE Option Set
+
+In general, an option is built by a bitwise OR of the
+desired option components. The set of valid options for the
+event_receive directive are listed in the following table:
+
+@itemize @bullet
+@item WAIT - task will wait for event (default)
+@item NO_WAIT - task should not wait
+@item EVENT_ALL - return after all events (default)
+@item EVENT_ANY - return after any events
+@end itemize
+
+Option values are specifically designed to be
+mutually exclusive, therefore bitwise OR and addition operations
+are equivalent as long as each option appears exactly once in
+the component list. An option listed as a default is not
+required to appear in the option list, although it is a good
+programming practice to specify default options. If all
+defaults are desired, the option DEFAULT_OPTIONS should be
+specified on this call.
+
+This example demonstrates the option parameter needed
+to poll for all events in a particular event condition to
+arrive. The option parameter passed to the event_receive
+directive should be either EVENT_ALL | NO_WAIT or NO_WAIT. The
+option parameter can be set to NO_WAIT because EVENT_ALL is the
+default condition for event_receive.
+
+@ifinfo
+@node Event Manager Operations, Sending an Event Set, Building an EVENT_RECEIVE Option Set, Event Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Sending an Event Set::
+* Receiving an Event Set::
+* Determining the Pending Event Set::
+* Receiving all Pending Events::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Sending an Event Set, Receiving an Event Set, Event Manager Operations, Event Manager Operations
+@end ifinfo
+@subsection Sending an Event Set
+
+The event_send directive allows a task (or an ISR) to
+direct an event set to a target task. Based upon the state of
+the target task, one of the following situations applies:
+
+@itemize @bullet
+@item Target Task is Blocked Waiting for Events
+
+@itemize -
+
+@item If the waiting task's input event condition is
+satisfied, then the task is made ready for execution.
+
+@item If the waiting task's input event condition is not
+satisfied, then the event set is posted but left pending and the
+task remains blocked.
+
+@end itemize
+
+@item Target Task is Not Waiting for Events
+
+@itemize -
+@item The event set is posted and left pending.
+@end itemize
+
+@end itemize
+
+@ifinfo
+@node Receiving an Event Set, Determining the Pending Event Set, Sending an Event Set, Event Manager Operations
+@end ifinfo
+@subsection Receiving an Event Set
+
+The event_receive directive is used by tasks to
+accept a specific input event condition. The task also
+specifies whether the request is satisfied when all requested
+events are available or any single requested event is available.
+If the requested event condition is satisfied by pending
+events, then a successful return code and the satisfying event
+set are returned immediately. If the condition is not
+satisfied, then one of the following situations applies:
+
+@itemize @bullet
+@item By default, the calling task will wait forever for the
+event condition to be satisfied.
+
+@item Specifying the NO_WAIT option forces an immediate return
+with an error status code.
+
+@item Specifying a timeout limits the period the task will
+wait before returning with an error status code.
+@end itemize
+
+@ifinfo
+@node Determining the Pending Event Set, Receiving all Pending Events, Receiving an Event Set, Event Manager Operations
+@end ifinfo
+@subsection Determining the Pending Event Set
+
+A task can determine the pending event set by calling
+the event_receive directive with a value of PENDING_EVENTS for
+the input event condition. The pending events are returned to
+the calling task but the event set is left unaltered.
+
+@ifinfo
+@node Receiving all Pending Events, Event Manager Directives, Determining the Pending Event Set, Event Manager Operations
+@end ifinfo
+@subsection Receiving all Pending Events
+
+A task can receive all of the currently pending
+events by calling the event_receive directive with a value of
+ALL_EVENTS for the input event condition and NO_WAIT | EVENT_ANY
+for the option set. The pending events are returned to the
+calling task and the event set is cleared. If no events are
+pending then the UNSATISFIED status code will be returned.
+
+@ifinfo
+@node Event Manager Directives, EVENT_SEND - Send event set to a task, Receiving all Pending Events, Event Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* EVENT_SEND - Send event set to a task::
+* EVENT_RECEIVE - Receive event condition::
+@end menu
+@end ifinfo
+
+This section details the event manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@ifinfo
+@node EVENT_SEND - Send event set to a task, EVENT_RECEIVE - Receive event condition, Event Manager Directives, Event Manager Directives
+@end ifinfo
+@subsection EVENT_SEND - Send event set to a task
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_event_send (
+ rtems_id id,
+ rtems_event_set event_in
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - event set sent successfully@*
+@code{INVALID_ID} - invalid task id
+
+@subheading DESCRIPTION:
+
+This directive sends an event set, event_in, to the
+task specified by id. If a blocked task's input event condition
+is satisfied by this directive, then it will be made ready. If
+its input event condition is not satisfied, then the events
+satisfied are updated and the events not satisfied are left
+pending. If the task specified by id is not blocked waiting for
+events, then the events sent are left pending.
+
+@subheading NOTES:
+
+Specifying SELF for id results in the event set being
+sent to the calling task.
+
+Identical events sent to a task are not queued. In
+other words, the second, and subsequent, posting of an event to
+a task before it can perform an event_receive has no effect.
+
+The calling task will be preempted if it has
+preemption enabled and a higher priority task is unblocked as
+the result of this directive.
+
+Sending an event set to a global task which does not
+reside on the local node will generate a request telling the
+remote node to send the event set to the appropriate task.
+
+@page
+@ifinfo
+@node EVENT_RECEIVE - Receive event condition, Signal Manager, EVENT_SEND - Send event set to a task, Event Manager Directives
+@end ifinfo
+@subsection EVENT_RECEIVE - Receive event condition
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_event_receive (
+ rtems_event_set event_in,
+ rtems_option option_set,
+ rtems_interval ticks,
+ rtems_event_set *event_out
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - event received successfully@*
+@code{UNSATISFIED} - input event not satisfied (NO_WAIT)@*
+@code{TIMEOUT} - timed out waiting for event
+
+@subheading DESCRIPTION:
+
+This directive attempts to receive the event
+condition specified in event_in. If event_in is set to
+PENDING_EVENTS, then the current pending events are returned in
+event_out and left pending. The WAIT and NO_WAIT options in the
+option_set parameter are used to specify whether or not the task
+is willing to wait for the event condition to be satisfied.
+EVENT_ANY and EVENT_ALL are used in the option_set parameter are
+used to specify whether a single event or the complete event set
+is necessary to satisfy the event condition. The event_out
+parameter is returned to the calling task with the value that
+corresponds to the events in event_in that were satisfied.
+
+If pending events satisfy the event condition, then
+event_out is set to the satisfied events and the pending events
+in the event condition are cleared. If the event condition is
+not satisfied and NO_WAIT is specified, then event_out is set to
+the currently satisfied events. If the calling task chooses to
+wait, then it will block waiting for the event condition.
+
+If the calling task must wait for the event condition
+to be satisfied, then the timeout parameter is used to specify
+the maximum interval to wait. If it is set to NO_TIMEOUT, then
+the calling task will wait forever.
+
+@subheading NOTES:
+
+This directive only affects the events specified in
+event_in. Any pending events that do not correspond to any of
+the events specified in event_in will be left pending.
+
+The following event receive option constants are defined by
+RTEMS:
+
+@itemize @bullet
+@item WAIT task will wait for event (default)
+@item NO_WAIT task should not wait
+@item EVENT_ALL return after all events (default)
+@item EVENT_ANY return after any events
+@end itemize
+
diff --git a/doc/user/example.texi b/doc/user/example.texi
new file mode 100644
index 0000000000..545cf8e8f4
--- /dev/null
+++ b/doc/user/example.texi
@@ -0,0 +1,103 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Example Application, Glossary, Directive Status Codes, Top
+@end ifinfo
+@chapter Example Application
+
+@example
+/* example.c
+ *
+ * This file contains an example of a simple RTEMS
+ * application. It contains a Configuration Table, a
+ * user initialization task, and a simple task.
+ *
+ * This example assumes that a board support package exists
+ * and invokes the initialize_executive() directive.
+ */
+
+#include "rtems.h"
+
+rtems_task init_task();
+
+#define INIT_NAME build_name( 'A', 'B', 'C', ' ' ' )
+
+rtems_initialization_tasks_table init_task = @{
+ @{ INIT_NAME, /* init task name "ABC" */
+ 1024, /* init task stack size */
+ 1, /* init task priority */
+ DEFAULT_ATTRIBUTES, /* init task attributes */
+ init_task, /* init task entry point */
+ TIMESLICE, /* init task initial mode */
+ 0 /* init task argument */
+ @}
+@};
+
+rtems_configuration_table User_Configuration_Table = @{
+ NULL, /* filled in by the BSP */
+ 65536, /* executive RAM size */
+ 2, /* maximum tasks */
+ 0, /* maximum timers */
+ 0, /* maximum semaphores */
+ 0, /* maximum message queues */
+ 0, /* maximum messages */
+ 0, /* maximum partitions */
+ 0, /* maximum regions */
+ 0, /* maximum ports */
+ 0, /* maximum periods */
+ 0, /* maximum extensions */
+ RTEMS_MILLISECONDS_TO_MICROSECONDS(10), /* number of ms in a tick */
+ 1, /* num of ticks in a timeslice */
+ 1, /* number of user init tasks */
+ init_task_tbl, /* user init task(s) table */
+ 0, /* number of device drivers */
+ NULL, /* ptr to driver address table */
+ NULL, /* ptr to extension table */
+ NULL /* ptr to MP config table */
+@};
+
+task user_application(
+ rtems_task_argument ignored
+);
+
+#define USER_APP_NAME 1 /* any 32-bit name; unique helps */
+
+rtems_task init_task(
+ rtems_task_argument ignored
+)
+@{
+ rtems_id tid;
+
+ /* example assumes SUCCESSFUL return value */
+
+ (void) rtems_task_create( USER_APP_NAME, 1, 1024,
+ RTEMS_NO_PREEMPT, RTEMS_FLOATING_POINT, &tid );
+ (void) rtems_task_start( tid, user_application, 0 );
+ (void) rtems_task_delete( SELF );
+@}
+
+
+
+rtems_task user_application()
+
+@{
+ /* application specific initialization goes here */
+
+ while ( 1 ) @{ /* infinite loop */
+
+ /* APPLICATION CODE GOES HERE
+ *
+ * This code will typically include at least one
+ * directive which causes the calling task to
+ * give up the processor.
+ */
+ @}
+@}
+@end example
+
+
+
diff --git a/doc/user/fatal.t b/doc/user/fatal.t
new file mode 100644
index 0000000000..4f15684195
--- /dev/null
+++ b/doc/user/fatal.t
@@ -0,0 +1,180 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Fatal Error Manager, Fatal Error Manager Introduction, IO_CONTROL - Special device services, Top
+@end ifinfo
+@chapter Fatal Error Manager
+@ifinfo
+@menu
+* Fatal Error Manager Introduction::
+* Fatal Error Manager Background::
+* Fatal Error Manager Operations::
+* Fatal Error Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Fatal Error Manager Introduction, Fatal Error Manager Background, Fatal Error Manager, Fatal Error Manager
+@end ifinfo
+@section Introduction
+
+The fatal error manager processes all fatal or
+irrecoverable errors. The directive provided by the fatal error
+manager is:
+
+@itemize @bullet
+@item @code{fatal_error_occurred} - Invoke the fatal error handler
+@end itemize
+
+
+
+@ifinfo
+@node Fatal Error Manager Background, Fatal Error Manager Operations, Fatal Error Manager Introduction, Fatal Error Manager
+@end ifinfo
+@section Background
+
+The fatal error manager is called upon detection of
+an irrecoverable error condition by either RTEMS or the
+application software. Fatal errors can be detected from three
+sources:
+
+@itemize @bullet
+@item the executive (RTEMS)
+@item user system code
+@item user application code
+@end itemize
+
+RTEMS automatically invokes the fatal error manager
+upon detection of an error it considers to be fatal. Similarly,
+the user should invoke the fatal error manager upon detection of
+a fatal error.
+
+Each status or dynamic user extension set may include
+a fatal error handler. The fatal error handler in the static
+extension set can be used to provide access to debuggers and
+monitors which may be present on the target hardware. If any
+user-supplied fatal error handlers are installed, the fatal
+error manager will invoke them. If no user handlers are
+configured or if all the user handler return control to the
+fatal error manager, then the RTEMS default fatal error handler
+is invoked. If the default fatal error handler is invoked, then
+the system state is marked as failed.
+
+Although the precise behavior of the default fatal
+error handler is processor specific, in general, it will disable
+all maskable interrupts, place the error code in a known
+processor dependent place (generally either on the stack or in a
+register), and halt the processor. The precise actions of the
+RTEMS fatal error are discussed in the Default Fatal Error
+Processing chapter of the C Applications Supplement document for
+a specific target processor.
+
+@ifinfo
+@node Fatal Error Manager Operations, Announcing a Fatal Error, Fatal Error Manager Background, Fatal Error Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Announcing a Fatal Error::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Announcing a Fatal Error, Fatal Error Manager Directives, Fatal Error Manager Operations, Fatal Error Manager Operations
+@end ifinfo
+@subsection Announcing a Fatal Error
+
+The fatal_error_occurred directive is invoked when a
+fatal error is detected. Before invoking any user-supplied
+fatal error handlers or the RTEMS fatal error handler, the
+fatal_error_occurred directive stores useful information in the
+variable _Internal_errors_What_happened. This structure
+contains three pieces of information:
+
+@itemize @bullet
+@item the source of the error (API or executive core),
+
+@item whether the error was generated internally by the
+executive, and a
+
+@item a numeric code to indicate the error type.
+@end itemize
+
+The error type indicator is dependent on the source
+of the error and whether or not the error was internally
+generated by the executive.
+
+The fatal_error_directive directive is responsible
+for invoking an optional user-supplied fatal error handler
+and/or the RTEMS fatal error handler. All fatal error handlers
+are passed an error code to describe the error detected.
+
+Occasionally, an application requires more
+sophisticated fatal error processing such as passing control to
+a debugger. For these cases, a user-supplied fatal error
+handler can be specified in the RTEMS configuration table. The
+User Extension Table field fatal contains the address of the
+fatal error handler to be executed when the fatal_error_occurred
+directive is called. If the field is set to NULL or if the
+configured fatal error handler returns to the executive, then
+the default handler provided by RTEMS is executed. This default
+handler will halt execution on the processor where the error
+occurred.
+
+@ifinfo
+@node Fatal Error Manager Directives, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Announcing a Fatal Error, Fatal Error Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* FATAL_ERROR_OCCURRED - Invoke the fatal error handler::
+@end menu
+@end ifinfo
+
+This section details the fatal error manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Scheduling Concepts, Fatal Error Manager Directives, Fatal Error Manager Directives
+@end ifinfo
+@subsection FATAL_ERROR_OCCURRED - Invoke the fatal error handler
+
+@subheading CALLING SEQUENCE:
+
+@example
+void volatile rtems_fatal_error_occurred(
+ rtems_unsigned32 the_error
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive processes fatal errors. If the FATAL
+error extension is defined in the configuration table, then the
+user-defined error extension is called. If configured and the
+provided FATAL error extension returns, then the RTEMS default
+error handler is invoked. This directive can be invoked by
+RTEMS or by the user's application code including initialization
+tasks, other tasks, and ISRs.
+
+@subheading NOTES:
+
+This directive supports local operations only.
+
+Unless the user-defined error extension takes special
+actions such as restarting the calling task, this directive WILL
+NOT RETURN to the caller.
+
+The user-defined extension for this directive may
+wish to initiate a global shutdown.
diff --git a/doc/user/glossary.texi b/doc/user/glossary.texi
new file mode 100644
index 0000000000..58b57061f0
--- /dev/null
+++ b/doc/user/glossary.texi
@@ -0,0 +1,772 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Glossary, Command and Variable Index, Example Application, Top
+@end ifinfo
+@chapter Glossary
+
+@table @b
+@item active
+A term used to describe an object
+which has been created by an application.
+
+@item aperiodic task
+A task which must execute only at
+irregular intervals and has only a soft deadline.
+
+@item application
+In this document, software which makes
+use of RTEMS.
+
+@item ASR
+see Asynchronous Signal Routine.
+
+@item asynchronous
+Not related in order or timing to
+other occurrences in the system.
+
+@item Asynchronous Signal Routine
+Similar to a hardware
+interrupt except that it is associated with a task and is run in
+the context of a task. The directives provided by the signal
+manager are used to service signals.
+
+@item awakened
+A term used to describe a task that has
+been unblocked and may be scheduled to the CPU.
+
+@item big endian
+A data representation scheme in which
+the bytes composing a numeric value are arranged such that the
+most significant byte is at the lowest address.
+
+@item bit-mapped
+A data encoding scheme in which each bit
+in a variable is used to represent something different. This
+makes for compact data representation.
+
+@item block
+A physically contiguous area of memory.
+
+@item blocked
+The task state entered by a task which has
+been previously started and cannot continue execution until the
+reason for waiting has been satisfied.
+
+@item broadcast
+To simultaneously send a message to a
+logical set of destinations.
+
+@item BSP
+see Board Support Package.
+
+@item Board Support Package
+A collection of device
+initialization and control routines specific to a particular
+type of board or collection of boards.
+
+@item buffer
+A fixed length block of memory allocated
+from a partition.
+
+@item calling convention
+The processor and compiler
+dependent rules which define the mechanism used to invoke
+subroutines in a high-level language. These rules define the
+passing of arguments, the call and return mechanism, and the
+register set which must be preserved.
+
+@item Central Processing Unit
+This term is equivalent to
+the terms processor and microprocessor.
+
+@item chain
+A data structure which allows for efficient
+dynamic addition and removal of elements. It differs from an
+array in that it is not limited to a predefined size.
+
+@item coalesce
+The process of merging adjacent holes into
+a single larger hole. Sometimes this process is referred to as
+garbage collection.
+
+@item Configuration Table
+A table which contains
+information used to tailor RTEMS for a particular application.
+
+@item context
+All of the processor registers and
+operating system data structures associated with a task.
+
+@item context switch
+Alternate term for task switch.
+Taking control of the processor from one task and transferring
+it to another task.
+
+@item control block
+A data structure used by the
+executive to define and control an object.
+
+@item core
+When used in this manual, this term refers to
+the internal executive utility functions. In the interest of
+application portability, the core of the executive should not be
+used directly by applications.
+
+@item CPU
+An acronym for Central Processing Unit.
+
+@item critical section
+A section of code which must be
+executed indivisibly.
+
+@item CRT
+An acronym for Cathode Ray Tube. Normally used
+in reference to the man-machine interface.
+
+@item deadline
+A fixed time limit by which a task must
+have completed a set of actions. Beyond this point, the results
+are of reduced value and may even be considered useless or
+harmful.
+
+@item device
+A peripheral used by the application that
+requires special operation software. See also device driver.
+
+@item device driver
+Control software for special
+peripheral devices used by the application.
+
+@item directives
+RTEMS' provided routines that provide
+support mechanisms for real-time applications.
+
+@item dispatch
+The act of loading a task's context onto
+the CPU and transferring control of the CPU to that task.
+
+@item dormant
+The state entered by a task after it is
+created and before it has been started.
+
+@item Device Driver Table
+A table which contains the
+entry points for each of the configured device drivers.
+
+@item dual-ported
+A term used to describe memory which
+can be accessed at two different addresses.
+
+@item embedded
+An application that is delivered as a
+hidden part of a larger system. For example, the software in a
+fuel-injection control system is an embedded application found
+in many late-model automobiles.
+
+@item envelope
+A buffer provided by the MPCI layer to
+RTEMS which is used to pass messages between nodes in a
+multiprocessor system. It typically contains routing
+information needed by the MPCI. The contents of an envelope are
+referred to as a packet.
+
+@item entry point
+The address at which a function or task
+begins to execute. In C, the entry point of a function is the
+function's name.
+
+@item events
+A method for task communication and
+synchronization. The directives provided by the event manager
+are used to service events.
+
+@item exception
+A synonym for interrupt.
+
+@item executing
+The task state entered by a task after it
+has been given control of the CPU.
+
+@item executive
+In this document, this term is used to
+referred to RTEMS. Commonly, an executive is a small real-time
+operating system used in embedded systems.
+
+@item exported
+An object known by all nodes in a
+multiprocessor system. An object created with the GLOBAL
+attribute will be exported.
+
+@item external address
+The address used to access
+dual-ported memory by all the nodes in a system which do not own
+the memory.
+
+@item FIFO
+An acronym for First In First Out.
+
+@item First In First Out
+A discipline for manipulating
+entries in a data structure.
+
+@item floating point coprocessor
+A component used in
+computer systems to enhance performance in mathematically
+intensive situations. It is typically viewed as a logical
+extension of the primary processor.
+
+@item freed
+A resource that has been released by the
+application to RTEMS.
+
+@item global
+An object that has been created with the
+GLOBAL attribute and exported to all nodes in a multiprocessor
+system.
+
+@item handler
+The equivalent of a manager, except that it
+is internal to RTEMS and forms part of the core. A handler is a
+collection of routines which provide a related set of functions.
+For example, there is a handler used by RTEMS to manage all
+objects.
+
+@item hard real-time system
+A real-time system in which a
+missed deadline causes the worked performed to have no value or
+to result in a catastrophic effect on the integrity of the
+system.
+
+@item heap
+A data structure used to dynamically allocate
+and deallocate variable sized blocks of memory.
+
+@item heterogeneous
+A multiprocessor computer system
+composed of dissimilar processors.
+
+@item homogeneous
+A multiprocessor computer system
+composed of a single type of processor.
+
+@item ID
+An RTEMS assigned identification tag used to
+access an active object.
+
+@item IDLE task
+A special low priority task which assumes
+control of the CPU when no other task is able to execute.
+
+@item interface
+A specification of the methodology used
+to connect multiple independent subsystems.
+
+@item internal address
+The address used to access
+dual-ported memory by the node which owns the memory.
+
+@item interrupt
+A hardware facility that causes the CPU
+to suspend execution, save its status, and transfer control to a
+specific location.
+
+@item interrupt level
+A mask used to by the CPU to
+determine which pending interrupts should be serviced. If a
+pending interrupt is below the current interrupt level, then the
+CPU does not recognize that interrupt.
+
+@item Interrupt Service Routine
+An ISR is invoked by the
+CPU to process a pending interrupt.
+
+@item I/O
+An acronym for Input/Output.
+
+@item ISR
+An acronym for Interrupt Service Routine.
+
+@item kernel
+In this document, this term is used as a
+synonym for executive.
+
+@item list
+A data structure which allows for dynamic
+addition and removal of entries. It is not statically limited
+to a particular size.
+
+@item little endian
+A data representation scheme in which
+the bytes composing a numeric value are arranged such that the
+least significant byte is at the lowest address.
+
+@item local
+An object which was created with the LOCAL
+attribute and is accessible only on the node it was created and
+resides upon. In a single processor configuration, all objects
+are local.
+
+@item local operation
+The manipulation of an object which
+resides on the same node as the calling task.
+
+@item logical address
+An address used by an application.
+In a system without memory management, logical addresses will
+equal physical addresses.
+
+@item loosely-coupled
+A multiprocessor configuration
+where shared memory is not used for communication.
+
+@item major number
+The index of a device driver in the
+Device Driver Table.
+
+@item manager
+A group of related RTEMS' directives which
+provide access and control over resources.
+
+@item memory pool
+Used interchangeably with heap.
+
+@item message
+A sixteen byte entity used to communicate
+between tasks. Messages are sent to message queues and stored
+in message buffers.
+
+@item message buffer
+A block of memory used to store
+messages.
+
+@item message queue
+An RTEMS object used to synchronize
+and communicate between tasks by transporting messages between
+sending and receiving tasks.
+
+@item Message Queue Control Block
+A data structure
+associated with each message queue used by RTEMS to manage that
+message queue.
+
+@item minor number
+A numeric value passed to a device
+driver, the exact usage of which is driver dependent.
+
+@item mode
+An entry in a task's control block that is
+used to determine if the task allows preemption, timeslicing,
+processing of signals, and the interrupt disable level used by
+the task.
+
+@item MPCI
+An acronym for Multiprocessor Communications
+Interface Layer.
+
+@item multiprocessing
+The simultaneous execution of two
+or more processes by a multiple processor computer system.
+
+@item multiprocessor
+A computer with multiple CPUs
+available for executing applications.
+
+@item Multiprocessor Communications Interface Layer
+A set
+of user-provided routines which enable the nodes in a
+multiprocessor system to communicate with one another.
+
+@item Multiprocessor Configuration Table
+The data
+structure defining the characteristics of the multiprocessor
+target system with which RTEMS will communicate.
+
+@item multitasking
+The alternation of execution amongst a
+group of processes on a single CPU. A scheduling algorithm is
+used to determine which process executes at which time.
+
+@item mutual exclusion
+A term used to describe the act of
+preventing other tasks from accessing a resource simultaneously.
+
+@item nested
+A term used to describe an ASR that occurs
+during another ASR or an ISR that occurs during another ISR.
+
+@item node
+A term used to reference a processor running
+RTEMS in a multiprocessor system.
+
+@item non-existent
+The state occupied by an uncreated or
+deleted task.
+
+@item numeric coprocessor
+A component used in computer
+systems to enhance performance in mathematically intensive
+situations. It is typically viewed as a logical extension of
+the primary processor.
+
+@item object
+In this document, this term is used to refer
+collectively to tasks, timers, message queues, partitions,
+regions, semaphores, ports, and rate monotonic periods. All
+RTEMS objects have IDs and user-assigned names.
+
+@item object-oriented
+A term used to describe systems
+with common mechanisms for utilizing a variety of entities.
+Object-oriented systems shield the application from
+implementation details.
+
+@item operating system
+The software which controls all
+the computer's resources and provides the base upon which
+application programs can be written.
+
+@item overhead
+The portion of the CPUs processing power
+consumed by the operating system.
+
+@item packet
+A buffer which contains the messages passed
+between nodes in a multiprocessor system. A packet is the
+contents of an envelope.
+
+@item partition
+An RTEMS object which is used to allocate
+and deallocate fixed size blocks of memory from an dynamically
+specified area of memory.
+
+@item Partition Control Block
+A data structure associated
+with each partition used by RTEMS to manage that partition.
+
+@item pending
+A term used to describe a task blocked
+waiting for an event, message, semaphore, or signal.
+
+@item periodic task
+A task which must execute at regular
+intervals and comply with a hard deadline.
+
+@item physical address
+The actual hardware address of a
+resource.
+
+@item poll
+A mechanism used to determine if an event has
+occurred by periodically checking for a particular status.
+Typical events include arrival of data, completion of an action,
+and errors.
+
+@item pool
+A collection from which resources are
+allocated.
+
+@item portability
+A term used to describe the ease with
+which software can be rehosted on another computer.
+
+@item posting
+The act of sending an event, message,
+semaphore, or signal to a task.
+
+@item preempt
+The act of forcing a task to relinquish the
+processor and dispatching to another task.
+
+@item priority
+A mechanism used to represent the relative
+importance of an element in a set of items. RTEMS uses priority
+to determine which task should execute.
+
+@item priority inheritance
+An algorithm that calls for
+the lower priority task holding a resource to have its priority
+increased to that of the highest priority task blocked waiting
+for that resource. This avoids the problem of priority
+inversion.
+
+@item priority inversion
+A form of indefinite
+postponement which occurs when a high priority tasks requests
+access to shared resource currently allocated to low priority
+task. The high priority task must block until the low priority
+task releases the resource.
+
+@item processor utilization
+The percentage of processor
+time used by a task or a set of tasks.
+
+@item proxy
+An RTEMS control structure used to represent,
+on a remote node, a task which must block as part of a remote
+operation.
+
+@item Proxy Control Block
+A data structure associated
+with each proxy used by RTEMS to manage that proxy.
+
+@item PTCB
+An acronym for Partition Control Block.
+
+@item PXCB
+An acronym for Proxy Control Block.
+
+@item quantum
+The application defined unit of time in
+which the processor is allocated.
+
+@item queue
+Alternate term for message queue.
+
+@item QCB
+An acronym for Message Queue Control Block.
+
+@item ready
+A task occupies this state when it is
+available to be given control of the CPU.
+
+@item real-time
+A term used to describe systems which are
+characterized by requiring deterministic response times to
+external stimuli. The external stimuli require that the
+response occur at a precise time or the response is incorrect.
+
+@item reentrant
+A term used to describe routines which do
+not modify themselves or global variables.
+
+@item region
+An RTEMS object which is used to allocate
+and deallocate variable size blocks of memory from a dynamically
+specified area of memory.
+
+@item Region Control Block
+A data structure associated
+with each region used by RTEMS to manage that region.
+
+@item registers
+Registers are locations physically
+located within a component, typically used for device control or
+general purpose storage.
+
+@item remote
+Any object that does not reside on the local
+node.
+
+@item remote operation
+The manipulation of an object
+which does not reside on the same node as the calling task.
+
+@item return code
+Also known as error code or return
+value.
+
+@item resource
+A hardware or software entity to which
+access must be controlled.
+
+@item resume
+Removing a task from the suspend state. If
+the task's state is ready following a call to the task_resume
+directive, then the task is available for scheduling.
+
+@item return code
+A value returned by RTEMS directives to
+indicate the completion status of the directive.
+
+@item RNCB
+An acronym for Region Control Block.
+
+@item round-robin
+A task scheduling discipline in which
+tasks of equal priority are executed in the order in which they
+are made ready.
+
+@item RS-232
+A standard for serial communications.
+
+@item running
+The state of a rate monotonic timer while
+it is being used to delineate a period. The timer exits this
+state by either expiring or being canceled.
+
+@item schedule
+The process of choosing which task should
+next enter the executing state.
+
+@item schedulable
+A set of tasks which can be guaranteed
+to meet their deadlines based upon a specific scheduling
+algorithm.
+
+@item segments
+Variable sized memory blocks allocated
+from a region.
+
+@item semaphore
+An RTEMS object which is used to
+synchronize tasks and provide mutually exclusive access to
+resources.
+
+@item Semaphore Control Block
+A data structure associated
+with each semaphore used by RTEMS to manage that semaphore.
+
+@item shared memory
+Memory which is accessible by
+multiple nodes in a multiprocessor system.
+
+@item signal
+An RTEMS provided mechanism to communicate
+asynchronously with a task. Upon reception of a signal, the ASR
+of the receiving task will be invoked.
+
+@item signal set
+A thirty-two bit entity which is used to
+represent a task's collection of pending signals and the signals
+sent to a task.
+
+@item SMCB
+An acronym for Semaphore Control Block.
+
+@item soft real-time system
+A real-time system in which a
+missed deadline does not compromise the integrity of the system.
+
+@item sporadic task
+A task which executes at irregular
+intervals and must comply with a hard deadline. A minimum
+period of time between successive iterations of the task can be
+guaranteed.
+
+@item stack
+A data structure that is managed using a Last
+In First Out (LIFO) discipline. Each task has a stack
+associated with it which is used to store return information
+and local variables.
+
+@item status code
+Also known as error code or return
+value.
+
+@item suspend
+A term used to describe a task that is not
+competing for the CPU because it has had a task_suspend
+directive.
+
+@item synchronous
+Related in order or timing to other
+occurrences in the system.
+
+@item system call
+In this document, this is used as an
+alternate term for directive.
+
+@item target
+The system on which the application will
+ultimately execute.
+
+@item task
+A logically complete thread of execution. The
+CPU is allocated among the ready tasks.
+
+@item Task Control Block
+A data structure associated with
+each task used by RTEMS to manage that task.
+
+@item task switch
+Alternate terminology for context
+switch. Taking control of the processor from one task and given
+to another.
+
+@item TCB
+An acronym for Task Control Block.
+
+@item tick
+The basic unit of time used by RTEMS. It is a
+user-configurable number of microseconds. The current tick
+expires when the clock_tick directive is invoked.
+
+@item tightly-coupled
+A multiprocessor configuration
+system which communicates via shared memory.
+
+@item timeout
+An argument provided to a number of
+directives which determines the maximum length of time an
+application task is willing to wait to acquire the resource if
+it is not immediately available.
+
+@item timer
+An RTEMS object used to invoke subprograms at
+a later time.
+
+@item Timer Control Block
+A data structure associated
+with each timer used by RTEMS to manage that timer.
+
+@item timeslicing
+A task scheduling discipline in which
+tasks of equal priority are executed for a specific period of
+time before being preempted by another task.
+
+@item timeslice
+The application defined unit of time in
+which the processor is allocated.
+
+@item TMCB
+An acronym for Timer Control Block.
+
+@item transient overload
+A temporary rise in system
+activity which may cause deadlines to be missed. Rate Monotonic
+Scheduling can be used to determine if all deadlines will be met
+under transient overload.
+
+@item user extensions
+Software routines provided by the
+application to enhance the functionality of RTEMS.
+
+@item User Extension Table
+A table which contains the
+entry points for each user extensions.
+
+@item User Initialization Tasks Table
+A table which
+contains the information needed to create and start each of the
+user initialization tasks.
+
+@item user-provided
+Alternate term for user-supplied.
+This term is used to designate any software routines which must
+be written by the application designer.
+
+@item user-supplied
+Alternate term for user-provided.
+This term is used to designate any software routines which must
+be written by the application designer.
+
+@item vector
+Memory pointers used by the processor to
+fetch the address of routines which will handle various
+exceptions and interrupts.
+
+@item wait queue
+The list of tasks blocked pending the
+release of a particular resource. Message queues, regions, and
+semaphores have a wait queue associated with them.
+
+@item yield
+When a task voluntarily releases control of the processor.
+
+@end table
+
diff --git a/doc/user/init.t b/doc/user/init.t
new file mode 100644
index 0000000000..6b558d4ab4
--- /dev/null
+++ b/doc/user/init.t
@@ -0,0 +1,408 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Initialization Manager, Initialization Manager Introduction, Key Concepts Memory Management, Top
+@end ifinfo
+@chapter Initialization Manager
+@ifinfo
+@menu
+* Initialization Manager Introduction::
+* Initialization Manager Background::
+* Initialization Manager Operations::
+* Initialization Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Initialization Manager Introduction, Initialization Manager Background, Initialization Manager, Initialization Manager
+@end ifinfo
+@section Introduction
+
+The initialization manager is responsible for
+initiating and shutting down RTEMS. Initiating RTEMS involves
+creating and starting all configured initialization tasks, and
+for invoking the initialization routine for each user-supplied
+device driver. In a multiprocessor configuration, this manager
+also initializes the interprocessor communications layer. The
+directives provided by the initialization manager are:
+
+@itemize @bullet
+@item @code{initialize_executive} - Initialize RTEMS
+@item @code{initialize_executive_early} - Initialize RTEMS and do NOT Start Multitasking
+@item @code{initialize_executive_late} - Complete Initialization and Start Multitasking
+@item @code{shutdown_executive} - Shutdown RTEMS
+@end itemize
+
+@ifinfo
+@node Initialization Manager Background, Initialization Tasks, Initialization Manager Introduction, Initialization Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Initialization Tasks::
+* The System Initialization Task::
+* The Idle Task::
+* Initialization Manager Failure::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Initialization Tasks, The System Initialization Task, Initialization Manager Background, Initialization Manager Background
+@end ifinfo
+@subsection Initialization Tasks
+
+Initialization task(s) are the mechanism by which
+RTEMS transfers initial control to the user's application.
+Initialization tasks differ from other application tasks in that
+they are defined in the User Initialization Tasks Table and
+automatically created and started by RTEMS as part of its
+initialization sequence. Since the initialization tasks are
+scheduled using the same algorithm as all other RTEMS tasks,
+they must be configured at a priority and mode which will insure
+that they will complete execution before other application tasks
+execute. Although there is no upper limit on the number of
+initialization tasks, an application is required to define at
+least one.
+
+A typical initialization task will create and start
+the static set of application tasks. It may also create any
+other objects used by the application. Initialization tasks
+which only perform initialization should delete themselves upon
+completion to free resources for other tasks. Initialization
+tasks may transform themselves into a "normal" application task.
+This transformation typically involves changing priority and
+execution mode. RTEMS does not automatically delete the
+initialization tasks.
+
+@ifinfo
+@node The System Initialization Task, The Idle Task, Initialization Tasks, Initialization Manager Background
+@end ifinfo
+@subsection The System Initialization Task
+
+The System Initialization Task is responsible for
+initializing all device drivers. As a result, this task has a
+higher priority than all other tasks to insure that no
+application tasks executes until all device drivers are
+initialized. After device initialization in a single processor
+system, this task will delete itself.
+
+The System Initialization Task must have enough stack
+space to successfully execute the initialization routines for
+all device drivers and, in multiprocessor configurations, the
+Multiprocessor Communications Interface Layer initialization
+routine. The CPU Configuration Table contains a field which
+allows the application or BSP to increase the default amount of
+stack space allocated for this task.
+
+In multiprocessor configurations, the System
+Initialization Task does not delete itself after initializing
+the device drivers. Instead it transforms itself into the
+Multiprocessing Server which initializes the Multiprocessor
+Communications Interface Layer, verifies multiprocessor system
+consistency, and processes all requests from remote nodes.
+
+@ifinfo
+@node The Idle Task, Initialization Manager Failure, The System Initialization Task, Initialization Manager Background
+@end ifinfo
+@subsection The Idle Task
+
+The Idle Task is the lowest priority task in a system
+and executes only when no other task is ready to execute. This
+task consists of an infinite loop and will be preempted when any
+other task is made ready to execute.
+
+@ifinfo
+@node Initialization Manager Failure, Initialization Manager Operations, The Idle Task, Initialization Manager Background
+@end ifinfo
+@subsection Initialization Manager Failure
+
+The fatal_error_occurred directive will be called
+from initialize_executive for any of the following reasons:
+
+@itemize @bullet
+@item If either the Configuration Table or the CPU Dependent
+Information Table is not provided.
+
+@item If the starting address of the RTEMS RAM Workspace,
+supplied by the application in the Configuration Table, is NULL
+or is not aligned on a four-byte boundary.
+
+@item If the size of the RTEMS RAM Workspace is not large
+enough to initialize and configure the system.
+
+@item If the interrupt stack size specified is too small.
+
+@item If multiprocessing is configured and the node entry in
+the Multiprocessor Configuration Table is not between one and
+the maximum_nodes entry.
+
+@item If a multiprocessor system is being configured and no
+Multiprocessor Communications Interface is specified.
+
+@item If no user initialization tasks are configured. At
+least one initialization task must be configured to allow RTEMS
+to pass control to the application at the end of the executive
+initialization sequence.
+
+@item If any of the user initialization tasks cannot be
+created or started successfully.
+@end itemize
+
+@ifinfo
+@node Initialization Manager Operations, Initializing RTEMS, Initialization Manager Failure, Initialization Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Initializing RTEMS::
+* Shutting Down RTEMS::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Initializing RTEMS, Shutting Down RTEMS, Initialization Manager Operations, Initialization Manager Operations
+@end ifinfo
+@subsection Initializing RTEMS
+
+The initialize_executive directive is called by the
+board support package at the completion of its initialization
+sequence. RTEMS assumes that the board support package
+successfully completed its initialization activities. The
+initialize_executive directive completes the initialization
+sequence by performing the following actions:
+
+@itemize @bullet
+@item Initializing internal RTEMS variables;
+@item Allocating system resources;
+@item Creating and starting the System Initialization Task;
+@item Creating and starting the Idle Task;
+@item Creating and starting the user initialization task(s); and
+@item Initiating multitasking.
+@end itemize
+
+This directive MUST be called before any other RTEMS
+directives. The effect of calling any RTEMS directives before
+initialize_executive is unpredictable. Many of RTEMS actions
+during initialization are based upon the contents of the
+Configuration Table and CPU Dependent Information Table. For
+more information regarding the format and contents of these
+tables, please refer to the chapter Configuring a System.
+
+The final step in the initialization sequence is the
+initiation of multitasking. When the scheduler and dispatcher
+are enabled, the highest priority, ready task will be dispatched
+to run. Control will not be returned to the board support
+package after multitasking is enabled until shutdown_executive
+the directive is called.
+
+The initialize_executive directive provides a
+conceptually simple way to initialize RTEMS. However, in
+certain cases, this mechanism cannot be used. The
+initialize_executive_early and initialize_executive_late
+directives are provided as an alternative mechanism for
+initializing RTEMS. The initialize_executive_early directive
+returns to the caller BEFORE initiating multitasking. The
+initialize_executive_late directive is invoked to start
+multitasking. It is critical that only one of the RTEMS
+initialization sequences be used in an application.
+
+@ifinfo
+@node Shutting Down RTEMS, Initialization Manager Directives, Initializing RTEMS, Initialization Manager Operations
+@end ifinfo
+@subsection Shutting Down RTEMS
+
+The shutdown_executive directive is invoked by the
+application to end multitasking and return control to the board
+support package. The board support package resumes execution at
+the code immediately following the invocation of the
+initialize_executive directive.
+
+@ifinfo
+@node Initialization Manager Directives, INITIALIZE_EXECUTIVE - Initialize RTEMS, Shutting Down RTEMS, Initialization Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* INITIALIZE_EXECUTIVE - Initialize RTEMS::
+* INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking::
+* INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking::
+* SHUTDOWN_EXECUTIVE - Shutdown RTEMS::
+@end menu
+@end ifinfo
+
+This section details the initialization manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node INITIALIZE_EXECUTIVE - Initialize RTEMS, INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, Initialization Manager Directives, Initialization Manager Directives
+@end ifinfo
+@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_interrupt_level rtems_initialize_executive_early(
+ rtems_configuration_table *configuration_table,
+ rtems_cpu_table *cpu_table
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive is called when the board support
+package has completed its initialization to allow RTEMS to
+initialize the application environment based upon the
+information in the Configuration Table, CPU Dependent
+Information Table, User Initialization Tasks Table, Device
+Driver Table, User Extension Table, Multiprocessor Configuration
+Table, and the Multiprocessor Communications Interface (MPCI)
+Table. This directive starts multitasking and does not return
+to the caller until the shutdown_executive directive is invoked.
+
+@subheading NOTES:
+
+This directive MUST be the first RTEMS directive
+called and it DOES NOT RETURN to the caller until the
+shutdown_executive is invoked.
+
+This directive causes all nodes in the system to
+verify that certain configuration parameters are the same as
+those of the local node. If an inconsistency is detected, then
+a fatal error is generated.
+
+The application must use only one of the two
+initialization sequences: initialize_executive or
+initialize_executive_early and initialize_executive_late. The
+initialize_executive directive is logically equivalent to
+invoking initialize_executive_early and
+initialize_executive_late with no intervening actions.
+
+@page
+@ifinfo
+@node INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, INITIALIZE_EXECUTIVE - Initialize RTEMS, Initialization Manager Directives
+@end ifinfo
+@subsection INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_interrupt_level rtems_initialize_executive_early(
+ rtems_configuration_table *configuration_table,
+ rtems_cpu_table *cpu_table
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive is called when the board support
+package has completed its initialization to allow RTEMS to
+initialize the application environment based upon the
+information in the Configuration Table, CPU Dependent
+Information Table, User Initialization Tasks Table, Device
+Driver Table, User Extension Table, Multiprocessor Configuration
+Table, and the Multiprocessor Communications Interface (MPCI)
+Table. This directive returns to the caller after completing
+the basic RTEMS initialization but before multitasking is
+initiated. The interrupt level in place when the directive is
+invoked is returned to the caller. This interrupt level should
+be the same one passed to initialize_executive_late.
+
+@subheading NOTES:
+
+The application must use only one of the two
+initialization sequences: initialize_executive or
+initialize_executive_early and initialize_executive_late.
+
+@page
+@ifinfo
+@node INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, Initialization Manager Directives
+@end ifinfo
+@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking
+
+@subheading CALLING SEQUENCE:
+
+@example
+void rtems_initialize_executive_late(
+ rtems_interrupt_level bsp_level
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive is called after the
+initialize_executive_early directive has been called to complete
+the RTEMS initialization sequence and initiate multitasking.
+The interrupt level returned by the initialize_executive_early
+directive should be in bsp_level and this value is restored as
+part of this directive returning to the caller after the
+shutdown_executive directive is invoked.
+
+@subheading NOTES:
+
+This directive MUST be the second RTEMS directive
+called and it DOES NOT RETURN to the caller until the
+shutdown_executive is invoked.
+
+This directive causes all nodes in the system to
+verify that certain configuration parameters are the same as
+those of the local node. If an inconsistency is detected, then
+a fatal error is generated.
+
+The application must use only one of the two
+initialization sequences: initialize_executive or
+initialize_executive_early and initialize_executive_late.
+
+
+
+@page
+@ifinfo
+@node SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Task Manager, INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, Initialization Manager Directives
+@end ifinfo
+@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS
+
+@subheading CALLING SEQUENCE:
+
+@example
+void rtems_shutdown_executive(
+ rtems_unsigned32 result
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive is called when the application wishes
+to shutdown RTEMS and return control to the board support
+package. The board support package resumes execution at the
+code immediately following the invocation of the
+initialize_executive directive.
+
+@subheading NOTES:
+
+This directive MUST be the last RTEMS directive
+invoked by an application and it DOES NOT RETURN to the caller.
+
+This directive should not be invoked until the
+executive has successfully completed initialization.
diff --git a/doc/user/intr.t b/doc/user/intr.t
new file mode 100644
index 0000000000..8eb076e8f4
--- /dev/null
+++ b/doc/user/intr.t
@@ -0,0 +1,300 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Interrupt Manager, Interrupt Manager Introduction, TASK_WAKE_WHEN - Wake up when specified, Top
+@end ifinfo
+@chapter Interrupt Manager
+@ifinfo
+@menu
+* Interrupt Manager Introduction::
+* Interrupt Manager Background::
+* Interrupt Manager Operations::
+* Interrupt Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Interrupt Manager Introduction, Interrupt Manager Background, Interrupt Manager, Interrupt Manager
+@end ifinfo
+@section Introduction
+
+Any real-time executive must provide a mechanism for
+quick response to externally generated interrupts to satisfy the
+critical time constraints of the application. The interrupt
+manager provides this mechanism for RTEMS. This manager permits
+quick interrupt response times by providing the critical ability
+to alter task execution which allows a task to be preempted upon
+exit from an ISR. The interrupt manager includes the following
+directive:
+
+@itemize @bullet
+@item @code{interrupt_catch} - Establish an ISR
+@end itemize
+
+@ifinfo
+@node Interrupt Manager Background, Processing an Interrupt, Interrupt Manager Introduction, Interrupt Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Processing an Interrupt::
+* RTEMS Interrupt Levels::
+* Disabling of Interrupts by RTEMS::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Processing an Interrupt, RTEMS Interrupt Levels, Interrupt Manager Background, Interrupt Manager Background
+@end ifinfo
+@subsection Processing an Interrupt
+
+The interrupt manager allows the application to
+connect a function to a hardware interrupt vector. When an
+interrupt occurs, the processor will automatically vector to
+RTEMS. RTEMS saves and restores all registers which are not
+preserved by the normal C calling convention for the target
+processor and invokes the user's ISR. The user's ISR is
+responsible for processing the interrupt, clearing the interrupt
+if necessary, and device specific manipulation.
+
+The interrupt_catch directive connects a procedure to
+an interrupt vector. The interrupt service routine is assumed
+to abide by these conventions and have a prototype similar to
+the following:
+
+@example
+rtems_isr user_isr(
+ rtems_vector_number vector
+);
+@end example
+
+The vector number argument is provided by RTEMS to
+allow the application to identify the interrupt source. This
+could be used to allow a single routine to service interrupts
+from multiple instances of the same device. For example, a
+single routine could service interrupts from multiple serial
+ports and use the vector number to identify which port requires
+servicing.
+
+To minimize the masking of lower or equal priority
+level interrupts, the ISR should perform the minimum actions
+required to service the interrupt. Other non-essential actions
+should be handled by application tasks. Once the user's ISR has
+completed, it returns control to the RTEMS interrupt manager
+which will perform task dispatching and restore the registers
+saved before the ISR was invoked.
+
+The RTEMS interrupt manager guarantees that proper
+task scheduling and dispatching are performed at the conclusion
+of an ISR. A system call made by the ISR may have readied a
+task of higher priority than the interrupted task. Therefore,
+when the ISR completes, the postponed dispatch processing must
+be performed. No dispatch processing is performed as part of
+directives which have been invoked by an ISR.
+
+Applications must adhere to the following rule if
+proper task scheduling and dispatching is to be performed:
+
+@itemize @code{ }
+
+@item @b{The interrupt manager must be used for all ISRs which
+may be interrupted by the highest priority ISR which invokes an
+RTEMS directive.}
+
+@end itemize
+
+
+Consider a processor which allows a numerically low
+interrupt level to interrupt a numerically greater interrupt
+level. In this example, if an RTEMS directive is used in a
+level 4 ISR, then all ISRs which execute at levels 0 through 4
+must use the interrupt manager.
+
+Interrupts are nested whenever an interrupt occurs
+during the execution of another ISR. RTEMS supports efficient
+interrupt nesting by allowing the nested ISRs to terminate
+without performing any dispatch processing. Only when the
+outermost ISR terminates will the postponed dispatching occur.
+
+
+
+@ifinfo
+@node RTEMS Interrupt Levels, Disabling of Interrupts by RTEMS, Processing an Interrupt, Interrupt Manager Background
+@end ifinfo
+@subsection RTEMS Interrupt Levels
+
+Many processors support multiple interrupt levels or
+priorities. The exact number of interrupt levels is processor
+dependent. RTEMS internally supports 256 interrupt levels which
+are mapped to the processor's interrupt levels. For specific
+information on the mapping between RTEMS and the target
+processor's interrupt levels, refer to the Interrupt Processing
+chapter of the C Applications Supplement document for a specific
+target processor.
+
+@ifinfo
+@node Disabling of Interrupts by RTEMS, Interrupt Manager Operations, RTEMS Interrupt Levels, Interrupt Manager Background
+@end ifinfo
+@subsection Disabling of Interrupts by RTEMS
+
+During the execution of directive calls, critical
+sections of code may be executed. When these sections are
+encountered, RTEMS disables all maskable interrupts before the
+execution of the section and restores them to the previous level
+upon completion of the section. RTEMS has been optimized to
+insure that interrupts are disabled for a minimum length of
+time. The maximum length of time interrupts are disabled by
+RTEMS is processor dependent and is detailed in the Timing
+Specification chapter of the C Applications Supplement document
+for a specific target processor.
+
+Non-maskable interrupts (NMI) cannot be disabled, and
+ISRs which execute at this level MUST NEVER issue RTEMS system
+calls. If a directive is invoked, unpredictable results may
+occur due to the inability of RTEMS to protect its critical
+sections. However, ISRs that make no system calls may safely
+execute as non-maskable interrupts.
+
+@ifinfo
+@node Interrupt Manager Operations, Establishing an ISR, Disabling of Interrupts by RTEMS, Interrupt Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Establishing an ISR::
+* Directives Allowed from an ISR::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Establishing an ISR, Directives Allowed from an ISR, Interrupt Manager Operations, Interrupt Manager Operations
+@end ifinfo
+@subsection Establishing an ISR
+
+The interrupt_catch directive establishes an ISR for
+the system. The address of the ISR and its associated CPU
+vector number are specified to this directive. This directive
+installs the RTEMS interrupt wrapper in the processor's
+Interrupt Vector Table and the address of the user's ISR in the
+RTEMS' Vector Table. This directive returns the previous
+contents of the specified vector in the RTEMS' Vector Table.
+
+@ifinfo
+@node Directives Allowed from an ISR, Interrupt Manager Directives, Establishing an ISR, Interrupt Manager Operations
+@end ifinfo
+@subsection Directives Allowed from an ISR
+
+Using the interrupt manager insures that RTEMS knows
+when a directive is being called from an ISR. The ISR may then
+use system calls to synchronize itself with an application task.
+The synchronization may involve messages, events or signals
+being passed by the ISR to the desired task. Directives invoked
+by an ISR must operate only on objects which reside on the local
+node. The following is a list of RTEMS system calls that may be
+made from an ISR:
+
+@itemize @bullet
+@item Task Management
+
+@itemize -
+@item task_get_note, task_set_note, task_suspend, task_resume
+@end itemize
+
+@item Clock Management
+
+@itemize -
+@item clock_get, clock_tick
+@end itemize
+
+@item Message, Event, and Signal Management
+
+@itemize -
+@item message_queue_send, message_queue_urgent
+@item event_send
+@item signal_send
+@end itemize
+
+@item Semaphore Management
+
+@itemize -
+@item semaphore_release
+@end itemize
+
+@item Dual-Ported Memory Management
+
+@itemize -
+@item port_external_to_internal, port_internal_to_external
+@end itemize
+
+@item IO Management
+
+@itemize -
+@item io_initialize, io_open, io_close, io_read, io_write, io_control
+@end itemize
+
+@item Fatal Error Management
+
+@itemize -
+@item fatal_error_occurred
+@end itemize
+
+@item Multiprocessing
+
+@itemize -
+@item multiprocessing_announce
+@end itemize
+@end itemize
+
+@ifinfo
+@node Interrupt Manager Directives, INTERRUPT_CATCH - Establish an ISR, Directives Allowed from an ISR, Interrupt Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* INTERRUPT_CATCH - Establish an ISR::
+@end menu
+@end ifinfo
+
+This section details the interrupt manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node INTERRUPT_CATCH - Establish an ISR, Clock Manager, Interrupt Manager Directives, Interrupt Manager Directives
+@end ifinfo
+@subsection INTERRUPT_CATCH - Establish an ISR
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_interrupt_catch(
+ rtems_isr_entry new_isr_handler,
+ rtems_vector_number vector,
+ rtems_isr_entry *old_isr_handler
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - ISR established successfully@*
+@code{INVALID_NUMBER} - illegal vector number@*
+@code{INVALID_ADDRESS} - illegal ISR entry point
+
+@subheading DESCRIPTION:
+
+This directive establishes an interrupt service
+routine (ISR) for the specified interrupt vector number. The
+new_isr_handler parameter specifies the entry point of the ISR.
+The entry point of the previous ISR for the specified vector is
+returned in old_isr_handler.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
diff --git a/doc/user/io.t b/doc/user/io.t
new file mode 100644
index 0000000000..5176b89224
--- /dev/null
+++ b/doc/user/io.t
@@ -0,0 +1,528 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node I/O Manager, I/O Manager Introduction, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, Top
+@end ifinfo
+@chapter I/O Manager
+@ifinfo
+@menu
+* I/O Manager Introduction::
+* I/O Manager Background::
+* I/O Manager Operations::
+* I/O Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node I/O Manager Introduction, I/O Manager Background, I/O Manager, I/O Manager
+@end ifinfo
+@section Introduction
+
+The input/output interface manager provides a
+well-defined mechanism for accessing device drivers and a
+structured methodology for organizing device drivers. The
+directives provided by the I/O manager are:
+
+@itemize @bullet
+@item @code{io_initialize} - Initialize a device driver
+@item @code{io_register_name} - Register a device name
+@item @code{io_lookup_name} - Look up a device name
+@item @code{io_open} - Open a device
+@item @code{io_close} - Close a device
+@item @code{io_read} - Read from a device
+@item @code{io_write} - Write to a device
+@item @code{io_control} - Special device services
+@end itemize
+
+
+
+@ifinfo
+@node I/O Manager Background, Device Driver Table, I/O Manager Introduction, I/O Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Device Driver Table::
+* Major and Minor Device Numbers::
+* Device Names::
+* Device Driver Environment::
+* Device Driver Interface::
+* Device Driver Initialization::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Device Driver Table, Major and Minor Device Numbers, I/O Manager Background, I/O Manager Background
+@end ifinfo
+@subsection Device Driver Table
+
+Each application utilizing the RTEMS I/O manager must
+specify the address of a Device Driver Table in its
+Configuration Table. This table contains each device driver's
+entry points. Each device driver may contain the following
+entry points:
+
+@itemize @bullet
+@item Initialization
+@item Open
+@item Close
+@item Read
+@item Write
+@item Control
+@end itemize
+
+If the device driver does not support a particular
+entry point, then that entry in the Configuration Table should
+be NULL. RTEMS will return SUCCESSFUL as the executive's and
+zero (0) as the device driver's return code for these device
+driver entry points.
+
+@ifinfo
+@node Major and Minor Device Numbers, Device Names, Device Driver Table, I/O Manager Background
+@end ifinfo
+@subsection Major and Minor Device Numbers
+
+Each call to the I/O manager must provide a device's
+major and minor numbers as arguments. The major number is the
+index of the requested driver's entry points in the Device
+Driver Table, and is used to select a specific device driver.
+The exact usage of the minor number is driver specific, but is
+commonly used to distinguish between a number of devices
+controlled by the same driver.
+
+@ifinfo
+@node Device Names, Device Driver Environment, Major and Minor Device Numbers, I/O Manager Background
+@end ifinfo
+@subsection Device Names
+
+The I/O Manager provides facilities to associate a
+name with a particular device. Directives are provided to
+register the name of a device and to look up the major/minor
+number pair associated with a device name.
+
+@ifinfo
+@node Device Driver Environment, Device Driver Interface, Device Names, I/O Manager Background
+@end ifinfo
+@subsection Device Driver Environment
+
+Application developers, as well as device driver
+developers, must be aware of the following regarding the RTEMS
+I/O Manager:
+
+@itemize @bullet
+@item A device driver routine executes in the context of the
+invoking task. Thus if the driver blocks, the invoking task
+blocks.
+
+@item The device driver is free to change the modes of the
+invoking task, although the driver should restore them to their
+original values.
+
+@item Device drivers may be invoked from ISRs.
+
+@item Only local device drivers are accessible through the I/O
+manager.
+
+@item A device driver routine may invoke all other RTEMS
+directives, including I/O directives, on both local and global
+objects.
+
+@end itemize
+
+Although the RTEMS I/O manager provides a framework
+for device drivers, it makes no assumptions regarding the
+construction or operation of a device driver.
+
+@ifinfo
+@node Device Driver Interface, Device Driver Initialization, Device Driver Environment, I/O Manager Background
+@end ifinfo
+@subsection Device Driver Interface
+
+When an application invokes an I/O manager directive,
+RTEMS determines which device driver entry point must be
+invoked. The information passed by the application to RTEMS is
+then passed to the correct device driver entry point. RTEMS
+will invoke each device driver entry point assuming it is
+compatible with the following prototype:
+
+@example
+rtems_device_driver io_entry(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument_block
+);
+@end example
+
+
+
+The format and contents of the parameter block are
+device driver and entry point dependent.
+
+It is recommended that a device driver avoid
+generating error codes which conflict with those used by
+application components. A common technique used to generate
+driver specific error codes is to make the most significant part
+of the status indicate a driver specific code.
+
+@ifinfo
+@node Device Driver Initialization, I/O Manager Operations, Device Driver Interface, I/O Manager Background
+@end ifinfo
+@subsection Device Driver Initialization
+
+RTEMS automatically initializes all device drivers
+when multitasking is initiated via the initialize_executive
+directive. RTEMS initializes the device drivers by invoking
+each device driver initialization entry point with the following
+parameters:
+
+@table @asis
+@item major
+the major device number for this device driver.
+
+@item minor
+zero.
+
+@item argument_block
+will point to the Configuration Table.
+
+@end table
+
+The returned status will be ignored by RTEMS. If the driver
+cannot successfully initialize the device, then it should invoke
+the fatal_error_occurred directive.
+
+@ifinfo
+@node I/O Manager Operations, Register and Lookup Name, Device Driver Initialization, I/O Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Register and Lookup Name::
+* Accessing an Device Driver::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Register and Lookup Name, Accessing an Device Driver, I/O Manager Operations, I/O Manager Operations
+@end ifinfo
+@subsection Register and Lookup Name
+
+The io_register directive associates a name with the
+specified device (i.e. major/minor number pair). Device names
+are typically registered as part of the device driver
+initialization sequence. The io_lookup directive is used to
+determine the major/minor number pair associated with the
+specified device name. The use of these directives frees the
+application from being dependent on the arbitrary assignment of
+major numbers in a particular application. No device naming
+conventions are dictated by RTEMS.
+
+@ifinfo
+@node Accessing an Device Driver, I/O Manager Directives, Register and Lookup Name, I/O Manager Operations
+@end ifinfo
+@subsection Accessing an Device Driver
+
+The I/O manager provides directives which enable the
+application program to utilize device drivers in a standard
+manner. There is a direct correlation between the RTEMS I/O
+manager directives io_initialize, io_open, io_close, io_read,
+io_write, and io_control and the underlying device driver entry
+points.
+
+@ifinfo
+@node I/O Manager Directives, IO_INITIALIZE - Initialize a device driver, Accessing an Device Driver, I/O Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* IO_INITIALIZE - Initialize a device driver::
+* IO_REGISTER_NAME - Register a device::
+* IO_LOOKUP_NAME - Lookup a device::
+* IO_OPEN - Open a device::
+* IO_CLOSE - Close a device::
+* IO_READ - Read from a device::
+* IO_WRITE - Write to a device::
+* IO_CONTROL - Special device services::
+@end menu
+@end ifinfo
+
+This section details the I/O manager's directives. A
+subsection is dedicated to each of this manager's directives and
+describes the calling sequence, related constants, usage, and
+status codes.
+
+@page
+@ifinfo
+@node IO_INITIALIZE - Initialize a device driver, IO_REGISTER_NAME - Register a device, I/O Manager Directives, I/O Manager Directives
+@end ifinfo
+@subsection IO_INITIALIZE - Initialize a device driver
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_initialize(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{INVALID_NUMBER} - invalid major device number
+
+@subheading DESCRIPTION:
+
+This directive calls the device driver initialization
+routine specified in the Device Driver Table for this major
+number. This directive is automatically invoked for each device
+driver when multitasking is initiated via the
+initialize_executive directive.
+
+A device driver initialization module is responsible
+for initializing all hardware and data structures associated
+with a device. If necessary, it can allocate memory to be used
+during other operations.
+
+@subheading NOTES:
+
+This directive may or may not cause the calling task
+to be preempted. This is dependent on the device driver being
+initialized.
+
+@page
+@ifinfo
+@node IO_REGISTER_NAME - Register a device, IO_LOOKUP_NAME - Lookup a device, IO_INITIALIZE - Initialize a device driver, I/O Manager Directives
+@end ifinfo
+@subsection IO_REGISTER_NAME - Register a device
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_register_name(
+ char *name,
+ rtems_device_major_number major,
+ rtems_device_minor_number minor
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{TOO_MANY} - too many devices registered
+
+@subheading DESCRIPTION:
+
+This directive associates name with the specified
+major/minor number pair.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node IO_LOOKUP_NAME - Lookup a device, IO_OPEN - Open a device, IO_REGISTER_NAME - Register a device, I/O Manager Directives
+@end ifinfo
+@subsection IO_LOOKUP_NAME - Lookup a device
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_lookup(
+ const char *name,
+ rtems_driver_name_t **device_info
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{UNSATISFIED} - name not registered
+
+@subheading DESCRIPTION:
+
+This directive returns the major/minor number pair
+associated with the given device name in device_info.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node IO_OPEN - Open a device, IO_CLOSE - Close a device, IO_LOOKUP_NAME - Lookup a device, I/O Manager Directives
+@end ifinfo
+@subsection IO_OPEN - Open a device
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_open(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{INVALID_NUMBER} - invalid major device number
+
+@subheading DESCRIPTION:
+
+This directive calls the device driver open routine
+specified in the Device Driver Table for this major number. The
+open entry point is commonly used by device drivers to provide
+exclusive access to a device.
+
+@subheading NOTES:
+
+This directive may or may not cause the calling task
+to be preempted. This is dependent on the device driver being
+invoked.
+
+@page
+@ifinfo
+@node IO_CLOSE - Close a device, IO_READ - Read from a device, IO_OPEN - Open a device, I/O Manager Directives
+@end ifinfo
+@subsection IO_CLOSE - Close a device
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_close(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{INVALID_NUMBER} - invalid major device number
+
+@subheading DESCRIPTION:
+
+This directive calls the device driver close routine
+specified in the Device Driver Table for this major number. The
+close entry point is commonly used by device drivers to
+relinquish exclusive access to a device.
+
+@subheading NOTES:
+
+This directive may or may not cause the calling task
+to be preempted. This is dependent on the device driver being
+invoked.
+
+@page
+@ifinfo
+@node IO_READ - Read from a device, IO_WRITE - Write to a device, IO_CLOSE - Close a device, I/O Manager Directives
+@end ifinfo
+@subsection IO_READ - Read from a device
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_read(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{INVALID_NUMBER} - invalid major device number
+
+@subheading DESCRIPTION:
+
+This directive calls the device driver read routine
+specified in the Device Driver Table for this major number.
+Read operations typically require a buffer address as part of
+the argument parameter block. The contents of this buffer will
+be replaced with data from the device.
+
+@subheading NOTES:
+
+This directive may or may not cause the calling task
+to be preempted. This is dependent on the device driver being
+invoked.
+
+@page
+@ifinfo
+@node IO_WRITE - Write to a device, IO_CONTROL - Special device services, IO_READ - Read from a device, I/O Manager Directives
+@end ifinfo
+@subsection IO_WRITE - Write to a device
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_write(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{INVALID_NUMBER} - invalid major device number
+
+@subheading DESCRIPTION:
+
+This directive calls the device driver write routine
+specified in the Device Driver Table for this major number.
+Write operations typically require a buffer address as part of
+the argument parameter block. The contents of this buffer will
+be sent to the device.
+
+@subheading NOTES:
+
+This directive may or may not cause the calling task
+to be preempted. This is dependent on the device driver being
+invoked.
+
+@page
+@ifinfo
+@node IO_CONTROL - Special device services, Fatal Error Manager, IO_WRITE - Write to a device, I/O Manager Directives
+@end ifinfo
+@subsection IO_CONTROL - Special device services
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_io_control(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - successfully initialized@*
+@code{INVALID_NUMBER} - invalid major device number
+
+@subheading DESCRIPTION:
+
+This directive calls the device driver I/O control
+routine specified in the Device Driver Table for this major
+number. The exact functionality of the driver entry called by
+this directive is driver dependent. It should not be assumed
+that the control entries of two device drivers are compatible.
+For example, an RS-232 driver I/O control operation may change
+the baud rate of a serial line, while an I/O control operation
+for a floppy disk driver may cause a seek operation.
+
+@subheading NOTES:
+
+This directive may or may not cause the calling task
+to be preempted. This is dependent on the device driver being
+invoked.
+
+
+
diff --git a/doc/user/mp.t b/doc/user/mp.t
new file mode 100644
index 0000000000..05a62978c4
--- /dev/null
+++ b/doc/user/mp.t
@@ -0,0 +1,628 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Multiprocessing Manager, Multiprocessing Manager Introduction, Configuring a System Sizing the RTEMS RAM Workspace, Top
+@end ifinfo
+@chapter Multiprocessing Manager
+@ifinfo
+@menu
+* Multiprocessing Manager Introduction::
+* Multiprocessing Manager Background::
+* Multiprocessing Manager Multiprocessor Communications Interface Layer::
+* Multiprocessing Manager Operations::
+* Multiprocessing Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Multiprocessing Manager Introduction, Multiprocessing Manager Background, Multiprocessing Manager, Multiprocessing Manager
+@end ifinfo
+@section Introduction
+
+In multiprocessor real-time systems, new
+requirements, such as sharing data and global resources between
+processors, are introduced. This requires an efficient and
+reliable communications vehicle which allows all processors to
+communicate with each other as necessary. In addition, the
+ramifications of multiple processors affect each and every
+characteristic of a real-time system, almost always making them
+more complicated.
+
+RTEMS addresses these issues by providing simple and
+flexible real-time multiprocessing capabilities. The executive
+easily lends itself to both tightly-coupled and loosely-coupled
+configurations of the target system hardware. In addition,
+RTEMS supports systems composed of both homogeneous and
+heterogeneous mixtures of processors and target boards.
+
+A major design goal of the RTEMS executive was to
+transcend the physical boundaries of the target hardware
+configuration. This goal is achieved by presenting the
+application software with a logical view of the target system
+where the boundaries between processor nodes are transparent.
+As a result, the application developer may designate objects
+such as tasks, queues, events, signals, semaphores, and memory
+blocks as global objects. These global objects may then be
+accessed by any task regardless of the physical location of the
+object and the accessing task. RTEMS automatically determines
+that the object being accessed resides on another processor and
+performs the actions required to access the desired object.
+Simply stated, RTEMS allows the entire system, both hardware and
+software, to be viewed logically as a single system.
+
+@ifinfo
+@node Multiprocessing Manager Background, Nodes, Multiprocessing Manager Introduction, Multiprocessing Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Nodes::
+* Global Objects::
+* Global Object Table::
+* Remote Operations::
+* Proxies::
+* Multiprocessor Configuration Table::
+@end menu
+@end ifinfo
+
+RTEMS makes no assumptions regarding the connection
+media or topology of a multiprocessor system. The tasks which
+compose a particular application can be spread among as many
+processors as needed to satisfy the application's timing
+requirements. The application tasks can interact using a subset
+of the RTEMS directives as if they were on the same processor.
+These directives allow application tasks to exchange data,
+communicate, and synchronize regardless of which processor they
+reside upon.
+
+The RTEMS multiprocessor execution model is multiple
+instruction streams with multiple data streams (MIMD). This
+execution model has each of the processors executing code
+independent of the other processors. Because of this
+parallelism, the application designer can more easily guarantee
+deterministic behavior.
+
+By supporting heterogeneous environments, RTEMS
+allows the systems designer to select the most efficient
+processor for each subsystem of the application. Configuring
+RTEMS for a heterogeneous environment is no more difficult than
+for a homogeneous one. In keeping with RTEMS philosophy of
+providing transparent physical node boundaries, the minimal
+heterogeneous processing required is isolated in the MPCI layer.
+
+@ifinfo
+@node Nodes, Global Objects, Multiprocessing Manager Background, Multiprocessing Manager Background
+@end ifinfo
+@subsection Nodes
+
+A processor in a RTEMS system is referred to as a
+node. Each node is assigned a unique non-zero node number by
+the application designer. RTEMS assumes that node numbers are
+assigned consecutively from one to maximum_nodes. The node
+number, node, and the maximum number of nodes, maximum_nodes, in
+a system are found in the Multiprocessor Configuration Table.
+The maximum_nodes field and the number of global objects,
+maximum_global_objects, is required to be the same on all nodes
+in a system.
+
+The node number is used by RTEMS to identify each
+node when performing remote operations. Thus, the
+Multiprocessor Communications Interface Layer (MPCI) must be
+able to route messages based on the node number.
+
+@ifinfo
+@node Global Objects, Global Object Table, Nodes, Multiprocessing Manager Background
+@end ifinfo
+@subsection Global Objects
+
+All RTEMS objects which are created with the GLOBAL
+attribute will be known on all other nodes. Global objects can
+be referenced from any node in the system, although certain
+directive specific restrictions (e.g. one cannot delete a remote
+object) may apply. A task does not have to be global to perform
+operations involving remote objects. The maximum number of
+global objects is the system is user configurable and can be
+found in the maximum_global_objects field in the Multiprocessor
+Configuration Table. The distribution of tasks to processors is
+performed during the application design phase. Dynamic task
+relocation is not supported by RTEMS.
+
+@ifinfo
+@node Global Object Table, Remote Operations, Global Objects, Multiprocessing Manager Background
+@end ifinfo
+@subsection Global Object Table
+
+RTEMS maintains two tables containing object
+information on every node in a multiprocessor system: a local
+object table and a global object table. The local object table
+on each node is unique and contains information for all objects
+created on this node whether those objects are local or global.
+The global object table contains information regarding all
+global objects in the system and, consequently, is the same on
+every node.
+
+Since each node must maintain an identical copy of
+the global object table, the maximum number of entries in each
+copy of the table must be the same. The maximum number of
+entries in each copy is determined by the
+maximum_global_objects parameter in the Multiprocessor
+Configuration Table. This parameter, as well as the
+maximum_nodes parameter, is required to be the same on all
+nodes. To maintain consistency among the table copies, every
+node in the system must be informed of the creation or deletion
+of a global object.
+
+@ifinfo
+@node Remote Operations, Proxies, Global Object Table, Multiprocessing Manager Background
+@end ifinfo
+@subsection Remote Operations
+
+When an application performs an operation on a remote
+global object, RTEMS must generate a Remote Request (RQ) message
+and send it to the appropriate node. After completing the
+requested operation, the remote node will build a Remote
+Response (RR) message and send it to the originating node.
+Messages generated as a side-effect of a directive (such as
+deleting a global task) are known as Remote Processes (RP) and
+do not require the receiving node to respond.
+
+Other than taking slightly longer to execute
+directives on remote objects, the application is unaware of the
+location of the objects it acts upon. The exact amount of
+overhead required for a remote operation is dependent on the
+media connecting the nodes and, to a lesser degree, on the
+efficiency of the user-provided MPCI routines.
+
+The following shows the typical transaction sequence
+during a remote application:
+
+@enumerate
+
+@item The application issues a directive accessing a
+remote global object.
+
+@item RTEMS determines the node on which the object
+resides.
+
+@item RTEMS calls the user-provided MPCI routine
+GET_PACKET to obtain a packet in which to build a RQ message.
+
+@item After building a message packet, RTEMS calls the
+user-provided MPCI routine SEND_PACKET to transmit the packet to
+the node on which the object resides (referred to as the
+destination node).
+
+@item The calling task is blocked until the RR message
+arrives, and control of the processor is transferred to another
+task.
+
+@item The MPCI layer on the destination node senses the
+arrival of a packet (commonly in an ISR), and calls the
+multiprocessing_announce directive. This directive readies the
+Multiprocessing Server.
+
+@item The Multiprocessing Server calls the user-provided
+MPCI routine RECEIVE_PACKET, performs the requested operation,
+builds an RR message, and returns it to the originating node.
+
+@item The MPCI layer on the originating node senses the
+arrival of a packet (typically via an interrupt), and calls the
+RTEMS multiprocessing_announce directive. This directive
+readies the Multiprocessing Server.
+
+@item The Multiprocessing Server calls the user-provided
+MPCI routine RECEIVE_PACKET, readies the original requesting
+task, and blocks until another packet arrives. Control is
+transferred to the original task which then completes processing
+of the directive.
+
+@end enumerate
+
+If an uncorrectable error occurs in the user-provided
+MPCI layer, the fatal error handler should be invoked. RTEMS
+assumes the reliable transmission and reception of messages by
+the MPCI and makes no attempt to detect or correct errors.
+
+@ifinfo
+@node Proxies, Multiprocessor Configuration Table, Remote Operations, Multiprocessing Manager Background
+@end ifinfo
+@subsection Proxies
+
+A proxy is an RTEMS data structure which resides on a
+remote node and is used to represent a task which must block as
+part of a remote operation. This action can occur as part of the
+semaphore_obtain and message_queue_receive directives. If the
+object were local, the task's control block would be available
+for modification to indicate it was blocking on a message queue
+or semaphore. However, the task's control block resides only on
+the same node as the task. As a result, the remote node must
+allocate a proxy to represent the task until it can be readied.
+
+The maximum number of proxies is defined in the
+Multiprocessor Configuration Table. Each node in a
+multiprocessor system may require a different number of proxies
+to be configured. The distribution of proxy control blocks is
+application dependent and is different from the distribution of
+tasks.
+
+@ifinfo
+@node Multiprocessor Configuration Table, Multiprocessing Manager Multiprocessor Communications Interface Layer, Proxies, Multiprocessing Manager Background
+@end ifinfo
+@subsection Multiprocessor Configuration Table
+
+The Multiprocessor Configuration Table contains
+information needed by RTEMS when used in a multiprocessor
+system. This table is discussed in detail in the section
+Multiprocessor Configuration Table of the Configuring a System
+chapter.
+
+@ifinfo
+@node Multiprocessing Manager Multiprocessor Communications Interface Layer, INITIALIZATION, Multiprocessor Configuration Table, Multiprocessing Manager
+@end ifinfo
+@section Multiprocessor Communications Interface Layer
+@ifinfo
+@menu
+* INITIALIZATION::
+* GET_PACKET::
+* RETURN_PACKET::
+* RECEIVE_PACKET::
+* SEND_PACKET::
+* Supporting Heterogeneous Environments::
+@end menu
+@end ifinfo
+
+The Multiprocessor Communications Interface Layer
+(MPCI) is a set of user-provided procedures which enable the
+nodes in a multiprocessor system to communicate with one
+another. These routines are invoked by RTEMS at various times
+in the preparation and processing of remote requests.
+Interrupts are enabled when an MPCI procedure is invoked. It is
+assumed that if the execution mode and/or interrupt level are
+altered by the MPCI layer, that they will be restored prior to
+returning to RTEMS.
+
+The MPCI layer is responsible for managing a pool of
+buffers called packets and for sending these packets between
+system nodes. Packet buffers contain the messages sent between
+the nodes. Typically, the MPCI layer will encapsulate the
+packet within an envelope which contains the information needed
+by the MPCI layer. The number of packets available is dependent
+on the MPCI layer implementation.
+
+The entry points to the routines in the user's MPCI
+layer should be placed in the Multiprocessor Communications
+Interface Table. The user must provide entry points for each of
+the following table entries in a multiprocessor system:
+
+@itemize @bullet
+@item initialization initialize the MPCI
+@item get_packet obtain a packet buffer
+@item return_packet return a packet buffer
+@item send_packet send a packet to another node
+@item receive_packet called to get an arrived packet
+@end itemize
+
+A packet is sent by RTEMS in each of the following
+situations:
+
+@itemize @bullet
+@item an RQ is generated on an originating node;
+@item an RR is generated on a destination node;
+@item a global object is created;
+@item a global object is deleted;
+@item a local task blocked on a remote object is deleted;
+@item during system initialization to check for system consistency.
+@end itemize
+
+If the target hardware supports it, the arrival of a
+packet at a node may generate an interrupt. Otherwise, the
+real-time clock ISR can check for the arrival of a packet. In
+any case, the multiprocessing_announce directive must be called
+to announce the arrival of a packet. After exiting the ISR,
+control will be passed to the Multiprocessing Server to process
+the packet. The Multiprocessing Server will call the get_packet
+entry to obtain a packet buffer and the receive_entry entry to
+copy the message into the buffer obtained.
+
+@ifinfo
+@node INITIALIZATION, GET_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer, Multiprocessing Manager Multiprocessor Communications Interface Layer
+@end ifinfo
+@subsection INITIALIZATION
+
+The INITIALIZATION component of the user-provided
+MPCI layer is called as part of the initialize_executive
+directive to initialize the MPCI layer and associated hardware.
+It is invoked immediately after all of the device drivers have
+been initialized. This component should be adhere to the
+following prototype:
+
+@example
+@group
+rtems_mpci_entry user_mpci_initialization(
+ rtems_configuration_table *configuration
+);
+@end group
+@end example
+
+where configuration is the address of the user's
+Configuration Table. Operations on global objects cannot be
+performed until this component is invoked. The INITIALIZATION
+component is invoked only once in the life of any system. If
+the MPCI layer cannot be successfully initialized, the fatal
+error manager should be invoked by this routine.
+
+One of the primary functions of the MPCI layer is to
+provide the executive with packet buffers. The INITIALIZATION
+routine must create and initialize a pool of packet buffers.
+There must be enough packet buffers so RTEMS can obtain one
+whenever needed.
+
+@ifinfo
+@node GET_PACKET, RETURN_PACKET, INITIALIZATION, Multiprocessing Manager Multiprocessor Communications Interface Layer
+@end ifinfo
+@subsection GET_PACKET
+
+The GET_PACKET component of the user-provided MPCI
+layer is called when RTEMS must obtain a packet buffer to send
+or broadcast a message. This component should be adhere to the
+following prototype:
+
+@example
+@group
+rtems_mpci_entry user_mpci_get_packet(
+ rtems_packet_prefix **packet
+);
+@end group
+@end example
+
+where packet is the address of a pointer to a packet.
+This routine always succeeds and, upon return, packet will
+contain the address of a packet. If for any reason, a packet
+cannot be successfully obtained, then the fatal error manager
+should be invoked.
+
+RTEMS has been optimized to avoid the need for
+obtaining a packet each time a message is sent or broadcast.
+For example, RTEMS sends response messages (RR) back to the
+originator in the same packet in which the request message (RQ)
+arrived.
+
+@ifinfo
+@node RETURN_PACKET, RECEIVE_PACKET, GET_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer
+@end ifinfo
+@subsection RETURN_PACKET
+
+The RETURN_PACKET component of the user-provided MPCI
+layer is called when RTEMS needs to release a packet to the free
+packet buffer pool. This component should be adhere to the
+following prototype:
+
+@example
+@group
+rtems_mpci_entry user_mpci_return_packet(
+ rtems_packet_prefix *packet
+);
+@end group
+@end example
+
+where packet is the address of a packet. If the
+packet cannot be successfully returned, the fatal error manager
+should be invoked.
+
+@ifinfo
+@node RECEIVE_PACKET, SEND_PACKET, RETURN_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer
+@end ifinfo
+@subsection RECEIVE_PACKET
+
+The RECEIVE_PACKET component of the user-provided
+MPCI layer is called when RTEMS needs to obtain a packet which
+has previously arrived. This component should be adhere to the
+following prototype:
+
+@example
+@group
+rtems_mpci_entry user_mpci_receive_packet(
+ rtems_packet_prefix **packet
+);
+@end group
+@end example
+
+where packet is a pointer to the address of a packet
+to place the message from another node. If a message is
+available, then packet will contain the address of the message
+from another node. If no messages are available, this entry
+packet should contain NULL.
+
+@ifinfo
+@node SEND_PACKET, Supporting Heterogeneous Environments, RECEIVE_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer
+@end ifinfo
+@subsection SEND_PACKET
+
+The SEND_PACKET component of the user-provided MPCI
+layer is called when RTEMS needs to send a packet containing a
+message to another node. This component should be adhere to the
+following prototype:
+
+@example
+@group
+rtems_mpci_entry user_mpci_send_packet(
+ rtems_unsigned32 node,
+ rtems_packet_prefix **packet
+);
+@end group
+@end example
+
+where node is the node number of the destination and packet is the
+address of a packet which containing a message. If the packet cannot
+be successfully sent, the fatal error manager should be invoked.
+
+If node is set to zero, the packet is to be
+broadcasted to all other nodes in the system. Although some
+MPCI layers will be built upon hardware which support a
+broadcast mechanism, others may be required to generate a copy
+of the packet for each node in the system.
+
+Many MPCI layers use the packet_length field of the MP_packet_prefix
+of the packet to avoid sending unnecessary data. This is especially
+useful if the media connecting the nodes is relatively slow.
+
+The to_convert field of the MP_packet_prefix portion of the packet indicates
+how much of the packet (in unsigned32's) may require conversion in a
+heterogeneous system.
+
+@ifinfo
+@node Supporting Heterogeneous Environments, Multiprocessing Manager Operations, SEND_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer
+@end ifinfo
+@subsection Supporting Heterogeneous Environments
+
+Developing an MPCI layer for a heterogeneous system
+requires a thorough understanding of the differences between the
+processors which comprise the system. One difficult problem is
+the varying data representation schemes used by different
+processor types. The most pervasive data representation problem
+is the order of the bytes which compose a data entity.
+Processors which place the least significant byte at the
+smallest address are classified as little endian processors.
+Little endian byte-ordering is shown below:
+
+
+@example
+@group
++---------------+----------------+---------------+----------------+
+| | | | |
+| Byte 3 | Byte 2 | Byte 1 | Byte 0 |
+| | | | |
++---------------+----------------+---------------+----------------+
+@end group
+@end example
+
+Conversely, processors which place the most
+significant byte at the smallest address are classified as big
+endian processors. Big endian byte-ordering is shown below:
+
+@example
+@group
++---------------+----------------+---------------+----------------+
+| | | | |
+| Byte 0 | Byte 1 | Byte 2 | Byte 3 |
+| | | | |
++---------------+----------------+---------------+----------------+
+@end group
+@end example
+
+Unfortunately, sharing a data structure between big
+endian and little endian processors requires translation into a
+common endian format. An application designer typically chooses
+the common endian format to minimize conversion overhead.
+
+Another issue in the design of shared data structures
+is the alignment of data structure elements. Alignment is both
+processor and compiler implementation dependent. For example,
+some processors allow data elements to begin on any address
+boundary, while others impose restrictions. Common restrictions
+are that data elements must begin on either an even address or
+on a long word boundary. Violation of these restrictions may
+cause an exception or impose a performance penalty.
+
+Other issues which commonly impact the design of
+shared data structures include the representation of floating
+point numbers, bit fields, decimal data, and character strings.
+In addition, the representation method for negative integers
+could be one's or two's complement. These factors combine to
+increase the complexity of designing and manipulating data
+structures shared between processors.
+
+RTEMS addressed these issues in the design of the
+packets used to communicate between nodes. The RTEMS packet
+format is designed to allow the MPCI layer to perform all
+necessary conversion without burdening the developer with the
+details of the RTEMS packet format. As a result, the MPCI layer
+must be aware of the following:
+
+@itemize @bullet
+@item All packets must begin on a four byte boundary.
+
+@item Packets are composed of both RTEMS and application data.
+All RTEMS data is treated as thirty-two (32) bit unsigned
+quantities and is in the first MINIMUM_UNSIGNED32S_TO_CONVERT
+thirty-two (32) quantities of the packet.
+
+@item The RTEMS data component of the packet must be in native
+endian format. Endian conversion may be performed by either the
+sending or receiving MPCI layer.
+
+@item RTEMS makes no assumptions regarding the application
+data component of the packet.
+@end itemize
+
+@ifinfo
+@node Multiprocessing Manager Operations, Announcing a Packet, Supporting Heterogeneous Environments, Multiprocessing Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Announcing a Packet::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Announcing a Packet, Multiprocessing Manager Directives, Multiprocessing Manager Operations, Multiprocessing Manager Operations
+@end ifinfo
+@subsection Announcing a Packet
+
+The multiprocessing_announce directive is called by
+the MPCI layer to inform RTEMS that a packet has arrived from
+another node. This directive can be called from an interrupt
+service routine or from within a polling routine.
+
+@ifinfo
+@node Multiprocessing Manager Directives, MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Announcing a Packet, Multiprocessing Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet::
+@end menu
+@end ifinfo
+
+This section details the additional directives
+required to support RTEMS in a multiprocessor configuration. A
+subsection is dedicated to each of this manager's directives and
+describes the calling sequence, related constants, usage, and
+status codes.
+
+@page
+@ifinfo
+@node MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Directive Status Codes, Multiprocessing Manager Directives, Multiprocessing Manager Directives
+@end ifinfo
+@subsection MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
+
+@subheading CALLING SEQUENCE:
+
+@example
+void rtems_multiprocessing_announce( void );
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive informs RTEMS that a multiprocessing
+communications packet has arrived from another node. This
+directive is called by the user-provided MPCI, and is only used
+in multiprocessor configurations.
+
+@subheading NOTES:
+
+This directive is typically called from an ISR.
+
+This directive will almost certainly cause the
+calling task to be preempted.
+
+This directive does not generate activity on remote nodes.
diff --git a/doc/user/msg.t b/doc/user/msg.t
new file mode 100644
index 0000000000..832b69ef2e
--- /dev/null
+++ b/doc/user/msg.t
@@ -0,0 +1,714 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Message Manager, Message Manager Introduction, SEMAPHORE_RELEASE - Release a semaphore, Top
+@end ifinfo
+@chapter Message Manager
+@ifinfo
+@menu
+* Message Manager Introduction::
+* Message Manager Background::
+* Message Manager Operations::
+* Message Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Message Manager Introduction, Message Manager Background, Message Manager, Message Manager
+@end ifinfo
+@section Introduction
+
+The message manager provides communication and
+synchronization capabilities using RTEMS message queues. The
+directives provided by the message manager are:
+
+@itemize @bullet
+@item @code{message_queue_create} - Create a queue
+@item @code{message_queue_ident} - Get ID of a queue
+@item @code{message_queue_delete} - Delete a queue
+@item @code{message_queue_send} - Put message at rear of a queue
+@item @code{message_queue_urgent} - Put message at front of a queue
+@item @code{message_queue_broadcast} - Broadcast N messages to a queue
+@item @code{message_queue_receive} - Receive message from a queue
+@item @code{message_queue_flush} - Flush all messages on a queue
+@end itemize
+
+@ifinfo
+@node Message Manager Background, Messages, Message Manager Introduction, Message Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Messages::
+* Message Queues::
+* Building a Message Queue's Attribute Set::
+* Building a MESSAGE_QUEUE_RECEIVE Option Set::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Messages, Message Queues, Message Manager Background, Message Manager Background
+@end ifinfo
+@subsection Messages
+
+A message is a variable length buffer where
+information can be stored to support communication. The length
+of the message and the information stored in that message are
+user-defined and can be actual data, pointer(s), or empty.
+
+@ifinfo
+@node Message Queues, Building a Message Queue's Attribute Set, Messages, Message Manager Background
+@end ifinfo
+@subsection Message Queues
+
+A message queue permits the passing of messages among
+tasks and ISRs. Message queues can contain a variable number of
+messages. Normally messages are sent to and received from the
+queue in FIFO order using the message_queue_send directive.
+However, the message_queue_urgent directive can be used to place
+messages at the head of a queue in LIFO order.
+
+Synchronization can be accomplished when a task can
+wait for a message to arrive at a queue. Also, a task may poll
+a queue for the arrival of a message.
+
+The maximum length message which can be sent is set
+on a per message queue basis.
+
+@ifinfo
+@node Building a Message Queue's Attribute Set, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Queues, Message Manager Background
+@end ifinfo
+@subsection Building a Message Queue's Attribute Set
+
+In general, an attribute set is built by a bitwise OR
+of the desired attribute components. The set of valid message
+queue attributes is provided in the following table:
+
+@itemize @bullet
+@item FIFO - tasks wait by FIFO (default)
+@item PRIORITY - tasks wait by priority
+@item LOCAL - local message queue (default)
+@item GLOBAL - global message queue
+@end itemize
+
+
+
+An attribute listed as a default is not required to
+appear in the attribute list, although it is a good programming
+practice to specify default attributes. If all defaults are
+desired, the attribute DEFAULT_ATTRIBUTES should be specified on
+this call.
+
+This example demonstrates the attribute_set parameter
+needed to create a local message queue with the task priority
+waiting queue discipline. The attribute_set parameter to the
+message_queue_create directive could be either PRIORITY or LOCAL
+| PRIORITY. The attribute_set parameter can be set to PRIORITY
+because LOCAL is the default for all created message queues. If
+a similar message queue were to be known globally, then the
+attribute_set parameter would be GLOBAL | PRIORITY.
+
+@ifinfo
+@node Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager Operations, Building a Message Queue's Attribute Set, Message Manager Background
+@end ifinfo
+@subsection Building a MESSAGE_QUEUE_RECEIVE Option Set
+
+In general, an option is built by a bitwise OR of the
+desired option components. The set of valid options for the
+message_queue_receive directive are listed in the following
+table:
+
+@itemize @bullet
+@item WAIT - task will wait for a message (default)
+@item NO_WAIT - task should not wait
+@end itemize
+
+An option listed as a default is not required to
+appear in the option OR list, although it is a good programming
+practice to specify default options. If all defaults are
+desired, the option DEFAULT_OPTIONS should be specified on this
+call.
+
+This example demonstrates the option parameter needed
+to poll for a message to arrive. The option parameter passed to
+the message_queue_receive directive should be NO_WAIT.
+
+@ifinfo
+@node Message Manager Operations, Creating a Message Queue, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Message Queue::
+* Obtaining Message Queue IDs::
+* Receiving a Message::
+* Sending a Message::
+* Broadcasting a Message::
+* Deleting a Message Queue::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Message Queue, Obtaining Message Queue IDs, Message Manager Operations, Message Manager Operations
+@end ifinfo
+@subsection Creating a Message Queue
+
+The message_queue_create directive creates a message
+queue with the user-defined name. The user specifies the
+maximum message size and maximum number of messages which can be
+placed in the message queue at one time. The user may select
+FIFO or task priority as the method for placing waiting tasks in
+the task wait queue. RTEMS allocates a Queue Control Block
+(QCB) from the QCB free list to maintain the newly created queue
+as well as memory for the message buffer pool associated with
+this message queue. RTEMS also generates a message queue ID
+which is returned to the calling task.
+
+For GLOBAL message queues, the maximum message size
+is effectively limited to the longest message which the MPCI is
+capable of transmitting.
+
+@ifinfo
+@node Obtaining Message Queue IDs, Receiving a Message, Creating a Message Queue, Message Manager Operations
+@end ifinfo
+@subsection Obtaining Message Queue IDs
+
+When a message queue is created, RTEMS generates a
+unique message queue ID. The message queue ID may be obtained
+by either of two methods. First, as the result of an invocation
+of the message_queue_create directive, the queue ID is stored in
+a user provided location. Second, the queue ID may be obtained
+later using the message_queue_ident directive. The queue ID is
+used by other message manager directives to access this message
+queue.
+
+@ifinfo
+@node Receiving a Message, Sending a Message, Obtaining Message Queue IDs, Message Manager Operations
+@end ifinfo
+@subsection Receiving a Message
+
+The message_queue_receive directive attempts to
+retrieve a message from the specified message queue. If at
+least one message is in the queue, then the message is removed
+from the queue, copied to the caller's message buffer, and
+returned immediately along with the length of the message. When
+messages are unavailable, one of the following situations
+applies:
+
+@itemize @bullet
+@item By default, the calling task will wait forever for the
+message to arrive.
+
+@item Specifying the NO_WAIT option forces an immediate return
+with an error status code.
+
+@item Specifying a timeout limits the period the task will
+wait before returning with an error status.
+@end itemize
+
+If the task waits for a message, then it is placed in
+the message queue's task wait queue in either FIFO or task
+priority order. All tasks waiting on a message queue are
+returned an error code when the message queue is deleted.
+
+@ifinfo
+@node Sending a Message, Broadcasting a Message, Receiving a Message, Message Manager Operations
+@end ifinfo
+@subsection Sending a Message
+
+Messages can be sent to a queue with the
+message_queue_send and message_queue_urgent directives. These
+directives work identically when tasks are waiting to receive a
+message. A task is removed from the task waiting queue,
+unblocked, and the message is copied to a waiting task's
+message buffer.
+
+When no tasks are waiting at the queue,
+message_queue_send places the message at the rear of the message
+queue, while message_queue_urgent places the message at the
+front of the queue. The message is copied to a message buffer
+from this message queue's buffer pool and then placed in the
+message queue. Neither directive can successfully send a
+message to a message queue which has a full queue of pending
+messages.
+
+@ifinfo
+@node Broadcasting a Message, Deleting a Message Queue, Sending a Message, Message Manager Operations
+@end ifinfo
+@subsection Broadcasting a Message
+
+The message_queue_broadcast directive sends the same
+message to every task waiting on the specified message queue as
+an atomic operation. The message is copied to each waiting
+task's message buffer and each task is unblocked. The number of
+tasks which were unblocked is returned to the caller.
+
+@ifinfo
+@node Deleting a Message Queue, Message Manager Directives, Broadcasting a Message, Message Manager Operations
+@end ifinfo
+@subsection Deleting a Message Queue
+
+The message_queue_delete directive removes a message
+queue from the system and frees its control block as well as the
+memory associated with this message queue's message buffer pool.
+A message queue can be deleted by any local task that knows the
+message queue's ID. As a result of this directive, all tasks
+blocked waiting to receive a message from the message queue will
+be readied and returned a status code which indicates that the
+message queue was deleted. Any subsequent references to the
+message queue's name and ID are invalid. Any messages waiting
+at the message queue are also deleted and deallocated.
+
+@ifinfo
+@node Message Manager Directives, MESSAGE_QUEUE_CREATE - Create a queue, Deleting a Message Queue, Message Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* MESSAGE_QUEUE_CREATE - Create a queue::
+* MESSAGE_QUEUE_IDENT - Get ID of a queue::
+* MESSAGE_QUEUE_DELETE - Delete a queue::
+* MESSAGE_QUEUE_SEND - Put message at rear of a queue::
+* MESSAGE_QUEUE_URGENT - Put message at front of a queue::
+* MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue::
+* MESSAGE_QUEUE_RECEIVE - Receive message from a queue::
+* MESSAGE_QUEUE_FLUSH - Flush all messages on a queue::
+@end menu
+@end ifinfo
+
+This section details the message manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_CREATE - Create a queue, MESSAGE_QUEUE_IDENT - Get ID of a queue, Message Manager Directives, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_CREATE - Create a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_create(
+ rtems_name name,
+ rtems_unsigned32 count,
+ rtems_unsigned32 max_message_size,
+ rtems_attribute attribute_set,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - queue created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{INVALID_NUMBER} - invalid message count@*
+@code{INVALID_SIZE} - invalid message size@*
+@code{TOO_MANY} - too many queues created@*
+@code{MP_NOT_CONFIGURED} - multiprocessing not configured@*
+@code{TOO_MANY} - too many global objects
+
+@subheading DESCRIPTION:
+
+This directive creates a message queue which resides
+on the local node with the user-defined name specified in name.
+For control and maintenance of the queue, RTEMS allocates and
+initializes a QCB. Memory is allocated from the RTEMS Workspace
+for the specified count of messages, each of max_message_size
+bytes in length. The RTEMS-assigned queue id, returned in id,
+is used to access the message queue.
+
+Specifying PRIORITY in attribute_set causes tasks
+waiting for a message to be serviced according to task priority.
+When FIFO is specified, waiting tasks are serviced in First
+In-First Out order.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The following message queue attribute constants are
+defined by RTEMS:
+
+@itemize @bullet
+@item FIFO - tasks wait by FIFO (default)
+@item PRIORITY - tasks wait by priority
+@item LOCAL - local message queue (default)
+@item GLOBAL - global message queue
+@end itemize
+
+Message queues should not be made global unless
+remote tasks must interact with the created message queue. This
+is to avoid the system overhead incurred by the creation of a
+global message queue. When a global message queue is created,
+the message queue's name and id must be transmitted to every
+node in the system for insertion in the local copy of the global
+object table.
+
+For GLOBAL message queues, the maximum message size
+is effectively limited to the longest message which the MPCI is
+capable of transmitting.
+
+The total number of global objects, including message
+queues, is limited by the maximum_global_objects field in the
+configuration table.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_IDENT - Get ID of a queue, MESSAGE_QUEUE_DELETE - Delete a queue, MESSAGE_QUEUE_CREATE - Create a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_ident(
+ rtems_name name,
+ rtems_unsigned32 node,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - queue identified successfully@*
+@code{INVALID_NAME} - queue name not found@*
+@code{INVALID_NODE} - invalid node id
+
+@subheading DESCRIPTION:
+
+This directive obtains the queue id associated with
+the queue name specified in name. If the queue name is not
+unique, then the queue id will match one of the queues with that
+name. However, this queue id is not guaranteed to correspond to
+the desired queue. The queue id is used with other message
+related directives to access the message queue.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+If node is SEARCH_ALL_NODES, all nodes are searched
+with the local node being searched first. All other nodes are
+searched with the lowest numbered node searched first.
+
+If node is a valid node number which does not
+represent the local node, then only the message queues exported
+by the designated node are searched.
+
+This directive does not generate activity on remote
+nodes. It accesses only the local copy of the global object
+table.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_DELETE - Delete a queue, MESSAGE_QUEUE_SEND - Put message at rear of a queue, MESSAGE_QUEUE_IDENT - Get ID of a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_DELETE - Delete a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - queue deleted successfully@*
+@code{INVALID_ID} - invalid queue id@*
+@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote queue
+
+@subheading DESCRIPTION:
+
+This directive deletes the message queue specified by
+id. As a result of this directive, all tasks blocked waiting to
+receive a message from this queue will be readied and returned a
+status code which indicates that the message queue was deleted.
+If no tasks are waiting, but the queue contains messages, then
+RTEMS returns these message buffers back to the system message
+buffer pool. The QCB for this queue as well as the memory for
+the message buffers is reclaimed by RTEMS.
+
+@subheading NOTES:
+
+The calling task will be preempted if its preemption
+mode is enabled and one or more local tasks with a higher
+priority than the calling task are waiting on the deleted queue.
+The calling task will NOT be preempted if the tasks that are
+waiting are remote tasks.
+
+The calling task does not have to be the task that
+created the queue, although the task and queue must reside on
+the same node.
+
+When the queue is deleted, any messages in the queue
+are returned to the free message buffer pool. Any information
+stored in those messages is lost.
+
+When a global message queue is deleted, the message
+queue id must be transmitted to every node in the system for
+deletion from the local copy of the global object table.
+
+Proxies, used to represent remote tasks, are
+reclaimed when the message queue is deleted.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_SEND - Put message at rear of a queue, MESSAGE_QUEUE_URGENT - Put message at front of a queue, MESSAGE_QUEUE_DELETE - Delete a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_send(
+ rtems_id id,
+ void *buffer,
+ rtems_unsigned32 size
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - message sent successfully@*
+@code{INVALID_ID} - invalid queue id@*
+@code{INVALID_SIZE} - invalid message size@*
+@code{UNSATISFIED} - out of message buffers@*
+@code{TOO_MANY} - queue's limit has been reached
+
+@subheading DESCRIPTION:
+
+This directive sends the message buffer of size bytes
+in length to the queue specified by id. If a task is waiting at
+the queue, then the message is copied to the waiting task's
+buffer and the task is unblocked. If no tasks are waiting at the
+queue, then the message is copied to a message buffer which is
+obtained from this message queue's message buffer pool. The
+message buffer is then placed at the rear of the queue.
+
+@subheading NOTES:
+
+The calling task will be preempted if it has
+preemption enabled and a higher priority task is unblocked as
+the result of this directive.
+
+Sending a message to a global message queue which
+does not reside on the local node will generate a request to the
+remote node to post the message on the specified message queue.
+
+If the task to be unblocked resides on a different
+node from the message queue, then the message is forwarded to
+the appropriate node, the waiting task is unblocked, and the
+proxy used to represent the task is reclaimed.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_URGENT - Put message at front of a queue, MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, MESSAGE_QUEUE_SEND - Put message at rear of a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_urgent(
+ rtems_id id,
+ void *buffer,
+ rtems_unsigned32 size
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - message sent successfully@*
+@code{INVALID_ID} - invalid queue id@*
+@code{INVALID_SIZE} - invalid message size@*
+@code{UNSATISFIED} - out of message buffers@*
+@code{TOO_MANY} - queue's limit has been reached
+
+@subheading DESCRIPTION:
+
+This directive sends the message buffer of size bytes
+in length to the queue specified by id. If a task is waiting on
+the queue, then the message is copied to the task's buffer and
+the task is unblocked. If no tasks are waiting on the queue,
+then the message is copied to a message buffer which is obtained
+from this message queue's message buffer pool. The message
+buffer is then placed at the front of the queue.
+
+@subheading NOTES:
+
+The calling task will be preempted if it has
+preemption enabled and a higher priority task is unblocked as
+the result of this directive.
+
+Sending a message to a global message queue which
+does not reside on the local node will generate a request
+telling the remote node to post the message on the specified
+message queue.
+
+If the task to be unblocked resides on a different
+node from the message queue, then the message is forwarded to
+the appropriate node, the waiting task is unblocked, and the
+proxy used to represent the task is reclaimed.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, MESSAGE_QUEUE_RECEIVE - Receive message from a queue, MESSAGE_QUEUE_URGENT - Put message at front of a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_broadcast(
+ rtems_id id,
+ void *buffer,
+ rtems_unsigned32 size,
+ rtems_unsigned32 *count
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - message broadcasted successfully@*
+@code{INVALID_ID} - invalid queue id@*
+@code{INVALID_SIZE} - invalid message size
+
+@subheading DESCRIPTION:
+
+This directive causes all tasks that are waiting at
+the queue specified by id to be unblocked and sent the message
+contained in buffer. Before a task is unblocked, the message
+buffer of size byes in length is copied to that task's message
+buffer. The number of tasks that were unblocked is returned in
+count.
+
+@subheading NOTES:
+
+The calling task will be preempted if it has
+preemption enabled and a higher priority task is unblocked as
+the result of this directive.
+
+The execution time of this directive is directly
+related to the number of tasks waiting on the message queue,
+although it is more efficient than the equivalent number of
+invocations of message_queue_send.
+
+Broadcasting a message to a global message queue
+which does not reside on the local node will generate a request
+telling the remote node to broadcast the message to the
+specified message queue.
+
+When a task is unblocked which resides on a different
+node from the message queue, a copy of the message is forwarded
+to the appropriate node, the waiting task is unblocked, and the
+proxy used to represent the task is reclaimed.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_RECEIVE - Receive message from a queue, MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_receive(
+ rtems_id id,
+ void *buffer,
+ rtems_unsigned32 *size,
+ rtems_unsigned32 option_set,
+ rtems_interval timeout
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - message received successfully@*
+@code{INVALID_ID} - invalid queue id@*
+@code{UNSATISFIED} - queue is empty@*
+@code{TIMEOUT} - timed out waiting for message@*
+@code{OBJECT_WAS_DELETED} - queue deleted while waiting
+
+@subheading DESCRIPTION:
+
+This directive receives a message from the message
+queue specified in id. The WAIT and NO_WAIT options of the
+options parameter allow the calling task to specify whether to
+wait for a message to become available or return immediately.
+For either option, if there is at least one message in the
+queue, then it is copied to buffer, size is set to return the
+length of the message in bytes, and this directive returns
+immediately with a successful return code.
+
+If the calling task chooses to return immediately and
+the queue is empty, then a status code indicating this condition
+is returned. If the calling task chooses to wait at the message
+queue and the queue is empty, then the calling task is placed on
+the message wait queue and blocked. If the queue was created
+with the PRIORITY option specified, then the calling task is
+inserted into the wait queue according to its priority. But, if
+the queue was created with the FIFO option specified, then the
+calling task is placed at the rear of the wait queue.
+
+A task choosing to wait at the queue can optionally
+specify a timeout value in the timeout parameter. The timeout
+parameter specifies the maximum interval to wait before the
+calling task desires to be unblocked. If it is set to
+NO_TIMEOUT, then the calling task will wait forever.
+
+@subheading NOTES:
+
+The following message receive option constants are
+defined by RTEMS:
+
+@itemize @bullet
+@item WAIT - task will wait for a message (default)
+@item NO_WAIT - task should not wait
+@end itemize
+
+
+Receiving a message from a global message queue which
+does not reside on the local node will generate a request to the
+remote node to obtain a message from the specified message
+queue. If no message is available and WAIT was specified, then
+the task must be blocked until a message is posted. A proxy is
+allocated on the remote node to represent the task until the
+message is posted.
+
+@page
+@ifinfo
+@node MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, Event Manager, MESSAGE_QUEUE_RECEIVE - Receive message from a queue, Message Manager Directives
+@end ifinfo
+@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_message_queue_flush(
+ rtems_id id,
+ rtems_unsigned32 *count
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - message received successfully@*
+@code{INVALID_ID} - invalid queue id
+
+@subheading DESCRIPTION:
+
+This directive removes all pending messages from the
+specified queue id. The number of messages removed is returned
+in count. If no messages are present on the queue, count is set
+to zero.
+
+@subheading NOTES:
+
+Flushing all messages on a global message queue which
+does not reside on the local node will generate a request to the
+remote node to actually flush the specified message queue.
+
+
+
diff --git a/doc/user/overview.t b/doc/user/overview.t
new file mode 100644
index 0000000000..a1c4d4ef01
--- /dev/null
+++ b/doc/user/overview.t
@@ -0,0 +1,578 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@c
+@c This chapter is missing the following figures:
+@c
+@c Figure 1-1 RTEMS Application Architecture
+@c Figure 1-2 RTEMS Internal Architecture
+@c
+
+@ifinfo
+@node Overview, Overview Introduction, Preface, Top
+@end ifinfo
+@chapter Overview
+@ifinfo
+@menu
+* Overview Introduction::
+* Overview Real-time Application Systems::
+* Overview Real-time Executive::
+* Overview RTEMS Application Architecture::
+* Overview RTEMS Internal Architecture::
+* Overview User Customization and Extensibility::
+* Overview Portability::
+* Overview Memory Requirements::
+* Overview Audience::
+* Overview Conventions::
+* Overview Manual Organization::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Overview Introduction, Overview Real-time Application Systems, Overview, Overview
+@end ifinfo
+@section Introduction
+
+RTEMS, Real-Time Executive for Multiprocessor Systems, is a
+real-time executive (kernel) which provides a high performance
+environment for embedded military applications including the
+following features:
+
+@itemize @bullet
+@item multitasking capabilities
+@item homogeneous and heterogeneous multiprocessor systems
+@item event-driven, priority-based, preemptive scheduling
+@item optional rate monotonic scheduling
+@item intertask communication and synchronization
+@item priority inheritance
+@item responsive interrupt management
+@item dynamic memory allocation
+@item high level of user configurability
+@end itemize
+
+This manual describes the usage of RTEMS for
+applications written in the C programming language. Those
+implementation details that are processor dependent are provided
+in the C Applications Supplement documents. A supplement
+document which addresses specific architectural issues that
+affect RTEMS is provided for each processor type that is
+supported.
+
+@ifinfo
+@node Overview Real-time Application Systems, Overview Real-time Executive, Overview Introduction, Overview
+@end ifinfo
+@section Real-time Application Systems
+
+Real-time application systems are a special class of
+computer applications. They have a complex set of
+characteristics that distinguish them from other software
+problems. Generally, they must adhere to more rigorous
+requirements. The correctness of the system depends not only on
+the results of computations, but also on the time at which the
+results are produced. The most important and complex
+characteristic of real-time application systems is that they
+must receive and respond to a set of external stimuli within
+rigid and critical time constraints referred to as deadlines.
+Systems can be buried by an avalanche of interdependent,
+asynchronous or cyclical event streams.
+
+Deadlines can be further characterized as either hard
+or soft based upon the value of the results when produced after
+the deadline has passed. A deadline is hard if the results have
+no value or if their use will result in a catastrophic event.
+In contrast, results which are produced after a soft deadline
+may have some value.
+
+Another distinguishing requirement of real-time
+application systems is the ability to coordinate or manage a
+large number of concurrent activities. Since software is a
+synchronous entity, this presents special problems. One
+instruction follows another in a repeating synchronous cycle.
+Even though mechanisms have been developed to allow for the
+processing of external asynchronous events, the software design
+efforts required to process and manage these events and tasks
+are growing more complicated.
+
+The design process is complicated further by
+spreading this activity over a set of processors instead of a
+single processor. The challenges associated with designing and
+building real-time application systems become very complex when
+multiple processors are involved. New requirements such as
+interprocessor communication channels and global resources that
+must be shared between competing processors are introduced. The
+ramifications of multiple processors complicate each and every
+characteristic of a real-time system.
+
+@ifinfo
+@node Overview Real-time Executive, Overview RTEMS Application Architecture, Overview Real-time Application Systems, Overview
+@end ifinfo
+@section Real-time Executive
+
+Fortunately, real-time operating systems or real-time
+executives serve as a cornerstone on which to build the
+application system. A real-time multitasking executive allows
+an application to be cast into a set of logical, autonomous
+processes or tasks which become quite manageable. Each task is
+internally synchronous, but different tasks execute
+independently, resulting in an asynchronous processing stream.
+Tasks can be dynamically paused for many reasons resulting in a
+different task being allowed to execute for a period of time.
+The executive also provides an interface to other system
+components such as interrupt handlers and device drivers.
+System components may request the executive to allocate and
+coordinate resources, and to wait for and trigger synchronizing
+conditions. The executive system calls effectively extend the
+CPU instruction set to support efficient multitasking. By
+causing tasks to travel through well-defined state transitions,
+system calls permit an application to demand-switch between
+tasks in response to real-time events.
+
+By proper grouping of responses to stimuli into
+separate tasks, a system can now asynchronously switch between
+independent streams of execution, directly responding to
+external stimuli as they occur. This allows the system design
+to meet critical performance specifications which are typically
+measured by guaranteed response time and transaction throughput.
+The multiprocessor extensions of RTEMS provide the features
+necessary to manage the extra requirements introduced by a
+system distributed across several processors. It removes the
+physical barriers of processor boundaries from the world of the
+system designer, enabling more critical aspects of the system to
+receive the required attention. Such a system, based on an
+efficient real-time, multiprocessor executive, is a more
+realistic model of the outside world or environment for which it
+is designed. As a result, the system will always be more
+logical, efficient, and reliable.
+
+By using the directives provided by RTEMS, the
+real-time applications developer is freed from the problem of
+controlling and synchronizing multiple tasks and processors. In
+addition, one need not develop, test, debug, and document
+routines to manage memory, pass messages, or provide mutual
+exclusion. The developer is then able to concentrate solely on
+the application. By using standard software components, the
+time and cost required to develop sophisticated real-time
+applications is significantly reduced.
+
+@ifinfo
+@node Overview RTEMS Application Architecture, Overview RTEMS Internal Architecture, Overview Real-time Executive, Overview
+@end ifinfo
+@section RTEMS Application Architecture
+
+One important design goal of RTEMS was to provide a
+bridge between two critical layers of typical real-time systems.
+As shown in the following figure, RTEMS serves as a buffer between the
+project dependent application code and the target hardware.
+Most hardware dependencies for real-time applications can be
+localized to the low level device drivers. The RTEMS I/O
+interface manager provides an efficient tool for incorporating
+these hardware dependencies into the system while simultaneously
+providing a general mechanism to the application code that
+accesses them. A well designed real-time system can benefit
+from this architecture by building a rich library of standard
+application components which can be used repeatedly in other
+real-time projects.
+
+@ifset use-ascii
+@example
+@group
+ +-----------------------------------------------------------+
+ | Application Dependent Software |
+ | +----------------------------------------+ |
+ | | Standard Application Components | |
+ | | +-------------+---+ |
+ | +---+-----------+ | | |
+ | | Board Support | | RTEMS | |
+ | | Package | | | |
+ +----+---------------+--------------+-----------------+-----|
+ | Target Hardware |
+ +-----------------------------------------------------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+@tex
+\centerline{\vbox{\offinterlineskip\halign{
+\vrule#&
+\hbox to 0.50in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.50in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.50in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.50in{\enskip\hfil#\hfil}&
+\vrule#\cr
+\multispan{17}\hrulefill\cr
+% to force all columns to desired width
+& \enskip && \enskip && \enskip && \enskip &&
+ \enskip && \enskip &&\enskip &&\enskip &\cr
+% For debugging columns
+%& \enskip 0&& \enskip 1&& \enskip 2&& \enskip 3&&
+% \enskip 4&& \enskip 5&&\enskip 6&&\enskip 7&\cr
+\strut&\multispan{15}&\cr
+&\multispan{15}\hfil Application Dependent Software\hfil&\cr
+\strut&\multispan{15}&\cr
+&\multispan{2}&&\multispan{8}\hrulefill &\multispan{2}&\cr
+\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr
+&\multispan{2}&&&\multispan{7}\hfil Standard Application Components\hfil&
+ &\multispan{2}&&\cr
+\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr
+&&\multispan{5}\hrulefill&&\multispan{7}\hrulefill&&\cr
+\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr
+&&&\multispan{3}\hfil Device\hfil&&&&\multispan{5}\hfil RTEMS\hfil&&&\cr
+&&&\multispan{3}\hfil Drivers\hfil&&&&\multispan{5}&&&\cr
+\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr
+\multispan{17}\hrulefill\cr
+\strut&\multispan{15}&\cr
+&\multispan{15}\hfil Target Hardware\hfil&\cr
+\strut&\multispan{15}&\cr
+\multispan{17}\hrulefill\cr
+}}\hfil}
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<IMG SRC="rtemsarc.gif" WIDTH=500 HEIGHT=300 ALT="RTEMS Application Architecture">
+@end html
+@end ifset
+
+@ifinfo
+@node Overview RTEMS Internal Architecture, Overview User Customization and Extensibility, Overview RTEMS Application Architecture, Overview
+@end ifinfo
+@section RTEMS Internal Architecture
+
+RTEMS can be viewed as a set of layered components that work in
+harmony to provide a set of services to a real-time application
+system. The executive interface presented to the application is
+formed by grouping directives into logical sets called resource managers.
+Functions utilized by multiple managers such as scheduling,
+dispatching, and object management are provided in the executive
+core. The executive core depends on a small set of CPU dependent routines.
+Together these components provide a powerful run time
+environment that promotes the development of efficient real-time
+application systems. The following figure illustrates this organization:
+
+@ifset use-ascii
+@example
+@group
+ +-----------------------------------------------+
+ | RTEMS Executive Interface |
+ +-----------------------------------------------+
+ | RTEMS Core |
+ +-----------------------------------------------+
+ | CPU Dependent Code |
+ +-----------------------------------------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@c for now use the ascii version
+@example
+@group
+ +-----------------------------------------------+
+ | RTEMS Executive Interface |
+ +-----------------------------------------------+
+ | RTEMS Core |
+ +-----------------------------------------------+
+ | CPU Dependent Code |
+ +-----------------------------------------------+
+@end group
+@end example
+@tex
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<IMG SRC="rtemspie.gif" WIDTH=500 HEIGHT=300 ALT="RTEMS Architecture">
+@end html
+@end ifset
+Subsequent chapters present a detailed description of the capabilities
+provided by each of the following RTEMS managers:
+
+@itemize @bullet
+@item initialization
+@item task
+@item interrupt
+@item clock
+@item timer
+@item semaphore
+@item message
+@item event
+@item signal
+@item partition
+@item region
+@item dual ported memory
+@item I/O
+@item fatal error
+@item rate monotonic
+@item user extensions
+@item multiprocessing
+@end itemize
+
+@ifinfo
+@node Overview User Customization and Extensibility, Overview Portability, Overview RTEMS Internal Architecture, Overview
+@end ifinfo
+@section User Customization and Extensibility
+
+As thirty-two bit microprocessors have decreased in
+cost, they have become increasingly common in a variety of
+embedded systems. A wide range of custom and general-purpose
+processor boards are based on various thirty-two bit processors.
+RTEMS was designed to make no assumptions concerning the
+characteristics of individual microprocessor families or of
+specific support hardware. In addition, RTEMS allows the system
+developer a high degree of freedom in customizing and extending
+its features.
+
+RTEMS assumes the existence of a supported
+microprocessor and sufficient memory for both RTEMS and the
+real-time application. Board dependent components such as
+clocks, interrupt controllers, or I/O devices can be easily
+integrated with RTEMS. The customization and extensibility
+features allow RTEMS to efficiently support as many environments
+as possible.
+
+@ifinfo
+@node Overview Portability, Overview Memory Requirements, Overview User Customization and Extensibility, Overview
+@end ifinfo
+@section Portability
+
+The issue of portability was the major factor in the
+creation of RTEMS. Since RTEMS is designed to isolate the
+hardware dependencies in the specific board support packages,
+the real-time application should be easily ported to any other
+processor. The use of RTEMS allows the development of real-time
+applications which can be completely independent of a particular
+microprocessor architecture.
+
+@ifinfo
+@node Overview Memory Requirements, Overview Audience, Overview Portability, Overview
+@end ifinfo
+@section Memory Requirements
+
+Since memory is a critical resource in many real-time
+embedded systems, RTEMS was specifically designed to allow
+unused managers to be excluded from the run-time environment.
+This allows the application designer the flexibility to tailor
+RTEMS to most efficiently meet system requirements while still
+satisfying even the most stringent memory constraints. As a
+result, the size of the RTEMS executive is application
+dependent. A worksheet is provided in the Memory Requirements
+chapter of the C Applications Supplement document for a specific
+target processor. The worksheet is used to calculate the memory
+requirements of a custom RTEMS run-time environment. The
+following managers may be optionally excluded:
+
+@itemize @bullet
+@item clock
+@item timer
+@item semaphore
+@item message
+@item event
+@item signal
+@item partition
+@item region
+@item dual ported memory
+@item I/O
+@item rate monotonic
+@item fatal error
+@item multiprocessing
+@end itemize
+
+RTEMS utilizes memory for both code and data space.
+Although RTEMS' data space must be in RAM, its code space can be
+located in either ROM or RAM.
+
+@ifinfo
+@node Overview Audience, Overview Conventions, Overview Memory Requirements, Overview
+@end ifinfo
+@section Audience
+
+This manual was written for experienced real-time
+software developers. Although some background is provided, it
+is assumed that the reader is familiar with the concepts of task
+management as well as intertask communication and
+synchronization. Since directives, user related data
+structures, and examples are presented in C, a basic
+understanding of the C programming language is required to fully
+understand the material presented. However, because of the
+similarity of the Ada and C RTEMS implementations, users will
+find that the use and behavior of the two implementations is
+very similar. A working knowledge of the target processor is
+helpful in understanding some of RTEMS' features. A thorough
+understanding of the executive cannot be obtained without
+studying the entire manual because many of RTEMS' concepts and
+features are interrelated. Experienced RTEMS users will find
+that the manual organization facilitates its use as a reference
+document.
+
+@ifinfo
+@node Overview Conventions, Overview Manual Organization, Overview Audience, Overview
+@end ifinfo
+@section Conventions
+
+The following conventions are used in this manual:
+
+@itemize @bullet
+@item Significant words or phrases as well as all directive
+names are printed in bold type.
+
+@item Items in bold capital letters are constants defined by
+RTEMS. Each language interface provided by RTEMS includes a
+file containing the standard set of constants, data types, and
+structure definitions which can be incorporated into the user
+application.
+
+@item A number of type definitions are provided by RTEMS and
+can be found in rtems.h.
+
+@item The characters "0x" preceding a number indicates that
+the number is in hexadecimal format. Any other numbers are
+assumed to be in decimal format.
+@end itemize
+
+@ifinfo
+@node Overview Manual Organization, Key Concepts, Overview Conventions, Overview
+@end ifinfo
+@section Manual Organization
+
+This first chapter has presented the introductory and
+background material for the RTEMS executive. The remaining
+chapters of this manual present a detailed description of RTEMS
+and the environment, including run time behavior, it creates for
+the user.
+
+A chapter is dedicated to each manager and provides a
+detailed discussion of each RTEMS manager and the directives
+which it provides. The presentation format for each directive
+includes the following sections:
+
+@itemize @bullet
+@item Calling sequence
+@item Directive status codes
+@item Description
+@item Notes
+@end itemize
+
+The following provides an overview of the remainder
+of this manual:
+
+@table @asis
+@item Chapter 2
+Key Concepts: presents an
+introduction to the ideas which are common across multiple RTEMS
+managers.
+
+@item Chapter 3:
+Initialization Manager: describes the functionality and directives
+provided by the Initialization Manager.
+
+@item Chapter 4:
+Task Manager: describes the functionality and directives provided
+by the Task Manager.
+
+@item Chapter 5:
+Interrupt Manager: describes the functionality and directives
+provided by the Interrupt Manager.
+
+@item Chapter 6:
+Clock Manager: describes the functionality and directives
+provided by the Clock Manager.
+
+@item Chapter 7
+Timer Manager: describes the functionality and directives provided
+by the Timer Manager.
+
+@item Chapter 8:
+Semaphore Manager: describes the functionality and directives
+provided by the Semaphore Manager.
+
+@item Chapter 9:
+Message Manager: describes the functionality and directives
+provided by the Message Manager.
+
+@item Chapter 10:
+Event Manager: describes the
+functionality and directives provided by the Event Manager.
+
+@item Chapter 11:
+Signal Manager: describes the
+functionality and directives provided by the Signal Manager.
+
+@item Chapter 12:
+Partition Manager: describes the
+functionality and directives provided by the Partition Manager.
+
+@item Chapter 13:
+Region Manager: describes the
+functionality and directives provided by the Region Manager.
+
+@item Chapter 14:
+Dual-Ported Memory Manager: describes
+the functionality and directives provided by the Dual-Ported
+Memory Manager.
+
+@item Chapter 15:
+I/O Manager: describes the
+functionality and directives provided by the I/O Manager.
+
+@item Chapter 16:
+Fatal Error Manager: describes the functionality and directives
+provided by the Fatal Error Manager.
+
+@item Chapter 17:
+Scheduling Concepts: details the RTEMS scheduling algorithm and
+task state transitions.
+
+@item Chapter 18:
+Rate Monotonic Manager: describes the functionality and directives
+provided by the Rate Monotonic Manager.
+
+@item Chapter 19:
+Board Support Packages: defines the
+functionality required of user-supplied board support packages.
+
+@item Chapter 20:
+User Extensions: shows the user how to
+extend RTEMS to incorporate custom features.
+
+@item Chapter 21:
+Configuring a System: details the process by which one tailors RTEMS
+for a particular single-processor or multiprocessor application.
+
+@item Chapter 22:
+Multiprocessing Manager: presents a
+conceptual overview of the multiprocessing capabilities provided
+by RTEMS as well as describing the Multiprocessing
+Communications Interface Layer and Multiprocessing Manager
+directives.
+
+@item Chapter 23:
+Directive Status Codes: provides a definition of each of the
+directive status codes referenced in this manual.
+
+@item Chapter 24:
+Example Application: provides a template for simple RTEMS applications.
+
+@item Chapter 25:
+Glossary: defines terms used throughout this manual.
+
+@end table
+
+
diff --git a/doc/user/part.t b/doc/user/part.t
new file mode 100644
index 0000000000..302f426497
--- /dev/null
+++ b/doc/user/part.t
@@ -0,0 +1,423 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Partition Manager, Partition Manager Introduction, SIGNAL_SEND - Send signal set to a task, Top
+@end ifinfo
+@chapter Partition Manager
+@ifinfo
+@menu
+* Partition Manager Introduction::
+* Partition Manager Background::
+* Partition Manager Operations::
+* Partition Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Partition Manager Introduction, Partition Manager Background, Partition Manager, Partition Manager
+@end ifinfo
+@section Introduction
+
+The partition manager provides facilities to
+dynamically allocate memory in fixed-size units. The directives
+provided by the partition manager are:
+
+@itemize @bullet
+@item @code{partition_create} - Create a partition
+@item @code{partition_ident} - Get ID of a partition
+@item @code{partition_delete} - Delete a partition
+@item @code{partition_get_buffer} - Get buffer from a partition
+@item @code{partition_return_buffer} - Return buffer to a partition
+@end itemize
+
+@ifinfo
+@node Partition Manager Background, Partition Manager Definitions, Partition Manager Introduction, Partition Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Partition Manager Definitions::
+* Building a Partition's Attribute Set::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Partition Manager Definitions, Building a Partition's Attribute Set, Partition Manager Background, Partition Manager Background
+@end ifinfo
+@subsection Partition Manager Definitions
+
+A partition is a physically contiguous memory area
+divided into fixed-size buffers that can be dynamically
+allocated and deallocated.
+
+Partitions are managed and maintained as a list of
+buffers. Buffers are obtained from the front of the partition's
+free buffer chain and returned to the rear of the same chain.
+When a buffer is on the free buffer chain, RTEMS uses eight
+bytes of each buffer as the free buffer chain. When a buffer is
+allocated, the entire buffer is available for application use.
+Therefore, modifying memory that is outside of an allocated
+buffer could destroy the free buffer chain or the contents of an
+adjacent allocated buffer.
+
+@ifinfo
+@node Building a Partition's Attribute Set, Partition Manager Operations, Partition Manager Definitions, Partition Manager Background
+@end ifinfo
+@subsection Building a Partition's Attribute Set
+
+In general, an attribute set is built by a bitwise OR
+of the desired attribute components. The set of valid partition
+attributes is provided in the following table:
+
+@itemize @bullet
+@item LOCAL - local task (default)
+@item GLOBAL - global task
+@end itemize
+
+
+
+Attribute values are specifically designed to be
+mutually exclusive, therefore bitwise OR and addition operations
+are equivalent as long as each attribute appears exactly once in
+the component list. An attribute listed as a default is not
+required to appear in the attribute list, although it is a good
+programming practice to specify default attributes. If all
+defaults are desired, the attribute DEFAULT_ATTRIBUTES should be
+specified on this call. The attribute_set parameter should be
+GLOBAL to indicate that the partition is to be known globally.
+
+@ifinfo
+@node Partition Manager Operations, Creating a Partition, Building a Partition's Attribute Set, Partition Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Partition::
+* Obtaining Partition IDs::
+* Acquiring a Buffer::
+* Releasing a Buffer::
+* Deleting a Partition::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Partition, Obtaining Partition IDs, Partition Manager Operations, Partition Manager Operations
+@end ifinfo
+@subsection Creating a Partition
+
+The partition_create directive creates a partition
+with a user-specified name. The partition's name, starting
+address, length and buffer size are all specified to the
+partition_create directive. RTEMS allocates a Partition Control
+Block (PTCB) from the PTCB free list. This data structure is
+used by RTEMS to manage the newly created partition. The number
+of buffers in the partition is calculated based upon the
+specified partition length and buffer size, and returned to the
+calling task along with a unique partition ID.
+
+@ifinfo
+@node Obtaining Partition IDs, Acquiring a Buffer, Creating a Partition, Partition Manager Operations
+@end ifinfo
+@subsection Obtaining Partition IDs
+
+When a partition is created, RTEMS generates a unique
+partition ID and assigned it to the created partition until it
+is deleted. The partition ID may be obtained by either of two
+methods. First, as the result of an invocation of the
+partition_create directive, the partition ID is stored in a user
+provided location. Second, the partition ID may be obtained
+later using the partition_ident directive. The partition ID is
+used by other partition manager directives to access this
+partition.
+
+@ifinfo
+@node Acquiring a Buffer, Releasing a Buffer, Obtaining Partition IDs, Partition Manager Operations
+@end ifinfo
+@subsection Acquiring a Buffer
+
+A buffer can be obtained by calling the
+partition_get_buffer directive. If a buffer is available, then
+it is returned immediately with a successful return code.
+Otherwise, an unsuccessful return code is returned immediately
+to the caller. Tasks cannot block to wait for a buffer to
+become available.
+
+@ifinfo
+@node Releasing a Buffer, Deleting a Partition, Acquiring a Buffer, Partition Manager Operations
+@end ifinfo
+@subsection Releasing a Buffer
+
+Buffers are returned to a partition's free buffer
+chain with the partition_return_buffer directive. This
+directive returns an error status code if the returned buffer
+was not previously allocated from this partition.
+
+@ifinfo
+@node Deleting a Partition, Partition Manager Directives, Releasing a Buffer, Partition Manager Operations
+@end ifinfo
+@subsection Deleting a Partition
+
+The partition_delete directive allows a partition to
+be removed and returned to RTEMS. When a partition is deleted,
+the PTCB for that partition is returned to the PTCB free list.
+A partition with buffers still allocated cannot be deleted. Any
+task attempting to do so will be returned an error status code.
+
+@ifinfo
+@node Partition Manager Directives, PARTITION_CREATE - Create a partition, Deleting a Partition, Partition Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* PARTITION_CREATE - Create a partition::
+* PARTITION_IDENT - Get ID of a partition::
+* PARTITION_DELETE - Delete a partition::
+* PARTITION_GET_BUFFER - Get buffer from a partition::
+* PARTITION_RETURN_BUFFER - Return buffer to a partition::
+@end menu
+@end ifinfo
+
+This section details the partition manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node PARTITION_CREATE - Create a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives, Partition Manager Directives
+@end ifinfo
+@subsection PARTITION_CREATE - Create a partition
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_partition_create(
+ rtems_name name,
+ void *starting_address,
+ rtems_unsigned32 length,
+ rtems_unsigned32 buffer_size,
+ rtems_attribute attribute_set,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - partition created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{TOO_MANY} - too many partitions created@*
+@code{INVALID_ADDRESS} - address not on four byte boundary@*
+@code{INVALID_SIZE} - length or buffer size is 0@*
+@code{INVALID_SIZE} - length is less than the buffer size@*
+@code{INVALID_SIZE} - buffer size not a multiple of 4@*
+@code{MP_NOT_CONFIGURED} - multiprocessing not configured@*
+@code{TOO_MANY} - too many global objects
+
+@subheading DESCRIPTION:
+
+This directive creates a partition of fixed size
+buffers from a physically contiguous memory space which starts
+at starting_address and is length bytes in size. Each allocated
+buffer is to be of buffer_length in bytes. The assigned
+partition id is returned in id. This partition id is used to
+access the partition with other partition related directives.
+For control and maintenance of the partition, RTEMS allocates a
+PTCB from the local PTCB free pool and initializes it.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The starting_address and buffer_size parameters must
+be multiples of four.
+
+Memory from the partition is not used by RTEMS to
+store the Partition Control Block.
+
+The following partition attribute constants are
+defined by RTEMS:
+
+@itemize @bullet
+@item LOCAL - local task (default)
+@item GLOBAL - global task
+@end itemize
+
+The PTCB for a global partition is allocated on the
+local node. The memory space used for the partition must reside
+in shared memory. Partitions should not be made global unless
+remote tasks must interact with the partition. This is to avoid
+the overhead incurred by the creation of a global partition.
+When a global partition is created, the partition's name and id
+must be transmitted to every node in the system for insertion in
+the local copy of the global object table.
+
+The total number of global objects, including
+partitions, is limited by the maximum_global_objects field in
+the Configuration Table.
+
+@page
+@ifinfo
+@node PARTITION_IDENT - Get ID of a partition, PARTITION_DELETE - Delete a partition, PARTITION_CREATE - Create a partition, Partition Manager Directives
+@end ifinfo
+@subsection PARTITION_IDENT - Get ID of a partition
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_partition_ident(
+ rtems_name name,
+ rtems_unsigned32 node,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - partition identified successfully@*
+@code{INVALID_NAME} - partition name not found@*
+@code{INVALID_NODE} - invalid node id
+
+@subheading DESCRIPTION:
+
+This directive obtains the partition id associated
+with the partition name. If the partition name is not unique,
+then the partition id will match one of the partitions with that
+name. However, this partition id is not guaranteed to
+correspond to the desired partition. The partition id is used
+with other partition related directives to access the partition.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+If node is SEARCH_ALL_NODES, all nodes are searched
+with the local node being searched first. All other nodes are
+searched with the lowest numbered node searched first.
+
+If node is a valid node number which does not
+represent the local node, then only the partitions exported by
+the designated node are searched.
+
+This directive does not generate activity on remote
+nodes. It accesses only the local copy of the global object
+table.
+
+@page
+@ifinfo
+@node PARTITION_DELETE - Delete a partition, PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives
+@end ifinfo
+@subsection PARTITION_DELETE - Delete a partition
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_partition_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - partition deleted successfully@*
+@code{INVALID_ID} - invalid partition id@*
+@code{RESOURCE_IN_USE} - buffers still in use@*
+@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote partition
+
+@subheading DESCRIPTION:
+
+This directive deletes the partition specified by id.
+The partition cannot be deleted if any of its buffers are still
+allocated. The PTCB for the deleted partition is reclaimed by
+RTEMS.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The calling task does not have to be the task that
+created the partition. Any local task that knows the partition
+id can delete the partition.
+
+When a global partition is deleted, the partition id
+must be transmitted to every node in the system for deletion
+from the local copy of the global object table.
+
+The partition must reside on the local node, even if
+the partition was created with the GLOBAL option.
+
+@page
+@ifinfo
+@node PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_RETURN_BUFFER - Return buffer to a partition, PARTITION_DELETE - Delete a partition, Partition Manager Directives
+@end ifinfo
+@subsection PARTITION_GET_BUFFER - Get buffer from a partition
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_partition_get_buffer(
+ rtems_id id,
+ void **buffer
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - buffer obtained successfully@*
+@code{INVALID_ID} - invalid partition id@*
+@code{UNSATISFIED} - all buffers are allocated
+
+@subheading DESCRIPTION:
+
+This directive allows a buffer to be obtained from
+the partition specified in id. The address of the allocated
+buffer is returned in buffer.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+All buffers begin on a four byte boundary.
+
+A task cannot wait on a buffer to become available.
+
+Getting a buffer from a global partition which does
+not reside on the local node will generate a request telling the
+remote node to allocate a buffer from the specified partition.
+
+@page
+@ifinfo
+@node PARTITION_RETURN_BUFFER - Return buffer to a partition, Region Manager, PARTITION_GET_BUFFER - Get buffer from a partition, Partition Manager Directives
+@end ifinfo
+@subsection PARTITION_RETURN_BUFFER - Return buffer to a partition
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_partition_return_buffer(
+ rtems_id id,
+ void *buffer
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - buffer returned successfully@*
+@code{INVALID_ID} - invalid partition id@*
+@code{INVALID_ADDRESS} - buffer address not in partition
+
+@subheading DESCRIPTION:
+
+This directive returns the buffer specified by buffer
+to the partition specified by id.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+Returning a buffer to a global partition which does
+not reside on the local node will generate a request telling the
+remote node to return the buffer to the specified partition.
diff --git a/doc/user/preface.texi b/doc/user/preface.texi
new file mode 100644
index 0000000000..c9154192a6
--- /dev/null
+++ b/doc/user/preface.texi
@@ -0,0 +1,173 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Preface, Overview, Top, Top
+@end ifinfo
+@unnumbered Preface
+
+In recent years, the cost required to develop a
+software product has increased significantly while the target
+hardware costs have decreased. Now a larger portion of money is
+expended in developing, using, and maintaining software. The
+trend in computing costs is the complete dominance of software
+over hardware costs. Because of this, it is necessary that
+formal disciplines be established to increase the probability
+that software is characterized by a high degree of correctness,
+maintainability, and portability. In addition, these
+disciplines must promote practices that aid in the consistent
+and orderly development of a software system within schedule and
+budgetary constraints. To be effective, these disciplines must
+adopt standards which channel individual software efforts toward
+a common goal.
+
+The push for standards in the software development
+field has been met with various degrees of success. The
+Microprocessor Operating Systems Interfaces (MOSI) effort has
+experienced only limited success. As popular as the UNIX
+operating system has grown, the attempt to develop a standard
+interface definition to allow portable application development
+has only recently begun to produce the results needed in this
+area. Unfortunately, very little effort has been expended to
+provide standards addressing the needs of the real-time
+community. Several organizations have addressed this need
+during recent years.
+
+The Real Time Executive Interface Definition (RTEID)
+was developed by Motorola with technical input from Software
+Components Group. RTEID was adopted by the VMEbus International
+Trade Association (VITA) as a baseline draft for their proposed
+standard multiprocessor, real-time executive interface, Open
+Real-Time Kernel Interface Definition (ORKID). These two groups
+are currently working together with the IEEE P1003.4 committee
+to insure that the functionality of their proposed standards is
+adopted as the real-time extensions to POSIX.
+
+This emerging standard defines an interface for the
+development of real-time software to ease the writing of
+real-time application programs that are directly portable across
+multiple real-time executive implementations. This interface
+includes both the source code interfaces and run-time behavior
+as seen by a real-time application. It does not include the
+details of how a kernel implements these functions. The
+standard's goal is to serve as a complete definition of external
+interfaces so that application code that conforms to these
+interfaces will execute properly in all real-time executive
+environments. With the use of a standards compliant executive,
+routines that acquire memory blocks, create and manage message
+queues, establish and use semaphores, and send and receive
+signals need not be redeveloped for a different real-time
+environment as long as the new environment is compliant with the
+standard. Software developers need only concentrate on the
+hardware dependencies of the real-time system. Furthermore,
+most hardware dependencies for real-time applications can be
+localized to the device drivers.
+
+A compliant executive provides simple and flexible
+real-time multiprocessing. It easily lends itself to both
+tightly-coupled and loosely-coupled configurations (depending on
+the system hardware configuration). Objects such as tasks,
+queues, events, signals, semaphores, and memory blocks can be
+designated as global objects and accessed by any task regardless
+of which processor the object and the accessing task reside.
+
+The acceptance of a standard for real-time executives
+will produce the same advantages enjoyed from the push for UNIX
+standardization by AT&T's System V Interface Definition and
+IEEE's POSIX efforts. A compliant multiprocessing executive
+will allow close coupling between UNIX systems and real-time
+executives to provide the many benefits of the UNIX development
+environment to be applied to real-time software development.
+Together they provide the necessary laboratory environment to
+implement real-time, distributed, embedded systems using a wide
+variety of computer architectures.
+
+A study was completed in 1988, within the Research,
+Development, and Engineering Center, U.S. Army Missile Command,
+which compared the various aspects of the Ada programming
+language as they related to the application of Ada code in
+distributed and/or multiple processing systems. Several
+critical conclusions were derived from the study. These
+conclusions have a major impact on the way the Army develops
+application software for embedded applications. These impacts
+apply to both in-house software development and contractor
+developed software.
+
+A conclusion of the analysis, which has been
+previously recognized by other agencies attempting to utilize
+Ada in a distributed or multiprocessing environment, is that the
+Ada programming language does not adequately support
+multiprocessing. Ada does provide a mechanism for
+multi-tasking, however, this capability exists only for a single
+processor system. The language also does not have inherent
+capabilities to access global named variables, flags or program
+code. These critical features are essential in order for data
+to be shared between processors. However, these drawbacks do
+have workarounds which are sometimes awkward and defeat the
+intent of software maintainability and portability goals.
+
+Another conclusion drawn from the analysis, was that
+the run time executives being delivered with the Ada compilers
+were too slow and inefficient to be used in modern missile
+systems. A run time executive is the core part of the run time
+system code, or operating system code, that controls task
+scheduling, input/output management and memory management.
+Traditionally, whenever efficient executive (also known as
+kernel) code was required by the application, the user developed
+in-house software. This software was usually written in
+assembly language for optimization.
+
+Because of this shortcoming in the Ada programming
+language, software developers in research and development and
+contractors for project managed systems, are mandated by
+technology to purchase and utilize off-the-shelf third party
+kernel code. The contractor, and eventually the Government,
+must pay a licensing fee for every copy of the kernel code used
+in an embedded system.
+
+The main drawback to this development environment is
+that the Government does not own, nor has the right to modify
+code contained within the kernel. V&V techniques in this
+situation are more difficult than if the complete source code
+were available. Responsibility for system failures due to faulty
+software is yet another area to be resolved under this
+environment.
+
+The Guidance and Control Directorate began a software
+development effort to address these problems. A project to
+develop an experimental run time kernel was begun that will
+eliminate the major drawbacks of the Ada programming language
+mentioned above. The Real Time Executive for Multiprocessor Systems
+(RTEMS) provides full capabilities for management of tasks,
+interrupts, time, and multiple processors in addition to those
+features typical of generic operating systems. The code is
+Government owned, so no licensing fees are necessary. RTEMS has
+been implemented in both the Ada and C programming languages.
+It has been ported to the Motorola MC68xxx family, the Intel
+i80386 and above, and the Intel i80960 family. Support for
+other processor families, including RISC, CISC, and DSP, is
+planned. Since almost all of RTEMS is written in a high level
+language, ports to additional processor families require minimal
+effort.
+
+RTEMS multiprocessor support is capable of handling
+either homogeneous or heterogeneous systems. The kernel
+automatically compensates for architectural differences (byte
+swapping, etc.) between processors. This allows a much easier
+transition from one processor family to another without a major
+system redesign.
+
+Since the proposed standards are still in draft form,
+RTEMS cannot and does not claim compliance. However, the status
+of the standard is being carefully monitored to guarantee that
+RTEMS provides the functionality specified in the standard.
+Once approved, RTEMS will be made compliant.
+
+This document is a detailed users guide for a
+functionally compliant real-time multiprocessor executive. It
+describes the user interface and run-time behavior of Release
+@value{RTEMS-RELEASE} of the C implementation of RTEMS.
+
diff --git a/doc/user/region.t b/doc/user/region.t
new file mode 100644
index 0000000000..22a24cfb95
--- /dev/null
+++ b/doc/user/region.t
@@ -0,0 +1,601 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Region Manager, Region Manager Introduction, PARTITION_RETURN_BUFFER - Return buffer to a partition, Top
+@end ifinfo
+@chapter Region Manager
+@ifinfo
+@menu
+* Region Manager Introduction::
+* Region Manager Background::
+* Region Manager Operations::
+* Region Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Region Manager Introduction, Region Manager Background, Region Manager, Region Manager
+@end ifinfo
+@section Introduction
+
+The region manager provides facilities to dynamically
+allocate memory in variable sized units. The directives
+provided by the region manager are:
+
+@itemize @bullet
+@item @code{region_create} - Create a region
+@item @code{region_ident} - Get ID of a region
+@item @code{region_delete} - Delete a region
+@item @code{region_extend} - Add memory to a region
+@item @code{region_get_segment} - Get segment from a region
+@item @code{region_return_segment} - Return segment to a region
+@item @code{region_get_segment_size} - Obtain size of a segment
+@end itemize
+
+@ifinfo
+@node Region Manager Background, Region Manager Definitions, Region Manager Introduction, Region Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Region Manager Definitions::
+* Building an Attribute Set::
+* Building an Option Set::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Region Manager Definitions, Building an Attribute Set, Region Manager Background, Region Manager Background
+@end ifinfo
+@subsection Region Manager Definitions
+
+A region makes up a physically contiguous memory
+space with user-defined boundaries from which variable-sized
+segments are dynamically allocated and deallocated. A segment
+is a variable size section of memory which is allocated in
+multiples of a user-defined page size. This page size is
+required to be a multiple of four greater than or equal to four.
+For example, if a request for a 350-byte segment is made in a
+region with 256-byte pages, then a 512-byte segment is allocated.
+
+Regions are organized as doubly linked chains of
+variable sized memory blocks. Memory requests are allocated
+using a first-fit algorithm. If available, the requester
+receives the number of bytes requested (rounded up to the next
+page size). RTEMS requires some overhead from the region's
+memory for each segment that is allocated. Therefore, an
+application should only modify the memory of a segment that has
+been obtained from the region. The application should NOT
+modify the memory outside of any obtained segments and within
+the region's boundaries while the region is currently active in
+the system.
+
+Upon return to the region, the free block is
+coalesced with its neighbors (if free) on both sides to produce
+the largest possible unused block.
+
+@ifinfo
+@node Building an Attribute Set, Building an Option Set, Region Manager Definitions, Region Manager Background
+@end ifinfo
+@subsection Building an Attribute Set
+
+In general, an attribute set is built by a bitwise OR
+of the desired attribute components. The set of valid region
+attributes is provided in the following table:
+
+@itemize @bullet
+@item FIFO - tasks wait by FIFO (default)
+@item PRIORITY - tasks wait by priority
+@end itemize
+
+Attribute values are specifically designed to be
+mutually exclusive, therefore bitwise OR and addition operations
+are equivalent as long as each attribute appears exactly once in
+the component list. An attribute listed as a default is not
+required to appear in the attribute list, although it is a good
+programming practice to specify default attributes. If all
+defaults are desired, the attribute DEFAULT_ATTRIBUTES should be
+specified on this call.
+
+This example demonstrates the attribute_set parameter
+needed to create a region with the task priority waiting queue
+discipline. The attribute_set parameter to the region_create
+directive should be PRIORITY.
+
+@ifinfo
+@node Building an Option Set, Region Manager Operations, Building an Attribute Set, Region Manager Background
+@end ifinfo
+@subsection Building an Option Set
+
+In general, an option is built by a bitwise OR of the
+desired option components. The set of valid options for the
+region_get_segment directive are listed in the following table:
+
+@itemize @bullet
+@item WAIT - task will wait for semaphore (default)
+@item NO_WAIT - task should not wait
+@end itemize
+
+Option values are specifically designed to be
+mutually exclusive, therefore bitwise OR and addition operations
+are equivalent as long as each option appears exactly once in
+the component list. An option listed as a default is not
+required to appear in the option list, although it is a good
+programming practice to specify default options. If all
+defaults are desired, the option DEFAULT_OPTIONS should be
+specified on this call.
+
+This example demonstrates the option parameter needed
+to poll for a segment. The option parameter passed to the
+region_get_segment directive should be NO_WAIT.
+
+@ifinfo
+@node Region Manager Operations, Creating a Region, Building an Option Set, Region Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Region::
+* Obtaining Region IDs::
+* Adding Memory to a Region::
+* Acquiring a Segment::
+* Releasing a Segment::
+* Obtaining the Size of a Segment::
+* Deleting a Region::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Region, Obtaining Region IDs, Region Manager Operations, Region Manager Operations
+@end ifinfo
+@subsection Creating a Region
+
+The region_create directive creates a region with the
+user-defined name. The user may select FIFO or task priority as
+the method for placing waiting tasks in the task wait queue.
+RTEMS allocates a Region Control Block (RNCB) from the RNCB free
+list to maintain the newly created region. RTEMS also generates
+a unique region ID which is returned to the calling task.
+
+It is not possible to calculate the exact number of
+bytes available to the user since RTEMS requires overhead for
+each segment allocated. For example, a region with one segment
+that is the size of the entire region has more available bytes
+than a region with two segments that collectively are the size
+of the entire region. This is because the region with one
+segment requires only the overhead for one segment, while the
+other region requires the overhead for two segments.
+
+Due to automatic coalescing, the number of segments
+in the region dynamically changes. Therefore, the total
+overhead required by RTEMS dynamically changes.
+
+@ifinfo
+@node Obtaining Region IDs, Adding Memory to a Region, Creating a Region, Region Manager Operations
+@end ifinfo
+@subsection Obtaining Region IDs
+
+When a region is created, RTEMS generates a unique
+region ID and assigns it to the created region until it is
+deleted. The region ID may be obtained by either of two
+methods. First, as the result of an invocation of the
+region_create directive, the region ID is stored in a user
+provided location. Second, the region ID may be obtained later
+using the region_ident directive. The region ID is used by
+other region manager directives to access this region.
+
+@ifinfo
+@node Adding Memory to a Region, Acquiring a Segment, Obtaining Region IDs, Region Manager Operations
+@end ifinfo
+@subsection Adding Memory to a Region
+
+The region_extend directive may be used to add memory
+to an existing region. The caller specifies the size in bytes
+and starting address of the memory being added.
+
+NOTE: Please see the release notes or RTEMS source
+code for information regarding restrictions on the location of
+the memory being added in relation to memory already in the
+region.
+
+@ifinfo
+@node Acquiring a Segment, Releasing a Segment, Adding Memory to a Region, Region Manager Operations
+@end ifinfo
+@subsection Acquiring a Segment
+
+The region_get_segment directive attempts to acquire
+a segment from a specified region. If the region has enough
+available free memory, then a segment is returned successfully
+to the caller. When the segment cannot be allocated, one of the
+following situations applies:
+
+@itemize @bullet
+@item By default, the calling task will wait forever to acquire the segment.
+
+@item Specifying the NO_WAIT option forces an immediate return
+with an error status code.
+
+@item Specifying a timeout limits the interval the task will
+wait before returning with an error status code.
+@end itemize
+
+If the task waits for the segment, then it is placed
+in the region's task wait queue in either FIFO or task priority
+order. All tasks waiting on a region are returned an error when
+the message queue is deleted.
+
+@ifinfo
+@node Releasing a Segment, Obtaining the Size of a Segment, Acquiring a Segment, Region Manager Operations
+@end ifinfo
+@subsection Releasing a Segment
+
+When a segment is returned to a region by the
+region_return_segment directive, it is merged with its
+unallocated neighbors to form the largest possible segment. The
+first task on the wait queue is examined to determine if its
+segment request can now be satisfied. If so, it is given a
+segment and unblocked. This process is repeated until the first
+task's segment request cannot be satisfied.
+
+@ifinfo
+@node Obtaining the Size of a Segment, Deleting a Region, Releasing a Segment, Region Manager Operations
+@end ifinfo
+@subsection Obtaining the Size of a Segment
+
+The region_get_segment_size directive returns the
+size in bytes of the specified segment. The size returned
+includes any "extra" memory included in the segment because of
+rounding up to a page size boundary.
+
+@ifinfo
+@node Deleting a Region, Region Manager Directives, Obtaining the Size of a Segment, Region Manager Operations
+@end ifinfo
+@subsection Deleting a Region
+
+A region can be removed from the system and returned
+to RTEMS with the region_delete directive. When a region is
+deleted, its control block is returned to the RNCB free list. A
+region with segments still allocated is not allowed to be
+deleted. Any task attempting to do so will be returned an
+error. As a result of this directive, all tasks blocked waiting
+to obtain a segment from the region will be readied and returned
+a status code which indicates that the region was deleted.
+
+@ifinfo
+@node Region Manager Directives, REGION_CREATE - Create a region, Deleting a Region, Region Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* REGION_CREATE - Create a region::
+* REGION_IDENT - Get ID of a region::
+* REGION_DELETE - Delete a region::
+* REGION_EXTEND - Add memory to a region::
+* REGION_GET_SEGMENT - Get segment from a region::
+* REGION_RETURN_SEGMENT - Return segment to a region::
+* REGION_GET_SEGMENT_SIZE - Obtain size of a segment::
+@end menu
+@end ifinfo
+
+This section details the region manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@ifinfo
+@node REGION_CREATE - Create a region, REGION_IDENT - Get ID of a region, Region Manager Directives, Region Manager Directives
+@end ifinfo
+@subsection REGION_CREATE - Create a region
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_create(
+ rtems_name name,
+ void *starting_address,
+ rtems_unsigned32 length,
+ rtems_unsigned32 page_size,
+ rtems_attribute attribute_set,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - region created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{INVALID_ADDRESS} - address not on four byte boundary@*
+@code{TOO_MANY} - too many regions created@*
+@code{INVALID_SIZE} - invalid page size
+
+@subheading DESCRIPTION:
+
+This directive creates a region from a physically
+contiguous memory space which starts at starting_address and is
+length bytes long. Segments allocated from the region will be a
+multiple of page_size bytes in length. The assigned region id
+is returned in id. This region id is used as an argument to
+other region related directives to access the region.
+
+For control and maintenance of the region, RTEMS
+allocates and initializes an RNCB from the RNCB free pool. Thus
+memory from the region is not used to store the RNCB. However,
+some overhead within the region is required by RTEMS each time a
+segment is constructed in the region.
+
+Specifying PRIORITY in attribute_set causes tasks
+waiting for a segment to be serviced according to task priority.
+Specifying FIFO in attribute_set or selecting
+DEFAULT_ATTRIBUTES will cause waiting tasks to be serviced in
+First In-First Out order.
+
+The starting_address parameter must be aligned on a
+four byte boundary. The page_size parameter must be a multiple
+of four greater than or equal to four.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The following region attribute constants are defined
+by RTEMS:
+
+@itemize @bullet
+@item FIFO - tasks wait by FIFO (default)
+@item PRIORITY - tasks wait by priority
+@end itemize
+
+@page
+@ifinfo
+@node REGION_IDENT - Get ID of a region, REGION_DELETE - Delete a region, REGION_CREATE - Create a region, Region Manager Directives
+@end ifinfo
+@subsection REGION_IDENT - Get ID of a region
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_ident(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - region identified successfully@*
+@code{INVALID_NAME} - region name not found
+
+@subheading DESCRIPTION:
+
+This directive obtains the region id associated with
+the region name to be acquired. If the region name is not
+unique, then the region id will match one of the regions with
+that name. However, this region id is not guaranteed to
+correspond to the desired region. The region id is used to
+access this region in other region manager directives.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be preempted.
+
+@page
+@ifinfo
+@node REGION_DELETE - Delete a region, REGION_EXTEND - Add memory to a region, REGION_IDENT - Get ID of a region, Region Manager Directives
+@end ifinfo
+@subsection REGION_DELETE - Delete a region
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - region deleted successfully@*
+@code{INVALID_ID} - invalid region id@*
+@code{RESOURCE_IN_USE} - segments still in use
+
+@subheading DESCRIPTION:
+
+This directive deletes the region specified by id.
+The region cannot be deleted if any of its segments are still
+allocated. The RNCB for the deleted region is reclaimed by
+RTEMS.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be preempted.
+
+The calling task does not have to be the task that
+created the region. Any local task that knows the region id can
+delete the region.
+
+@page
+@ifinfo
+@node REGION_EXTEND - Add memory to a region, REGION_GET_SEGMENT - Get segment from a region, REGION_DELETE - Delete a region, Region Manager Directives
+@end ifinfo
+@subsection REGION_EXTEND - Add memory to a region
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_extend(
+ rtems_id id,
+ void *starting_address,
+ rtems_unsigned32 length
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - region extended successfully@*
+@code{INVALID_ID} - invalid region id@*
+@code{INVALID_ADDRESS} - invalid address of area to add
+
+@subheading DESCRIPTION:
+
+This directive adds the memory which starts at
+starting_address for length bytes to the region specified by id.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be preempted.
+
+The calling task does not have to be the task that
+created the region. Any local task that knows the region id can
+extend the region.
+
+@page
+@ifinfo
+@node REGION_GET_SEGMENT - Get segment from a region, REGION_RETURN_SEGMENT - Return segment to a region, REGION_EXTEND - Add memory to a region, Region Manager Directives
+@end ifinfo
+@subsection REGION_GET_SEGMENT - Get segment from a region
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_get_segment(
+ rtems_id id,
+ rtems_unsigned32 size,
+ rtems_option option_set,
+ rtems_interval timeout,
+ void **segment
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - segment obtained successfully@*
+@code{INVALID_ID} - invalid region id@*
+@code{INVALID_SIZE} - request is for zero bytes or exceeds
+the size of maximum segment which is possible for this region@*
+@code{UNSATISFIED} - segment of requested size not available@*
+@code{TIMEOUT} - timed out waiting for segment@*
+@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting
+
+@subheading DESCRIPTION:
+
+This directive obtains a variable size segment from
+the region specified by id. The address of the allocated
+segment is returned in segment. The WAIT and NO_WAIT components
+of the options parameter are used to specify whether the calling
+tasks wish to wait for a segment to become available or return
+immediately if no segment is available. For either option, if a
+sufficiently sized segment is available, then the segment is
+successfully acquired by returning immediately with the
+SUCCESSFUL status code.
+
+If the calling task chooses to return immediately and
+a segment large enough is not available, then an error code
+indicating this fact is returned. If the calling task chooses
+to wait for the segment and a segment large enough is not
+available, then the calling task is placed on the region's
+segment wait queue and blocked. If the region was created with
+the PRIORITY option, then the calling task is inserted into the
+wait queue according to its priority. However, if the region
+was created with the FIFO option, then the calling task is
+placed at the rear of the wait queue.
+
+The timeout parameter specifies the maximum interval
+that a task is willing to wait to obtain a segment. If timeout
+is set to NO_TIMEOUT, then the calling task will wait forever.
+
+@subheading NOTES:
+
+The actual length of the allocated segment may be
+larger than the requested size because a segment size is always
+a multiple of the region's page size.
+
+The following segment acquisition option constants
+are defined by RTEMS:
+
+@itemize @bullet
+@item WAIT - task will wait for semaphore (default)
+@item NO_WAIT - task should not wait
+@end itemize
+
+@page
+@ifinfo
+@node REGION_RETURN_SEGMENT - Return segment to a region, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, REGION_GET_SEGMENT - Get segment from a region, Region Manager Directives
+@end ifinfo
+@subsection REGION_RETURN_SEGMENT - Return segment to a region
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_return_segment(
+ rtems_id id,
+ void *segment
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - segment returned successfully@*
+@code{INVALID_ID} - invalid region id@*
+@code{INVALID_ADDRESS} - segment address not in region
+
+@subheading DESCRIPTION:
+
+This directive returns the segment specified by
+segment to the region specified by id. The returned segment is
+merged with its neighbors to form the largest possible segment.
+The first task on the wait queue is examined to determine if its
+segment request can now be satisfied. If so, it is given a
+segment and unblocked. This process is repeated until the first
+task's segment request cannot be satisfied.
+
+@subheading NOTES:
+
+This directive will cause the calling task to be
+preempted if one or more local tasks are waiting for a segment
+and the following conditions exist:
+
+@itemize @bullet
+@item a waiting task has a higher priority than the calling task
+
+@item the size of the segment required by the waiting task
+is less than or equal to the size of the segment returned.
+@end itemize
+
+@page
+@ifinfo
+@node REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Dual-Ported Memory Manager, REGION_RETURN_SEGMENT - Return segment to a region, Region Manager Directives
+@end ifinfo
+@subsection REGION_GET_SEGMENT_SIZE - Obtain size of a segment
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_region_get_segment_size(
+ rtems_id id,
+ void *segment,
+ rtems_unsigned32 *size
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{SUCCESSFUL} - segment obtained successfully@*
+@code{INVALID_ID} - invalid region id@*
+@code{INVALID_ADDRESS} - segment address not in region
+
+@subheading DESCRIPTION:
+
+This directive obtains the size in bytes of the specified segment.
+
+@subheading NOTES:
+
+The actual length of the allocated segment may be
+larger than the requested size because a segment size is always
+a multiple of the region's page size.
+
diff --git a/doc/user/rtemsarc.gif b/doc/user/rtemsarc.gif
new file mode 100644
index 0000000000..fea62ecb42
--- /dev/null
+++ b/doc/user/rtemsarc.gif
Binary files differ
diff --git a/doc/user/rtemspie.gif b/doc/user/rtemspie.gif
new file mode 100644
index 0000000000..8341861b0d
--- /dev/null
+++ b/doc/user/rtemspie.gif
Binary files differ
diff --git a/doc/user/rtmon.t b/doc/user/rtmon.t
new file mode 100644
index 0000000000..91fb23b2bf
--- /dev/null
+++ b/doc/user/rtmon.t
@@ -0,0 +1,1148 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@c
+@c Open Issues
+@c - nicen up the tables
+@c - use math mode to print formulas
+@c
+
+@ifinfo
+@node Rate Monotonic Manager, Rate Monotonic Manager Introduction, Scheduling Concepts Task State Transitions, Top
+@end ifinfo
+@chapter Rate Monotonic Manager
+@ifinfo
+@menu
+* Rate Monotonic Manager Introduction::
+* Rate Monotonic Manager Background::
+* Rate Monotonic Manager Operations::
+* Rate Monotonic Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Rate Monotonic Manager Introduction, Rate Monotonic Manager Background, Rate Monotonic Manager, Rate Monotonic Manager
+@end ifinfo
+@section Introduction
+
+The rate monotonic manager provides facilities to
+implement tasks which execute in a periodic fashion. The
+directives provided by the rate monotonic manager are:
+
+@itemize @bullet
+@item @code{rate_monotonic_create} - Create a rate monotonic period
+@item @code{rate_monotonic_ident} - Get ID of a period
+@item @code{rate_monotonic_cancel} - Cancel a period
+@item @code{rate_monotonic_delete} - Delete a rate monotonic period
+@item @code{rate_monotonic_period} - Conclude current/Start next period
+@item @code{rate_monotonic_get_status} - Obtain status information on period
+@end itemize
+
+@ifinfo
+@node Rate Monotonic Manager Background, Rate Monotonic Manager Definitions, Rate Monotonic Manager Introduction, Rate Monotonic Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Rate Monotonic Manager Definitions::
+* Rate Monotonic Scheduling Algorithm::
+* Schedulability Analysis::
+* Assumptions::
+* Processor Utilization Rule::
+* Processor Utilization Rule Example::
+* First Deadline Rule::
+* First Deadline Rule Example::
+* Relaxation of Assumptions::
+* Further Reading::
+@end menu
+@end ifinfo
+
+The rate monotonic manager provides facilities to
+manage the execution of periodic tasks. This manager was
+designed to support application designers who utilize the Rate
+Monotonic Scheduling Algorithm (RMS) to insure that their
+periodic tasks will meet their deadlines, even under transient
+overload conditions. Although designed for hard real-time
+systems, the services provided by the rate monotonic manager may
+be used by any application which requires periodic tasks.
+
+@ifinfo
+@node Rate Monotonic Manager Definitions, Rate Monotonic Scheduling Algorithm, Rate Monotonic Manager Background, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Rate Monotonic Manager Definitions
+
+A periodic task is one which must be executed at a
+regular interval. The interval between successive iterations of
+the task is referred to as its period. Periodic tasks can be
+characterized by the length of their period and execution time.
+The period and execution time of a task can be used to determine
+the processor utilization for that task. Processor utilization
+is the percentage of processor time used and can be calculated
+on a per-task or system-wide basis. Typically, the task's
+worst-case execution time will be less than its period. For
+example, a periodic task's requirements may state that it should
+execute for 10 milliseconds every 100 milliseconds. Although
+the execution time may be the average, worst, or best case, the
+worst-case execution time is more appropriate for use when
+analyzing system behavior under transient overload conditions.
+
+In contrast, an aperiodic task executes at irregular
+intervals and has only a soft deadline. In other words, the
+deadlines for aperiodic tasks are not rigid, but adequate
+response times are desirable. For example, an aperiodic task
+may process user input from a terminal.
+
+Finally, a sporadic task is an aperiodic task with a
+hard deadline and minimum interarrival time. The minimum
+interarrival time is the minimum period of time which exists
+between successive iterations of the task. For example, a
+sporadic task could be used to process the pressing of a fire
+button on a joystick. The mechanical action of the fire button
+insures a minimum time period between successive activations,
+but the missile must be launched by a hard deadline.
+
+@ifinfo
+@node Rate Monotonic Scheduling Algorithm, Schedulability Analysis, Rate Monotonic Manager Definitions, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Rate Monotonic Scheduling Algorithm
+
+The Rate Monotonic Scheduling Algorithm (RMS) is
+important to real-time systems designers because it allows one
+to guarantee that a set of tasks is schedulable. A set of tasks
+is said to be schedulable if all of the tasks can meet their
+deadlines. RMS provides a set of rules which can be used to
+perform a guaranteed schedulability analysis for a task set.
+This analysis determines whether a task set is schedulable under
+worst-case conditions and emphasizes the predictability of the
+system's behavior. It has been proven that:
+
+@itemize @code{ }
+@b{RMS is an optimal static priority algorithm for
+scheduling independent, preemptible, periodic tasks
+on a single processor.}
+@end itemize
+
+RMS is optimal in the sense that if a set of tasks
+can be scheduled by any static priority algorithm, then RMS will
+be able to schedule that task set. RMS bases it schedulability
+analysis on the processor utilization level below which all
+deadlines can be met.
+
+RMS calls for the static assignment of task
+priorities based upon their period. The shorter a task's
+period, the higher its priority. For example, a task with a 1
+millisecond period has higher priority than a task with a 100
+millisecond period. If two tasks have the same period, than RMS
+does not distinguish between the tasks. However, RTEMS
+specifies that when given tasks of equal priority, the task
+which has been ready longest will execute first. RMS's priority
+assignment scheme does not provide one with exact numeric values
+for task priorities. For example, consider the following task
+set and priority assignments:
+
+@ifset use-ascii
+@example
+@group
++--------------------+---------------------+---------------------+
+| Task | Period | Priority |
+| | (in milliseconds) | |
++--------------------+---------------------+---------------------+
+| 1 | 100 | Low |
++--------------------+---------------------+---------------------+
+| 2 | 50 | Medium |
++--------------------+---------------------+---------------------+
+| 3 | 50 | Medium |
++--------------------+---------------------+---------------------+
+| 4 | 25 | High |
++--------------------+---------------------+---------------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+@tex
+\centerline{\vbox{\offinterlineskip\halign{
+\vrule\strut#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.25in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.25in{\enskip\hfil#\hfil}&
+\vrule#\cr\noalign{\hrule}
+&\bf Task&& \bf Period && \bf Priority &\cr
+& && \bf (in milliseconds) && &\cr\noalign{\hrule}
+& 1 && 100 && Low &\cr\noalign{\hrule}
+& 2 && 50 && Medium &\cr\noalign{\hrule}
+& 3 && 50 && Medium &\cr\noalign{\hrule}
+& 4 && 25 && Low &\cr\noalign{\hrule}
+}}\hfil}
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=3 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
+ <TD ALIGN=center><STRONG>Period (in milliseconds)</STRONG></TD>
+ <TD ALIGN=center><STRONG>Priority</STRONG></TD></TR>
+<TR><TD ALIGN=center>1</TD>
+ <TD ALIGN=center>100 </TD>
+ <TD ALIGN=center>Low</TD></TR>
+<TR><TD ALIGN=center>2</TD>
+ <TD ALIGN=center>50 </TD>
+ <TD ALIGN=center>Medium</TD></TR>
+<TR><TD ALIGN=center>3</TD>
+ <TD ALIGN=center>50 </TD>
+ <TD ALIGN=center>Medium</TD></TR>
+<TR><TD ALIGN=center>4</TD>
+ <TD ALIGN=center>25 </TD>
+ <TD ALIGN=center>High</TD></TR>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+RMS only calls for task 1 to have the lowest
+priority, task 4 to have the highest priority, and tasks 2 and 3
+to have an equal priority between that of tasks 1 and 4. The
+actual RTEMS priorities assigned to the tasks must only adhere
+to those guidelines.
+
+Many applications have tasks with both hard and soft
+deadlines. The tasks with hard deadlines are typically referred
+to as the critical task set, with the soft deadline tasks being
+the non-critical task set. The critical task set can be
+scheduled using RMS, with the non-critical tasks not executing
+under transient overload, by simply assigning priorities such
+that the lowest priority critical task (i.e. longest period) has
+a higher priority than the highest priority non-critical task.
+Although RMS may be used to assign priorities to the
+non-critical tasks, it is not necessary. In this instance,
+schedulability is only guaranteed for the critical task set.
+
+@ifinfo
+@node Schedulability Analysis, Assumptions, Rate Monotonic Scheduling Algorithm, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Schedulability Analysis
+
+RMS allows application designers to insure that tasks
+can meet all deadlines, even under transient overload, without
+knowing exactly when any given task will execute by applying
+proven schedulability analysis rules.
+
+@lowersections
+
+@ifinfo
+@node Assumptions, Processor Utilization Rule, Schedulability Analysis, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Assumptions
+
+The schedulability analysis rules for RMS were
+developed based on the following assumptions:
+
+
+@itemize @bullet
+@item The requests for all tasks for which hard deadlines
+exist are periodic, with a constant interval between requests.
+
+@item Each task must complete before the next request for it
+occurs.
+
+@item The tasks are independent in that a task does not depend
+on the initiation or completion of requests for other tasks.
+
+@item The execution time for each task without preemption or
+interruption is constant and does not vary.
+
+@item Any non-periodic tasks in the system are special. These
+tasks displace periodic tasks while executing and do not have
+hard, critical deadlines.
+@end itemize
+
+Once the basic schedulability analysis is understood,
+some of the above assumptions can be relaxed and the
+side-effects accounted for.
+
+@ifinfo
+@node Processor Utilization Rule, Processor Utilization Rule Example, Assumptions, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Processor Utilization Rule
+
+The Processor Utilization Rule requires that
+processor utilization be calculated based upon the period and
+execution time of each task. The fraction of processor time
+spent executing task index is Time(index) / Period(index). The
+processor utilization can be calculated as follows:
+
+@example
+@group
+Utilization = 0
+
+for index = 1 to maximum_tasks
+ Utilization = Utilization + (Time(index)/Period(index))
+@end group
+@end example
+
+To insure schedulability even under transient
+overload, the processor utilization must adhere to the following
+rule:
+
+@example
+Utilization = maximum_tasks * (2(1/maximum_tasks) - 1)
+@end example
+
+As the number of tasks increases, the above formula
+approaches ln(2) for a worst-case utilization factor of
+approximately 0.693. Many tasks sets can be scheduled with a
+greater utilization factor. In fact, the average processor
+utilization threshold for a randomly generated task set is
+approximately 0.88.
+
+@ifinfo
+@node Processor Utilization Rule Example, First Deadline Rule, Processor Utilization Rule, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Processor Utilization Rule Example
+
+This example illustrates the application of the
+Processor Utilization Rule to an application with three critical
+periodic tasks. The following table details the RMS priority,
+period, execution time, and processor utilization for each task:
+
+@ifset use-ascii
+@example
+@group
+ +------------+----------+--------+-----------+-------------+
+ | Task | RMS | Period | Execution | Processor |
+ | | Priority | | Time | Utilization |
+ +------------+----------+--------+-----------+-------------+
+ | 1 | High | 100 | 15 | 0.15 |
+ +------------+----------+--------+-----------+-------------+
+ | 2 | Medium | 200 | 50 | 0.25 |
+ +------------+----------+--------+-----------+-------------+
+ | 3 | Low | 300 | 100 | 0.33 |
+ +------------+----------+--------+-----------+-------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+@tex
+\centerline{\vbox{\offinterlineskip\halign{
+\vrule\strut#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.00in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.00in{\enskip\hfil#\hfil}&
+\vrule#\cr\noalign{\hrule}
+&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr
+& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule}
+& 1 && High && 100 && 15 && 0.15 &\cr\noalign{\hrule}
+& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule}
+& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule}
+}}\hfil}
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=5 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
+ <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD>
+ <TD ALIGN=center><STRONG>Period</STRONG></TD>
+ <TD ALIGN=center><STRONG>Execution Time</STRONG></TD>
+ <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR>
+<TR><TD ALIGN=center>1</TD>
+ <TD ALIGN=center>High</TD>
+ <TD ALIGN=center>100</TD>
+ <TD ALIGN=center>15</TD>
+ <TD ALIGN=center>0.15</TD></TR>
+<TR><TD ALIGN=center>2</TD>
+ <TD ALIGN=center>Medium</TD>
+ <TD ALIGN=center>200</TD>
+ <TD ALIGN=center>50</TD>
+ <TD ALIGN=center>0.25</TD></TR>
+<TR><TD ALIGN=center>3</TD>
+ <TD ALIGN=center>Low</TD>
+ <TD ALIGN=center>300</TD>
+ <TD ALIGN=center>100</TD>
+ <TD ALIGN=center>0.33</TD></TR>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+The total processor utilization for this task set is
+0.73 which is below the upper bound of 3 * (2(1/3) - 1), or
+0.779, imposed by the Processor Utilization Rule. Therefore,
+this task set is guaranteed to be schedulable using RMS.
+
+@ifinfo
+@node First Deadline Rule, First Deadline Rule Example, Processor Utilization Rule Example, Rate Monotonic Manager Background
+@end ifinfo
+@subsection First Deadline Rule
+
+If a given set of tasks do exceed the processor
+utilization upper limit imposed by the Processor Utilization
+Rule, they can still be guaranteed to meet all their deadlines
+by application of the First Deadline Rule. This rule can be
+stated as follows:
+
+For a given set of independent periodic tasks, if
+each task meets its first deadline when all tasks are started at
+the same time, then the deadlines will always be met for any
+combination of start times.
+
+A key point with this rule is that ALL periodic tasks
+are assumed to start at the exact same instant in time.
+Although this assumption may seem to be invalid, RTEMS makes it
+quite easy to insure. By having a non-preemptible user
+initialization task, all application tasks, regardless of
+priority, can be created and started before the initialization
+deletes itself. This technique insures that all tasks begin to
+compete for execution time at the same instant -- when the user
+initialization task deletes itself.
+
+@ifinfo
+@node First Deadline Rule Example, Relaxation of Assumptions, First Deadline Rule, Rate Monotonic Manager Background
+@end ifinfo
+@subsection First Deadline Rule Example
+
+The First Deadline Rule can insure schedulability
+even when the Processor Utilization Rule fails. The example
+below is a modification of the Processor Utilization Rule
+example where task execution time has been increased from 15 to
+25 units. The following table details the RMS priority, period,
+execution time, and processor utilization for each task:
+
+@ifset use-ascii
+@example
+@group
+ +------------+----------+--------+-----------+-------------+
+ | Task | RMS | Period | Execution | Processor |
+ | | Priority | | Time | Utilization |
+ +------------+----------+--------+-----------+-------------+
+ | 1 | High | 100 | 25 | 0.25 |
+ +------------+----------+--------+-----------+-------------+
+ | 2 | Medium | 200 | 50 | 0.25 |
+ +------------+----------+--------+-----------+-------------+
+ | 3 | Low | 300 | 100 | 0.33 |
+ +------------+----------+--------+-----------+-------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+@tex
+\centerline{\vbox{\offinterlineskip\halign{
+\vrule\strut#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.00in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.00in{\enskip\hfil#\hfil}&
+\vrule#\cr\noalign{\hrule}
+&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr
+& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule}
+& 1 && High && 100 && 25 && 0.25 &\cr\noalign{\hrule}
+& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule}
+& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule}
+}}\hfil}
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=5 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
+ <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD>
+ <TD ALIGN=center><STRONG>Period</STRONG></TD>
+ <TD ALIGN=center><STRONG>Execution Time</STRONG></TD>
+ <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR>
+<TR><TD ALIGN=center>1</TD>
+ <TD ALIGN=center>High</TD>
+ <TD ALIGN=center>100</TD>
+ <TD ALIGN=center>25</TD>
+ <TD ALIGN=center>0.25</TD></TR>
+<TR><TD ALIGN=center>2</TD>
+ <TD ALIGN=center>Medium</TD>
+ <TD ALIGN=center>200</TD>
+ <TD ALIGN=center>50</TD>
+ <TD ALIGN=center>0.25</TD></TR>
+<TR><TD ALIGN=center>3</TD>
+ <TD ALIGN=center>Low</TD>
+ <TD ALIGN=center>300</TD>
+ <TD ALIGN=center>100</TD>
+ <TD ALIGN=center>0.33</TD></TR>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+The total processor utilization for the modified task
+set is 0.83 which is above the upper bound of 3 * (2(1/3) - 1),
+or 0.779, imposed by the Processor Utilization Rule. Therefore,
+this task set is not guaranteed to be schedulable using RMS.
+However, the First Deadline Rule can guarantee the
+schedulability of this task set. This rule calls for one to
+examine each occurrence of deadline until either all tasks have
+met their deadline or one task failed to meet its first
+deadline. The following table details the time of each deadline
+occurrence, the maximum number of times each task may have run,
+the total execution time, and whether all the deadlines have
+been met.
+
+@ifset use-ascii
+@example
+@group
++----------+------+------+------+----------------------+---------------+
+| Deadline | Task | Task | Task | Total | All Deadlines |
+| Time | 1 | 2 | 3 | Execution Time | Met? |
++----------+------+------+------+----------------------+---------------+
+| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO |
++----------+------+------+------+----------------------+---------------+
+| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES |
++----------+------+------+------+----------------------+---------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+@tex
+\centerline{\vbox{\offinterlineskip\halign{
+\vrule\strut#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 0.75in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 2.00in{\enskip\hfil#\hfil}&
+\vrule#&
+\hbox to 1.00in{\enskip\hfil#\hfil}&
+\vrule#\cr\noalign{\hrule}
+&\bf Deadline&& \bf Task &&\bf Task&&\bf Task&&\bf Total &&\bf All Deadlines &\cr
+&\bf Time && \bf 1 &&\bf 2 &&\bf 3 &&\bf Execution Time &&\bf Net?&\cr\noalign{\hrule}
+& 100&& 1 && 1 && 1 && 25 + 50 + 100 = 175 && NO &\cr\noalign{\hrule}
+& 200&& 2 && 1 && 1 && 50 + 50 + 100 = 200 && YES &\cr\noalign{\hrule}
+}}\hfil}
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=6 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center><STRONG>Deadline Time</STRONG></TD>
+ <TD ALIGN=center><STRONG>Task 1</STRONG></TD>
+ <TD ALIGN=center><STRONG>Task 2</STRONG></TD>
+ <TD ALIGN=center><STRONG>Task 3</STRONG></TD>
+ <TD ALIGN=center><STRONG>Total Execution Time</STRONG></TD>
+ <TD ALIGN=center><STRONG>All Deadlines Met?</STRONG></TD></TR>
+<TR><TD ALIGN=center>100</TD>
+ <TD ALIGN=center>1</TD>
+ <TD ALIGN=center>1</TD>
+ <TD ALIGN=center>1</TD>
+ <TD ALIGN=center>25 + 50 + 100 = 175</TD>
+ <TD ALIGN=center>NO</TD></TR>
+<TR><TD ALIGN=center>200</TD>
+ <TD ALIGN=center>2</TD>
+ <TD ALIGN=center>1</TD>
+ <TD ALIGN=center>1</TD>
+ <TD ALIGN=center>50 + 50 + 100 = 175</TD>
+ <TD ALIGN=center>YES</TD></TR>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+The key to this analysis is to recognize when each
+task will execute. For example at time 100, task 1 must have
+met its first deadline, but tasks 2 and 3 may also have begun
+execution. In this example, at time 100 tasks 1 and 2 have
+completed execution and thus have met their first deadline.
+Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100
+- 75) = 25 time units for task 3 to begin. Because task 3 takes
+100 ticks to execute, it will not have completed execution at
+time 100. Thus at time 100, all of the tasks except task 3 have
+met their first deadline.
+
+At time 200, task 1 must have met its second deadline
+and task 2 its first deadline. As a result, of the first 200
+time units, task 1 uses (2 * 25) = 50 and task 2 uses 50,
+leaving (200 - 100) time units for task 3. Task 3 requires 100
+time units to execute, thus it will have completed execution at
+time 200. Thus, all of the tasks have met their first deadlines
+at time 200, and the task set is schedulable using the First
+Deadline Rule.
+
+@ifinfo
+@node Relaxation of Assumptions, Further Reading, First Deadline Rule Example, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Relaxation of Assumptions
+
+The assumptions used to develop the RMS
+schedulability rules are uncommon in most real-time systems.
+For example, it was assumed that tasks have constant unvarying
+execution time. It is possible to relax this assumption, simply
+by using the worst-case execution time of each task.
+
+Another assumption is that the tasks are independent.
+This means that the tasks do not wait for one another or
+contend for resources. This assumption can be relaxed by
+accounting for the amount of time a task spends waiting to
+acquire resources. Similarly, each task's execution time must
+account for any I/O performed and any RTEMS directive calls.
+
+In addition, the assumptions did not account for the
+time spent executing interrupt service routines. This can be
+accounted for by including all the processor utilization by
+interrupt service routines in the utilization calculation.
+Similarly, one should also account for the impact of delays in
+accessing local memory caused by direct memory access and other
+processors accessing local dual-ported memory.
+
+The assumption that nonperiodic tasks are used only
+for initialization or failure-recovery can be relaxed by placing
+all periodic tasks in the critical task set. This task set can
+be scheduled and analyzed using RMS. All nonperiodic tasks are
+placed in the non-critical task set. Although the critical task
+set can be guaranteed to execute even under transient overload,
+the non-critical task set is not guaranteed to execute.
+
+In conclusion, the application designer must be fully
+cognizant of the system and its run-time behavior when
+performing schedulability analysis for a system using RMS.
+Every hardware and software factor which impacts the execution
+time of each task must be accounted for in the schedulability
+analysis.
+
+@ifinfo
+@node Further Reading, Rate Monotonic Manager Operations, Relaxation of Assumptions, Rate Monotonic Manager Background
+@end ifinfo
+@subsection Further Reading
+
+For more information on Rate Monotonic Scheduling and
+its schedulability analysis, the reader is referred to the
+following:
+
+@itemize @code{ }
+@item @cite{C. L. Liu and J. W. Layland. "Scheduling Algorithms for
+Multiprogramming in a Hard Real Time Environment." @b{Journal of
+the Association of Computing Machinery}. January 1973. pp. 46-61.}
+
+@item @cite{John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
+Scheduling Algorithm: Exact Characterization and Average Case
+Behavior." @b{IEEE Real-Time Systems Symposium}. 1989. pp. 166-171.}
+
+@item @cite{Lui Sha and John Goodenough. "Real-Time Scheduling
+Theory and Ada." @b{IEEE Computer}. April 1990. pp. 53-62.}
+
+@item @cite{Alan Burns. "Scheduling hard real-time systems: a
+review." @b{Software Engineering Journal}. May 1991. pp. 116-128.}
+@end itemize
+
+@raisesections
+
+@ifinfo
+@node Rate Monotonic Manager Operations, Creating a Rate Monotonic Period, Further Reading, Rate Monotonic Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Rate Monotonic Period::
+* Manipulating a Period::
+* Obtaining a Period's Status::
+* Canceling a Period::
+* Deleting a Rate Monotonic Period::
+* Examples::
+* Simple Periodic Task::
+* Task with Multiple Periods::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Rate Monotonic Period, Manipulating a Period, Rate Monotonic Manager Operations, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Creating a Rate Monotonic Period
+
+The rate_monotonic_create directive creates a rate
+monotonic period which is to be used by the calling task to
+delineate a period. RTEMS allocates a Period Control Block
+(PCB) from the PCB free list. This data structure is used by
+RTEMS to manage the newly created rate monotonic period. RTEMS
+returns a unique period ID to the application which is used by
+other rate monotonic manager directives to access this rate
+monotonic period.
+
+@ifinfo
+@node Manipulating a Period, Obtaining a Period's Status, Creating a Rate Monotonic Period, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Manipulating a Period
+
+The rate_monotonic_period directive is used to
+establish and maintain periodic execution utilizing a previously
+created rate monotonic period. Once initiated by the
+rate_monotonic_period directive, the period is said to run until
+it either expires or is reinitiated. The state of the rate
+monotonic period results in one of the following scenarios:
+
+@itemize @bullet
+@item If the rate monotonic period is running, the calling
+task will be blocked for the remainder of the outstanding period
+and, upon completion of that period, the period will be
+reinitiated with the specified period.
+
+@item If the rate monotonic period is not currently running
+and has not expired, it is initiated with a length of period
+ticks and the calling task returns immediately.
+
+@item If the rate monotonic period has expired before the task
+invokes the rate_monotonic_period directive, the period will be
+initiated with a length of period ticks and the calling task
+returns immediately with a timeout error status.
+@end itemize
+
+@ifinfo
+@node Obtaining a Period's Status, Canceling a Period, Manipulating a Period, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Obtaining a Period's Status
+
+If the rate_monotonic_period directive is invoked
+with a period of PERIOD_STATUS ticks, the current state of the
+specified rate monotonic period will be returned. The following
+table details the relationship between the period's status and
+the directive status code returned by the rate_monotonic_period
+directive:
+
+@itemize @bullet
+@item SUCCESSFUL - period is running
+
+@item TIMEOUT - period has expired
+
+@item NOT_DEFINED - period has never been initiated
+@end itemize
+
+Obtaining the status of a rate monotonic period does
+not alter the state or length of that period.
+
+@ifinfo
+@node Canceling a Period, Deleting a Rate Monotonic Period, Obtaining a Period's Status, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Canceling a Period
+
+The rate_monotonic_cancel directive is used to stop
+the period maintained by the specified rate monotonic period.
+The period is stopped and the rate monotonic period can be
+reinitiated using the rate_monotonic_period directive.
+
+@ifinfo
+@node Deleting a Rate Monotonic Period, Examples, Canceling a Period, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Deleting a Rate Monotonic Period
+
+The rate_monotonic_delete directive is used to delete
+a rate monotonic period. If the period is running and has not
+expired, the period is automatically canceled. The rate
+monotonic period's control block is returned to the PCB free
+list when it is deleted. A rate monotonic period can be deleted
+by a task other than the task which created the period.
+
+@ifinfo
+@node Examples, Simple Periodic Task, Deleting a Rate Monotonic Period, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Examples
+
+The following sections illustrate common uses of rate
+monotonic periods to construct periodic tasks.
+
+@ifinfo
+@node Simple Periodic Task, Task with Multiple Periods, Examples, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Simple Periodic Task
+
+This example consists of a single periodic task
+which, after initialization, executes every 100 clock ticks.
+
+@page
+@example
+rtems_task Periodic_task()
+@{
+ rtems_name name;
+ rtems_id period;
+ rtems_status_code status;
+
+ name = build_name( 'P', 'E', 'R', 'D' );
+
+ (void) rate_monotonic_create( name, &period );
+
+ while ( 1 ) @{
+ if ( rate_monotonic_period( period, 100 ) == TIMEOUT )
+ break;
+
+ /* Perform some periodic actions */
+ @}
+
+ /* missed period so delete period and SELF */
+
+ (void) rate_monotonic_delete( period );
+ (void) task_delete( SELF );
+@}
+@end example
+
+
+The above task creates a rate monotonic period as
+part of its initialization. The first time the loop is
+executed, the rate_monotonic_period directive will initiate the
+period for 100 ticks and return immediately. Subsequent
+invocations of the rate_monotonic_period directive will result
+in the task blocking for the remainder of the 100 tick period.
+If, for any reason, the body of the loop takes more than 100
+ticks to execute, the rate_monotonic_period directive will
+return the TIMEOUT status. If the above task misses its
+deadline, it will delete the rate monotonic period and itself.
+
+@ifinfo
+@node Task with Multiple Periods, Rate Monotonic Manager Directives, Simple Periodic Task, Rate Monotonic Manager Operations
+@end ifinfo
+@subsection Task with Multiple Periods
+
+This example consists of a single periodic task
+which, after initialization, performs two sets of actions every
+100 clock ticks. The first set of actions is performed in the
+first forty clock ticks of every 100 clock ticks, while the
+second set of actions is performed between the fortieth and
+seventieth clock ticks. The last thirty clock ticks are not
+used by this task.
+
+@page
+@example
+task Periodic_task()
+@{
+ rtems_name name_1, name_2;
+ rtems_id period_1, period_2;
+ rtems_status_code status;
+
+ name_1 = build_name( 'P', 'E', 'R', '1' );
+ name_2 = build_name( 'P', 'E', 'R', '2' );
+
+ (void ) rate_monotonic_create( name_1, &period_1 );
+ (void ) rate_monotonic_create( name_2, &period_2 );
+
+ while ( 1 ) @{
+ if ( rate_monotonic_period( period_1, 100 ) == TIMEOUT )
+ break;
+
+ if ( rate_monotonic_period( period_2, 40 ) == TIMEOUT )
+ break;
+
+ /*
+ * Perform first set of actions between clock
+ * ticks 0 and 39 of every 100 ticks.
+ */
+
+ if ( rate_monotonic_period( period_2, 30 ) == TIMEOUT )
+ break;
+
+ /*
+ * Perform second set of actions between clock 40 and 69
+ * of every 100 ticks. THEN ...
+ *
+ * Check to make sure we didn't miss the period_2 period.
+ */
+
+ if ( rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
+ break;
+
+ (void) rate_monotonic_cancel( period_2 );
+ @}
+
+ /* missed period so delete period and SELF */
+
+ (void ) rate_monotonic_delete( period_1 );
+ (void ) rate_monotonic_delete( period_2 );
+ (void ) task_delete( SELF );
+@}
+@end example
+
+The above task creates two rate monotonic periods as
+part of its initialization. The first time the loop is
+executed, the rate_monotonic_period directive will initiate the
+period_1 period for 100 ticks and return immediately.
+Subsequent invocations of the rate_monotonic_period directive
+for period_1 will result in the task blocking for the remainder
+of the 100 tick period. The period_2 period is used to control
+the execution time of the two sets of actions within each 100
+tick period established by period_1. The rate_monotonic_cancel(
+period_2 ) call is performed to insure that the period_2 period
+does not expire while the task is blocked on the period_1
+period. If this cancel operation were not performed, every time
+the rate_monotonic_period( period_1, 40 ) call is executed,
+except for the initial one, a directive status of TIMEOUT is
+returned. It is important to note that every time this call is
+made, the period_1 period will be initiated immediately and the
+task will not block.
+
+If, for any reason, the task misses any deadline, the
+rate_monotonic_period directive will return the TIMEOUT
+directive status. If the above task misses its deadline, it
+will delete the rate monotonic periods and itself.
+
+@ifinfo
+@node Rate Monotonic Manager Directives, RATE_MONOTONIC_CREATE - Create a rate monotonic period, Task with Multiple Periods, Rate Monotonic Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* RATE_MONOTONIC_CREATE - Create a rate monotonic period::
+* RATE_MONOTONIC_IDENT - Get ID of a period::
+* RATE_MONOTONIC_CANCEL - Cancel a period::
+* RATE_MONOTONIC_DELETE - Delete a rate monotonic period::
+* RATE_MONOTONIC_PERIOD - Conclude current/Start next period::
+* RATE_MONOTONIC_GET_STATUS - Obtain status information on period::
+@end menu
+@end ifinfo
+
+This section details the rate monotonic manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node RATE_MONOTONIC_CREATE - Create a rate monotonic period, RATE_MONOTONIC_IDENT - Get ID of a period, Rate Monotonic Manager Directives, Rate Monotonic Manager Directives
+@end ifinfo
+@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_rate_monotonic_create(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - rate monotonic period created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{TOO_MANY} - too many periods created
+
+@subheading DESCRIPTION:
+
+This directive creates a rate monotonic period. The
+assigned rate monotonic id is returned in id. This id is used
+to access the period with other rate monotonic manager
+directives. For control and maintenance of the rate monotonic
+period, RTEMS allocates a PCB from the local PCB free pool and
+initializes it.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node RATE_MONOTONIC_IDENT - Get ID of a period, RATE_MONOTONIC_CANCEL - Cancel a period, RATE_MONOTONIC_CREATE - Create a rate monotonic period, Rate Monotonic Manager Directives
+@end ifinfo
+@subsection RATE_MONOTONIC_IDENT - Get ID of a period
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_rate_monotonic_ident(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - period identified successfully@*
+@code{INVALID_NAME} - period name not found
+
+@subheading DESCRIPTION:
+
+This directive obtains the period id associated with
+the period name to be acquired. If the period name is not
+unique, then the period id will match one of the periods with
+that name. However, this period id is not guaranteed to
+correspond to the desired period. The period id is used to
+access this period in other rate monotonic manager directives.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+@page
+@ifinfo
+@node RATE_MONOTONIC_CANCEL - Cancel a period, RATE_MONOTONIC_DELETE - Delete a rate monotonic period, RATE_MONOTONIC_IDENT - Get ID of a period, Rate Monotonic Manager Directives
+@end ifinfo
+@subsection RATE_MONOTONIC_CANCEL - Cancel a period
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_rate_monotonic_cancel(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - period canceled successfully@*
+@code{INVALID_ID} - invalid rate monotonic period id@*
+@code{NOT_OWNER_OF_RESOURCE} - rate monotonic period not created by calling task
+
+@subheading DESCRIPTION:
+
+This directive cancels the rate monotonic period id.
+This period will be reinitiated by the next invocation of
+rate_monotonic_period with id.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+The rate monotonic period specified by id must have
+been created by the calling task.
+
+@page
+@ifinfo
+@node RATE_MONOTONIC_DELETE - Delete a rate monotonic period, RATE_MONOTONIC_PERIOD - Conclude current/Start next period, RATE_MONOTONIC_CANCEL - Cancel a period, Rate Monotonic Manager Directives
+@end ifinfo
+@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_rate_monotonic_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - period deleted successfully@*
+@code{INVALID_ID} - invalid rate monotonic period id
+
+@subheading DESCRIPTION:
+
+This directive deletes the rate monotonic period
+specified by id. If the period is running, it is automatically
+canceled. The PCB for the deleted period is reclaimed by RTEMS.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+A rate monotonic period can be deleted by a task
+other than the task which created the period.
+
+@page
+@ifinfo
+@node RATE_MONOTONIC_PERIOD - Conclude current/Start next period, RATE_MONOTONIC_GET_STATUS - Obtain status information on period, RATE_MONOTONIC_DELETE - Delete a rate monotonic period, Rate Monotonic Manager Directives
+@end ifinfo
+@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_rate_monotonic_period(
+ rtems_id id,
+ rtems_interval length
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - period initiated successfully@*
+@code{INVALID_ID} - invalid rate monotonic period id@*
+@code{NOT_OWNER_OF_RESOURCE} - period not created by calling task@*
+@code{NOT_DEFINED} - period has never been initiated@*
+@code{TIMEOUT} - period has expired
+
+@subheading DESCRIPTION:
+
+This directive initiates the rate monotonic period id
+with a length of period ticks. If id is running, then the
+calling task will block for the remainder of the period before
+reinitiating the period with the specified period. If id was
+not running (either expired or never initiated), the period is
+immediately initiated and the directive returns immediately.
+
+If invoked with a period of PERIOD_STATUS ticks, the
+current state of id will be returned. The directive status
+indicates the current state of the period. This does not alter
+the state or period of the period.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be preempted.
+
+---------------------
+@page
+@ifinfo
+@node RATE_MONOTONIC_GET_STATUS - Obtain status information on period, Board Support Packages, RATE_MONOTONIC_PERIOD - Conclude current/Start next period, Rate Monotonic Manager Directives
+@end ifinfo
+@subsection RATE_MONOTONIC_GET_STATUS - Obtain status information on period
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_rate_monotonic_period(
+ rtems_id id,
+ rtems_rate_monotonic_period_status *status
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - period initiated successfully@*
+@code{INVALID_ID} - invalid rate monotonic period id@*
+@code{INVALID_ADDRESS} - invalid address of status@*
+
+@subheading DESCRIPTION:
+
+This directive returns status information associated with
+the rate monotonic period id in the following data structure:
+
+@example
+typedef struct @{
+ rtems_rate_monotonic_period_states state;
+ unsigned32 ticks_since_last_period;
+ unsigned32 ticks_executed_since_last_period;
+@} rtems_rate_monotonic_period_status;
+@end example
+
+If the period's state is RATE_MONOTONIC_INACTIVE, both
+ticks_since_last_period and ticks_executed_since_last_period
+will be set to 0. Otherwise, ticks_since_last_period will
+contain the number of clock ticks which have occurred since
+the last invocation of the rtems_rate_monotonic_period directive.
+Also in this case, the ticks_executed_since_last_period will indicate
+how much processor time the owning task has consumed since the invocation
+of the rtems_rate_monotonic_period directive.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be preempted.
diff --git a/doc/user/schedule.t b/doc/user/schedule.t
new file mode 100644
index 0000000000..5781a670b7
--- /dev/null
+++ b/doc/user/schedule.t
@@ -0,0 +1,426 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@c
+@c This figure is not included:
+@c Figure 17-1 RTEMS Task State Transitions
+@c
+
+@ifinfo
+@node Scheduling Concepts, Scheduling Concepts Introduction, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Top
+@end ifinfo
+@chapter Scheduling Concepts
+@ifinfo
+@menu
+* Scheduling Concepts Introduction::
+* Scheduling Concepts Scheduling Mechanisms::
+* Scheduling Concepts Task State Transitions::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Scheduling Concepts Introduction, Scheduling Concepts Scheduling Mechanisms, Scheduling Concepts, Scheduling Concepts
+@end ifinfo
+@section Introduction
+
+The concept of scheduling in real-time systems
+dictates the ability to provide immediate response to specific
+external events, particularly the necessity of scheduling tasks
+to run within a specified time limit after the occurrence of an
+event. For example, software embedded in life-support systems
+used to monitor hospital patients must take instant action if a
+change in the patient's status is detected.
+
+The component of RTEMS responsible for providing this
+capability is appropriately called the scheduler. The
+scheduler's sole purpose is to allocate the all important
+resource of processor time to the various tasks competing for
+attention. The RTEMS scheduler allocates the processor using a
+priority-based, preemptive algorithm augmented to provide
+round-robin characteristics within individual priority groups.
+The goal of this algorithm is to guarantee that the task which
+is executing on the processor at any point in time is the one
+with the highest priority among all tasks in the ready state.
+
+There are two common methods of accomplishing the
+mechanics of this algorithm. Both ways involve a list or chain
+of tasks in the ready state. One method is to randomly place
+tasks in the ready chain forcing the scheduler to scan the
+entire chain to determine which task receives the processor.
+The other method is to schedule the task by placing it in the
+proper place on the ready chain based on the designated
+scheduling criteria at the time it enters the ready state.
+Thus, when the processor is free, the first task on the ready
+chain is allocated the processor. RTEMS schedules tasks using
+the second method to guarantee faster response times to external
+events.
+
+@ifinfo
+@node Scheduling Concepts Scheduling Mechanisms, Task Priority and Scheduling, Scheduling Concepts Introduction, Scheduling Concepts
+@end ifinfo
+@section Scheduling Mechanisms
+@ifinfo
+@menu
+* Task Priority and Scheduling::
+* Preemption::
+* Timeslicing::
+* Manual Round-Robin::
+* Dispatching Tasks::
+@end menu
+@end ifinfo
+
+RTEMS provides four mechanisms which allow the user
+to impact the task scheduling process:
+
+@itemize @bullet
+@item user-selectable task priority level
+@item task preemption control
+@item task timeslicing control
+@item manual round-robin selection
+@end itemize
+
+Each of these methods provides a powerful capability
+to customize sets of tasks to satisfy the unique and particular
+requirements encountered in custom real-time applications.
+Although each mechanism operates independently, there is a
+precedence relationship which governs the effects of scheduling
+modifications. The evaluation order for scheduling
+characteristics is always priority, preemption mode, and
+timeslicing. When reading the descriptions of timeslicing and
+manual round-robin it is important to keep in mind that
+preemption (if enabled) of a task by higher priority tasks will
+occur as required, overriding the other factors presented in the
+description.
+
+@ifinfo
+@node Task Priority and Scheduling, Preemption, Scheduling Concepts Scheduling Mechanisms, Scheduling Concepts Scheduling Mechanisms
+@end ifinfo
+@subsection Task Priority and Scheduling
+
+The most significant of these mechanisms is the
+ability for the user to assign a priority level to each
+individual task when it is created and to alter a task's
+priority at run-time. RTEMS provides 255 priority levels.
+Level 255 is the lowest priority and level 1 is the highest.
+When a task is added to the ready chain, it is placed behind all
+other tasks of the same priority. This rule provides a
+round-robin within priority group scheduling characteristic.
+This means that in a group of equal priority tasks, tasks will
+execute in the order they become ready or FIFO order. Even
+though there are ways to manipulate and adjust task priorities,
+the most important rule to remember is:
+
+@itemize @code{ }
+@item @b{The RTEMS scheduler will always select the highest
+priority task that is ready to run when allocating the processor
+to a task.}
+@end itemize
+
+@ifinfo
+@node Preemption, Timeslicing, Task Priority and Scheduling, Scheduling Concepts Scheduling Mechanisms
+@end ifinfo
+@subsection Preemption
+
+Another way the user can alter the basic scheduling
+algorithm is by manipulating the preemption mode flag
+(PREEMPT_MASK) of individual tasks. If preemption is disabled
+for a task (NO_PREEMPT), then the task will not relinquish
+control of the processor until it terminates, blocks, or
+re-enables preemption. Even tasks which become ready to run and
+possess higher priority levels will not be allowed to execute.
+Note that the preemption setting has no effect on the manner in
+which a task is scheduled. It only applies once a task has
+control of the processor.
+
+@ifinfo
+@node Timeslicing, Manual Round-Robin, Preemption, Scheduling Concepts Scheduling Mechanisms
+@end ifinfo
+@subsection Timeslicing
+
+Timeslicing or round-robin scheduling is an
+additional method which can be used to alter the basic
+scheduling algorithm. Like preemption, timeslicing is specified
+on a task by task basis using the timeslicing mode flag
+(TIMESLICE_MASK). If timeslicing is enabled for a task
+(TIMESLICE), then RTEMS will limit the amount of time the task
+can execute before the processor is allocated to another task.
+Each tick of the real-time clock reduces the currently running
+task's timeslice. When the execution time equals the timeslice,
+RTEMS will dispatch another task of the same priority to
+execute. If there are no other tasks of the same priority ready
+to execute, then the current task is allocated an additional
+timeslice and continues to run. Remember that a higher priority
+task will preempt the task (unless preemption is disabled) as
+soon as it is ready to run, even if the task has not used up its
+entire timeslice.
+
+@ifinfo
+@node Manual Round-Robin, Dispatching Tasks, Timeslicing, Scheduling Concepts Scheduling Mechanisms
+@end ifinfo
+@subsection Manual Round-Robin
+
+The final mechanism for altering the RTEMS scheduling
+algorithm is called manual round-robin. Manual round-robin is
+invoked by using the task_wake_after directive with a time
+interval of YIELD_PROCESSOR. This allows a task to give up the
+processor and be immediately returned to the ready chain at the
+end of its priority group. If no other tasks of the same
+priority are ready to run, then the task does not lose control
+of the processor.
+
+@ifinfo
+@node Dispatching Tasks, Scheduling Concepts Task State Transitions, Manual Round-Robin, Scheduling Concepts Scheduling Mechanisms
+@end ifinfo
+@subsection Dispatching Tasks
+
+The dispatcher is the RTEMS component responsible for
+allocating the processor to a ready task. In order to allocate
+the processor to one task, it must be deallocated or retrieved
+from the task currently using it. This involves a concept
+called a context switch. To perform a context switch, the
+dispatcher saves the context of the current task and restores
+the context of the task which has been allocated to the
+processor. Saving and restoring a task's context is the
+storing/loading of all the essential information about a task to
+enable it to continue execution without any effects of the
+interruption. For example, the contents of a task's register
+set must be the same when it is given the processor as they were
+when it was taken away. All of the information that must be
+saved or restored for a context switch is located either in the
+TCB or on the task's stacks.
+
+Tasks that utilize a numeric coprocessor and are
+created with the FLOATING_POINT attribute require additional
+operations during a context switch. These additional operations
+are necessary to save and restore the floating point context of
+FLOATING_POINT tasks. To avoid unnecessary save and restore
+operations, the state of the numeric coprocessor is only saved
+when a FLOATING_POINT task is dispatched and that task was not
+the last task to utilize the coprocessor.
+
+@ifinfo
+@node Scheduling Concepts Task State Transitions, Rate Monotonic Manager, Dispatching Tasks, Scheduling Concepts
+@end ifinfo
+@section Task State Transitions
+
+Tasks in an RTEMS system must always be in one of the
+five allowable task states. These states are: executing, ready,
+blocked, dormant, and non-existent.
+
+@ifset use-ascii
+@example
+@group
+ +-------------------------------------------------------------+
+ | Non-existent |
+ | +-------------------------------------------------------+ |
+ | | | |
+ | | | |
+ | | Creating +---------+ Deleting | |
+ | | -------------------> | Dormant | -------------------> | |
+ | | +---------+ | |
+ | | | | |
+ | | Starting | | |
+ | | | | |
+ | | V Deleting | |
+ | | +-------> +-------+ -------------------> | |
+ | | Yielding / +----- | Ready | ------+ | |
+ | | / / +-------+ <--+ \ | |
+ | | / / \ \ Blocking | |
+ | | / / Dispatching Readying \ \ | |
+ | | / V \ V | |
+ | | +-----------+ Blocking +---------+ | |
+ | | | Executing | --------------> | Blocked | | |
+ | | +-----------+ +---------+ | |
+ | | | |
+ | | | |
+ | +-------------------------------------------------------+ |
+ | Non-existent |
+ +-------------------------------------------------------------+
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@c for now use the ascii version
+@example
+@group
+ +-------------------------------------------------------------+
+ | Non-existent |
+ | +-------------------------------------------------------+ |
+ | | | |
+ | | | |
+ | | Creating +---------+ Deleting | |
+ | | -------------------> | Dormant | -------------------> | |
+ | | +---------+ | |
+ | | | | |
+ | | Starting | | |
+ | | | | |
+ | | V Deleting | |
+ | | +-------> +-------+ -------------------> | |
+ | | Yielding / +----- | Ready | ------+ | |
+ | | / / +-------+ <--+ \ | |
+ | | / / \ \ Blocking | |
+ | | / / Dispatching Readying \ \ | |
+ | | / V \ V | |
+ | | +-----------+ Blocking +---------+ | |
+ | | | Executing | --------------> | Blocked | | |
+ | | +-----------+ +---------+ | |
+ | | | |
+ | | | |
+ | +-------------------------------------------------------+ |
+ | Non-existent |
+ +-------------------------------------------------------------+
+@end group
+@end example
+@tex
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<IMG SRC="states.gif" WIDTH=550 HEIGHT=400 ALT="RTEMS Task States">
+@end html
+@end ifset
+
+A task occupies the non-existent state before a
+task_create has been issued on its behalf. A task enters the
+non-existent state from any other state in the system when it is
+deleted with the task_delete directive. While a task occupies
+this state it does not have a TCB or a task ID assigned to it;
+therefore, no other tasks in the system may reference this task.
+
+When a task is created via the task_create directive
+it enters the dormant state. This state is not entered through
+any other means. Although the task exists in the system, it
+cannot actively compete for system resources. It will remain in
+the dormant state until it is started via the task_start
+directive, at which time it enters the ready state. The task is
+now permitted to be scheduled for the processor and to compete
+for other system resources.
+
+A task occupies the blocked state whenever it is
+unable to be scheduled to run. A running task may block itself
+or be blocked by other tasks in the system. The running task
+blocks itself through voluntary operations that cause the task
+to wait. The only way a task can block a task other than itself
+is with the task_suspend directive. A task enters the blocked
+state due to any of the following conditions:
+
+@itemize @bullet
+@item A task issues a task_suspend directive which blocks
+either itself or another task in the system.
+
+@item The running task issues a message_queue_receive
+directive with the wait option and the message queue is empty.
+
+@item The running task issues an event_receive directive with
+the wait option and the currently pending events do not satisfy
+the request.
+
+@item The running task issues a semaphore_obtain directive
+with the wait option and the requested semaphore is unavailable.
+
+@item The running task issues a task_wake_after directive
+which blocks the task for the given time interval. If the time
+interval specified is zero, the task yields the processor and
+remains in the ready state.
+
+@item The running task issues a task_wake_when directive which
+blocks the task until the requested date and time arrives.
+
+@item The running task issues a region_get_segment directive
+with the wait option and there is not an available segment large
+enough to satisfy the task's request.
+
+@item The running task issues a rate_monotonic_period
+directive and must wait for the specified rate monotonic period
+to conclude.
+@end itemize
+
+A blocked task may also be suspended. Therefore,
+both the suspension and the blocking condition must be removed
+before the task becomes ready to run again.
+
+A task occupies the ready state when it is able to be
+scheduled to run, but currently does not have control of the
+processor. Tasks of the same or higher priority will yield the
+processor by either becoming blocked, completing their
+timeslice, or being deleted. All tasks with the same priority
+will execute in FIFO order. A task enters the ready state due
+to any of the following conditions:
+
+@itemize @bullet
+
+@item A running task issues a task_resume directive for a task
+that is suspended and the task is not blocked waiting on any
+resource.
+
+@item A running task issues a message_queue_send,
+message_queue_broadcast, or a message_queue_urgent directive
+which posts a message to the queue on which the blocked task is
+waiting.
+
+@item A running task issues an event_send directive which
+sends an event condition to a task which is blocked waiting on
+that event condition.
+
+@item A running task issues a semaphore_release directive
+which releases the semaphore on which the blocked task is
+waiting.
+
+@item A timeout interval expires for a task which was blocked
+by a call to the task_wake_after directive.
+
+@item A timeout period expires for a task which blocked by a
+call to the task_wake_when directive.
+
+@item A running task issues a region_return_segment directive
+which releases a segment to the region on which the blocked task
+is waiting and a resulting segment is large enough to satisfy
+the task's request.
+
+@item A rate monotonic period expires for a task which blocked
+by a call to the rate_monotonic_period directive.
+
+@item A timeout interval expires for a task which was blocked
+waiting on a message, event, semaphore, or segment with a
+timeout specified.
+
+@item A running task issues a directive which deletes a
+message queue, a semaphore, or a region on which the blocked
+task is waiting.
+
+@item A running task issues a task_restart directive for the
+blocked task.
+
+@item The running task, with its preemption mode enabled, may
+be made ready by issuing any of the directives that may unblock
+a task with a higher priority. This directive may be issued
+from the running task itself or from an ISR.
+
+A ready task occupies the executing state when it has
+control of the CPU. A task enters the executing state due to
+any of the following conditions:
+
+@item The task is the highest priority ready task in the
+system.
+
+@item The running task blocks and the task is next in the
+scheduling queue. The task may be of equal priority as in
+round-robin scheduling or the task may possess the highest
+priority of the remaining ready tasks.
+
+@item The running task may reenable its preemption mode and a
+task exists in the ready queue that has a higher priority than
+the running task.
+
+@item The running task lowers its own priority and another
+task is of higher priority as a result.
+
+@item The running task raises the priority of a task above its
+own and the running task is in preemption mode.
+
+@end itemize
diff --git a/doc/user/sem.t b/doc/user/sem.t
new file mode 100644
index 0000000000..2e45af686c
--- /dev/null
+++ b/doc/user/sem.t
@@ -0,0 +1,722 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Semaphore Manager, Semaphore Manager Introduction, TIMER_RESET - Reset an interval timer, Top
+@end ifinfo
+@chapter Semaphore Manager
+@ifinfo
+@menu
+* Semaphore Manager Introduction::
+* Semaphore Manager Background::
+* Semaphore Manager Operations::
+* Semaphore Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Semaphore Manager Introduction, Semaphore Manager Background, Semaphore Manager, Semaphore Manager
+@end ifinfo
+@section Introduction
+
+The semaphore manager utilizes standard Dijkstra
+counting semaphores to provide synchronization and mutual
+exclusion capabilities. The directives provided by the
+semaphore manager are:
+
+@itemize @bullet
+@item @code{semaphore_create} - Create a semaphore
+@item @code{semaphore_ident} - Get ID of a semaphore
+@item @code{semaphore_delete} - Delete a semaphore
+@item @code{semaphore_obtain} - Acquire a semaphore
+@item @code{semaphore_release} - Release a semaphore
+@end itemize
+
+@ifinfo
+@node Semaphore Manager Background, Nested Resource Access, Semaphore Manager Introduction, Semaphore Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Nested Resource Access::
+* Priority Inversion::
+* Priority Inheritance::
+* Priority Ceiling::
+* Building a Semaphore's Attribute Set::
+* Building a SEMAPHORE_OBTAIN Option Set::
+@end menu
+@end ifinfo
+
+A semaphore can be viewed as a protected variable
+whose value can be modified only with the semaphore_create,
+semaphore_obtain, and semaphore_release directives. RTEMS
+supports both binary and counting semaphores. A binary semaphore
+is restricted to values of zero or one, while a counting
+semaphore can assume any non-negative integer value.
+
+A binary semaphore can be used to control access to a
+single resource. In particular, it can be used to enforce
+mutual exclusion for a critical section in user code. In this
+instance, the semaphore would be created with an initial count
+of one to indicate that no task is executing the critical
+section of code. Upon entry to the critical section, a task
+must issue the semaphore_obtain directive to prevent other tasks
+from entering the critical section. Upon exit from the critical
+section, the task must issue the semaphore_release directive to
+allow another task to execute the critical section.
+
+A counting semaphore can be used to control access to
+a pool of two or more resources. For example, access to three
+printers could be administered by a semaphore created with an
+initial count of three. When a task requires access to one of
+the printers, it issues the semaphore_obtain directive to obtain
+access to a printer. If a printer is not currently available,
+the task can wait for a printer to become available or return
+immediately. When the task has completed printing, it should
+issue the semaphore_release directive to allow other tasks
+access to the printer.
+
+Task synchronization may be achieved by creating a
+semaphore with an initial count of zero. One task waits for the
+arrival of another task by issuing a semaphore_obtain directive
+when it reaches a synchronization point. The other task
+performs a corresponding semaphore_release operation when it
+reaches its synchronization point, thus unblocking the pending
+task.
+
+@ifinfo
+@node Nested Resource Access, Priority Inversion, Semaphore Manager Background, Semaphore Manager Background
+@end ifinfo
+@subsection Nested Resource Access
+
+Deadlock occurs when a task owning a binary semaphore
+attempts to acquire that same semaphore and blocks as result.
+Since the semaphore is allocated to a task, it cannot be
+deleted. Therefore, the task that currently holds the semaphore
+and is also blocked waiting for that semaphore will never
+execute again.
+
+RTEMS addresses this problem by allowing the task
+holding the binary semaphore to obtain the same binary semaphore
+multiple times in a nested manner. Each semaphore_obtain must
+be accompanied with a semaphore_release. The semaphore will
+only be made available for acquisition by other tasks when the
+outermost semaphore_obtain is matched with a semaphore_release.
+
+
+@ifinfo
+@node Priority Inversion, Priority Inheritance, Nested Resource Access, Semaphore Manager Background
+@end ifinfo
+@subsection Priority Inversion
+
+Priority inversion is a form of indefinite
+postponement which is common in multitasking, preemptive
+executives with shared resources. Priority inversion occurs
+when a high priority tasks requests access to shared resource
+which is currently allocated to low priority task. The high
+priority task must block until the low priority task releases
+the resource. This problem is exacerbated when the low priority
+task is prevented from executing by one or more medium priority
+tasks. Because the low priority task is not executing, it
+cannot complete its interaction with the resource and release
+that resource. The high priority task is effectively prevented
+from executing by lower priority tasks.
+
+@ifinfo
+@node Priority Inheritance, Priority Ceiling, Priority Inversion, Semaphore Manager Background
+@end ifinfo
+@subsection Priority Inheritance
+
+Priority inheritance is an algorithm that calls for
+the lower priority task holding a resource to have its priority
+increased to that of the highest priority task blocked waiting
+for that resource. Each time a task blocks attempting to obtain
+the resource, the task holding the resource may have its
+priority increased.
+
+RTEMS supports priority inheritance for local, binary
+semaphores that use the priority task wait queue blocking
+discipline. When a task of higher priority than the task
+holding the semaphore blocks, the priority of the task holding
+the semaphore is increased to that of the blocking task. When
+the task holding the task completely releases the binary
+semaphore (i.e. not for a nested release), the holder's priority
+is restored to the value it had before any higher priority was
+inherited.
+
+The RTEMS implementation of the priority inheritance
+algorithm takes into account the scenario in which a task holds
+more than one binary semaphore. The holding task will execute
+at the priority of the higher of the highest ceiling priority or
+at the priority of the highest priority task blocked waiting for
+any of the semaphores the task holds. Only when the task
+releases ALL of the binary semaphores it holds will its priority
+be restored to the normal value.
+
+@ifinfo
+@node Priority Ceiling, Building a Semaphore's Attribute Set, Priority Inheritance, Semaphore Manager Background
+@end ifinfo
+@subsection Priority Ceiling
+
+Priority ceiling is an algorithm that calls for the
+lower priority task holding a resource to have its priority
+increased to that of the highest priority task which will EVER
+block waiting for that resource. This algorithm addresses the
+problem of priority inversion although it avoids the possibility
+of changing the priority of the task holding the resource
+multiple times. The priority ceiling algorithm will only change
+the priority of the task holding the resource a maximum of one
+time. The ceiling priority is set at creation time and must be
+the priority of the highest priority task which will ever
+attempt to acquire that semaphore.
+
+RTEMS supports priority ceiling for local, binary
+semaphores that use the priority task wait queue blocking
+discipline. When a task of lower priority than the ceiling
+priority successfully obtains the semaphore, its priority is
+raised to the ceiling priority. When the task holding the task
+completely releases the binary semaphore (i.e. not for a nested
+release), the holder's priority is restored to the value it had
+before any higher priority was put into effect.
+
+The need to identify the highest priority task which
+will attempt to obtain a particular semaphore can be a difficult
+task in a large, complicated system. Although the priority
+ceiling algorithm is more efficient than the priority
+inheritance algorithm with respect to the maximum number of task
+priority changes which may occur while a task holds a particular
+semaphore, the priority inheritance algorithm is more forgiving
+in that it does not require this apriori information.
+
+The RTEMS implementation of the priority ceiling
+algorithm takes into account the scenario in which a task holds
+more than one binary semaphore. The holding task will execute
+at the priority of the higher of the highest ceiling priority or
+at the priority of the highest priority task blocked waiting for
+any of the semaphores the task holds. Only when the task
+releases ALL of the binary semaphores it holds will its priority
+be restored to the normal value.
+
+@ifinfo
+@node Building a Semaphore's Attribute Set, Building a SEMAPHORE_OBTAIN Option Set, Priority Ceiling, Semaphore Manager Background
+@end ifinfo
+@subsection Building a Semaphore's Attribute Set
+
+In general, an attribute set is built by a bitwise OR
+of the desired attribute components. The following table lists
+the set of valid semaphore attributes:
+
+@itemize @bullet
+@item FIFO - tasks wait by FIFO (default)
+@item PRIORITY - tasks wait by priority
+@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
+@item COUNTING_SEMAPHORE - no restriction on values
+@item NO_INHERIT_PRIORITY - do not use priority inheritance (default)
+@item INHERIT_PRIORITY - use priority inheritance
+@item PRIORITY_CEILING - use priority ceiling
+@item NO_PRIORITY_CEILING - do not use priority ceiling (default)
+@item LOCAL - local task (default)
+@item GLOBAL - global task
+@end itemize
+
+Attribute values are specifically designed to be
+mutually exclusive, therefore bitwise OR and addition operations
+are equivalent as long as each attribute appears exactly once in
+the component list. An attribute listed as a default is not
+required to appear in the attribute list, although it is a good
+programming practice to specify default attributes. If all
+defaults are desired, the attribute DEFAULT_ATTRIBUTES should be
+specified on this call.
+
+This example demonstrates the attribute_set parameter
+needed to create a local semaphore with the task priority
+waiting queue discipline. The attribute_set parameter passed to
+the semaphore_create directive could be either PRIORITY or LOCAL
+| PRIORITY. The attribute_set parameter can be set to PRIORITY
+because LOCAL is the default for all created tasks. If a
+similar semaphore were to be known globally, then the
+attribute_set parameter would be GLOBAL | PRIORITY.
+
+@ifinfo
+@node Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager Operations, Building a Semaphore's Attribute Set, Semaphore Manager Background
+@end ifinfo
+@subsection Building a SEMAPHORE_OBTAIN Option Set
+
+In general, an option is built by a bitwise OR of the
+desired option components. The set of valid options for the
+semaphore_obtain directive are listed in the following table:
+
+@itemize @bullet
+@item WAIT - task will wait for semaphore (default)
+@item NO_WAIT - task should not wait
+@end itemize
+
+Option values are specifically designed to be
+mutually exclusive, therefore bitwise OR and addition operations
+are equivalent as long as each attribute appears exactly once in
+the component list. An option listed as a default is not
+required to appear in the list, although it is a good
+programming practice to specify default options. If all
+defaults are desired, the option DEFAULT_OPTIONS should be
+specified on this call.
+
+This example demonstrates the option parameter needed
+to poll for a semaphore. The option parameter passed to the
+semaphore_obtain directive should be NO_WAIT.
+
+@ifinfo
+@node Semaphore Manager Operations, Creating a Semaphore, Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Semaphore::
+* Obtaining Semaphore IDs::
+* Acquiring a Semaphore::
+* Releasing a Semaphore::
+* Deleting a Semaphore::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations, Semaphore Manager Operations
+@end ifinfo
+@subsection Creating a Semaphore
+
+The semaphore_create directive creates a binary or
+counting semaphore with a user-specified name as well as an
+initial count. If a binary semaphore is created with a count of
+zero (0) to indicate that it has been allocated, then the task
+creating the semaphore is considered the current holder of the
+semaphore. At create time the method for ordering waiting tasks
+in the semaphore's task wait queue (by FIFO or task priority) is
+specified. Additionally, the priority inheritance or priority
+ceiling algorithm may be selected for local, binary semaphores
+that use the priority task wait queue blocking discipline. If
+the priority ceiling algorithm is selected, then the highest
+priority of any task which will attempt to obtain this semaphore
+must be specified. RTEMS allocates a Semaphore Control Block
+(SMCB) from the SMCB free list. This data structure is used by
+RTEMS to manage the newly created semaphore. Also, a unique
+semaphore ID is generated and returned to the calling task.
+
+@ifinfo
+@node Obtaining Semaphore IDs, Acquiring a Semaphore, Creating a Semaphore, Semaphore Manager Operations
+@end ifinfo
+@subsection Obtaining Semaphore IDs
+
+When a semaphore is created, RTEMS generates a unique
+semaphore ID and assigns it to the created semaphore until it is
+deleted. The semaphore ID may be obtained by either of two
+methods. First, as the result of an invocation of the
+semaphore_create directive, the semaphore ID is stored in a user
+provided location. Second, the semaphore ID may be obtained
+later using the semaphore_ident directive. The semaphore ID is
+used by other semaphore manager directives to access this
+semaphore.
+
+@ifinfo
+@node Acquiring a Semaphore, Releasing a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations
+@end ifinfo
+@subsection Acquiring a Semaphore
+
+The semaphore_obtain directive is used to acquire the
+specified semaphore. A simplified version of the
+semaphore_obtain directive can be described as follows:
+
+@example
+if semaphore's count is greater than zero
+ then decrement semaphore's count
+ else wait for release of semaphore
+
+return SUCCESSFUL
+@end example
+
+When the semaphore cannot be immediately acquired,
+one of the following situations applies:
+
+@itemize @bullet
+@item By default, the calling task will wait forever to
+acquire the semaphore.
+
+@item Specifying NO_WAIT forces an immediate return with an
+error status code.
+
+@item Specifying a timeout limits the interval the task will
+wait before returning with an error status code.
+@end itemize
+
+If the task waits to acquire the semaphore, then it
+is placed in the semaphore's task wait queue in either FIFO or
+task priority order. If the task blocked waiting for a binary
+semaphore using priority inheritance and the task's priority is
+greater than that of the task currently holding the semaphore,
+then the holding task will inherit the priority of the blocking
+task. All tasks waiting on a semaphore are returned an error
+code when the semaphore is deleted.
+
+When a task successfully obtains a semaphore using
+priority ceiling and the priority ceiling for this semaphore is
+greater than that of the holder, then the holder's priority will
+be elevated.
+
+@ifinfo
+@node Releasing a Semaphore, Deleting a Semaphore, Acquiring a Semaphore, Semaphore Manager Operations
+@end ifinfo
+@subsection Releasing a Semaphore
+
+The semaphore_release directive is used to release
+the specified semaphore. A simplified version of the
+semaphore_release directive can be described as follows:
+
+@example
+if no tasks are waiting on this semaphore
+ then increment semaphore's count
+ else assign semaphore to a waiting task
+
+return SUCCESSFUL
+@end example
+
+If this is the outermost release of a binary
+semaphore that uses priority inheritance or priority ceiling and
+the task does not currently hold any other binary semaphores,
+then the task performing the semaphore_release will have its
+priority restored to its normal value.
+
+@ifinfo
+@node Deleting a Semaphore, Semaphore Manager Directives, Releasing a Semaphore, Semaphore Manager Operations
+@end ifinfo
+@subsection Deleting a Semaphore
+
+The semaphore_delete directive removes a semaphore
+from the system and frees its control block. A semaphore can be
+deleted by any local task that knows the semaphore's ID. As a
+result of this directive, all tasks blocked waiting to acquire
+the semaphore will be readied and returned a status code which
+indicates that the semaphore was deleted. Any subsequent
+references to the semaphore's name and ID are invalid.
+
+@ifinfo
+@node Semaphore Manager Directives, SEMAPHORE_CREATE - Create a semaphore, Deleting a Semaphore, Semaphore Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* SEMAPHORE_CREATE - Create a semaphore::
+* SEMAPHORE_IDENT - Get ID of a semaphore::
+* SEMAPHORE_DELETE - Delete a semaphore::
+* SEMAPHORE_OBTAIN - Acquire a semaphore::
+* SEMAPHORE_RELEASE - Release a semaphore::
+@end menu
+@end ifinfo
+
+This section details the semaphore manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node SEMAPHORE_CREATE - Create a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives, Semaphore Manager Directives
+@end ifinfo
+@subsection SEMAPHORE_CREATE - Create a semaphore
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_semaphore_create(
+ rtems_name name,
+ rtems_unsigned32 count,
+ rtems_attribute attribute_set,
+ rtems_task_priority priority_ceiling,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - semaphore created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{TOO_MANY} - too many semaphores created@*
+@code{NOT_DEFINED} - invalid attribute set@*
+@code{INVALID_NUMBER} - invalid starting count for binary semaphore@*
+@code{MP_NOT_CONFIGURED} - multiprocessing not configured@*
+@code{TOO_MANY} - too many global objects
+
+@subheading DESCRIPTION:
+
+This directive creates a semaphore which resides on
+the local node. The created semaphore has the user-defined name
+specified in name and the initial count specified in count. For
+control and maintenance of the semaphore, RTEMS allocates and
+initializes a SMCB. The RTEMS-assigned semaphore id is returned
+in id. This semaphore id is used with other semaphore related
+directives to access the semaphore.
+
+Specifying PRIORITY in attribute_set causes tasks
+waiting for a semaphore to be serviced according to task
+priority. When FIFO is selected, tasks are serviced in First
+In-First Out order.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The priority inheritance and priority ceiling
+algorithms are only supported for local, binary semaphores that
+use the priority task wait queue blocking discipline.
+
+The following semaphore attribute constants are
+defined by RTEMS:
+
+@itemize @bullet
+@item FIFO - tasks wait by FIFO (default)
+@item PRIORITY - tasks wait by priority
+@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
+@item COUNTING_SEMAPHORE - no restriction on values
+@item NO_INHERIT_PRIORITY - do not use priority inheritance (default)
+@item INHERIT_PRIORITY - use priority inheritance
+@item PRIORITY_CEILING - use priority ceiling
+@item NO_PRIORITY_CEILING - do not use priority ceiling (default)
+@item LOCAL - local task (default)
+@item GLOBAL - global task
+@end itemize
+
+
+
+Semaphores should not be made global unless remote
+tasks must interact with the created semaphore. This is to
+avoid the system overhead incurred by the creation of a global
+semaphore. When a global semaphore is created, the semaphore's
+name and id must be transmitted to every node in the system for
+insertion in the local copy of the global object table.
+
+The total number of global objects, including
+semaphores, is limited by the maximum_global_objects field in
+the Configuration Table.
+
+@page
+@ifinfo
+@node SEMAPHORE_IDENT - Get ID of a semaphore, SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_CREATE - Create a semaphore, Semaphore Manager Directives
+@end ifinfo
+@subsection SEMAPHORE_IDENT - Get ID of a semaphore
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_semaphore_ident(
+ rtems_name name,
+ rtems_unsigned32 node,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - semaphore identified successfully@*
+@code{INVALID_NAME} - semaphore name not found@*
+@code{INVALID_NODE} - invalid node id
+
+@subheading DESCRIPTION:
+
+This directive obtains the semaphore id associated
+with the semaphore name. If the semaphore name is not unique,
+then the semaphore id will match one of the semaphores with that
+name. However, this semaphore id is not guaranteed to
+correspond to the desired semaphore. The semaphore id is used
+by other semaphore related directives to access the semaphore.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+If node is SEARCH_ALL_NODES, all nodes are searched
+with the local node being searched first. All other nodes are
+searched with the lowest numbered node searched first.
+
+If node is a valid node number which does not
+represent the local node, then only the semaphores exported by
+the designated node are searched.
+
+This directive does not generate activity on remote
+nodes. It accesses only the local copy of the global object
+table.
+
+@page
+@ifinfo
+@node SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives
+@end ifinfo
+@subsection SEMAPHORE_DELETE - Delete a semaphore
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_semaphore_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - semaphore deleted successfully@*
+@code{INVALID_ID} - invalid semaphore id@*
+@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@*
+@code{RESOURCE_IN_USE} - binary semaphore is in use
+
+@subheading DESCRIPTION:
+
+This directive deletes the semaphore specified by id.
+All tasks blocked waiting to acquire the semaphore will be
+readied and returned a status code which indicates that the
+semaphore was deleted. The SMCB for this semaphore is reclaimed
+by RTEMS.
+
+@subheading NOTES:
+
+The calling task will be preempted if it is enabled
+by the task's execution mode and a higher priority local task is
+waiting on the deleted semaphore. The calling task will NOT be
+preempted if all of the tasks that are waiting on the semaphore
+are remote tasks.
+
+The calling task does not have to be the task that
+created the semaphore. Any local task that knows the semaphore
+id can delete the semaphore.
+
+When a global semaphore is deleted, the semaphore id
+must be transmitted to every node in the system for deletion
+from the local copy of the global object table.
+
+The semaphore must reside on the local node, even if
+the semaphore was created with the GLOBAL option.
+
+Proxies, used to represent remote tasks, are
+reclaimed when the semaphore is deleted.
+
+@page
+@ifinfo
+@node SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_RELEASE - Release a semaphore, SEMAPHORE_DELETE - Delete a semaphore, Semaphore Manager Directives
+@end ifinfo
+@subsection SEMAPHORE_OBTAIN - Acquire a semaphore
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_semaphore_obtain(
+ rtems_id id,
+ rtems_unsigned32 option_set,
+ rtems_interval timeout
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - semaphore obtained successfully@*
+@code{UNSATISFIED} - semaphore not available@*
+@code{TIMEOUT} - timed out waiting for semaphore@*
+@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting@*
+@code{INVALID_ID} - invalid semaphore id
+
+@subheading DESCRIPTION:
+
+This directive acquires the semaphore specified by
+id. The WAIT and NO_WAIT components of the options parameter
+indicate whether the calling task wants to wait for the
+semaphore to become available or return immediately if the
+semaphore is not currently available. With either WAIT or
+NO_WAIT, if the current semaphore count is positive, then it is
+decremented by one and the semaphore is successfully acquired by
+returning immediately with a successful return code.
+
+If the calling task chooses to return immediately and
+the current semaphore count is zero or negative, then a status
+code is returned indicating that the semaphore is not available.
+If the calling task chooses to wait for a semaphore and the
+current semaphore count is zero or negative, then it is
+decremented by one and the calling task is placed on the
+semaphore's wait queue and blocked. If the semaphore was
+created with the PRIORITY attribute, then the calling task is
+inserted into the queue according to its priority. However, if
+the semaphore was created with the FIFO attribute, then the
+calling task is placed at the rear of the wait queue. If the
+binary semaphore was created with the INHERIT_PRIORITY
+attribute, then the priority of the task currently holding the
+binary semaphore is guaranteed to be greater than or equal to
+that of the blocking task. If the binary semaphore was created
+with the PRIORITY_CEILING attribute, a task successfully obtains
+the semaphore, and the priority of that task is greater than the
+ceiling priority for this semaphore, then the priority of the
+task obtaining the semaphore is elevated to that of the ceiling.
+
+The timeout parameter specifies the maximum interval
+the calling task is willing to be blocked waiting for the
+semaphore. If it is set to NO_TIMEOUT, then the calling task
+will wait forever. If the semaphore is available or the NO_WAIT
+option component is set, then timeout is ignored.
+
+@subheading NOTES:
+The following semaphore acquisition option constants
+are defined by RTEMS:
+
+@itemize @bullet
+@item WAIT - task will wait for semaphore (default)
+@item NO_WAIT - task should not wait
+@end itemize
+
+Attempting to obtain a global semaphore which does not reside on
+the local node will generate a request to the remote node to
+access the semaphore. If the semaphore is not available and
+NO_WAIT was not specified, then the task must be blocked until
+the semaphore is released. A proxy is allocated on the remote
+node to represent the task until the semaphore is released.
+
+@page
+@ifinfo
+@node SEMAPHORE_RELEASE - Release a semaphore, Message Manager, SEMAPHORE_OBTAIN - Acquire a semaphore, Semaphore Manager Directives
+@end ifinfo
+@subsection SEMAPHORE_RELEASE - Release a semaphore
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_semaphore_release(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - semaphore released successfully@*
+@code{INVALID_ID} - invalid semaphore id@*
+@code{NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore
+
+@subheading DESCRIPTION:
+
+This directive releases the semaphore specified by
+id. The semaphore count is incremented by one. If the count is
+zero or negative, then the first task on this semaphore's wait
+queue is removed and unblocked. The unblocked task may preempt
+the running task if the running task's preemption mode is
+enabled and the unblocked task has a higher priority than the
+running task.
+
+@subheading NOTES:
+
+The calling task may be preempted if it causes a
+higher priority task to be made ready for execution.
+
+Releasing a global semaphore which does not reside on
+the local node will generate a request telling the remote node
+to release the semaphore.
+
+If the task to be unblocked resides on a different
+node from the semaphore, then the semaphore allocation is
+forwarded to the appropriate node, the waiting task is
+unblocked, and the proxy used to represent the task is reclaimed.
+
+The outermost release of a local, binary, priority
+inheritance or priority ceiling semaphore may result in the
+calling task having its priority lowered. This will occur if
+the calling task holds no other binary semaphores and it has
+inherited a higher priority.
+
diff --git a/doc/user/signal.t b/doc/user/signal.t
new file mode 100644
index 0000000000..f6a53c1967
--- /dev/null
+++ b/doc/user/signal.t
@@ -0,0 +1,354 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Signal Manager, Signal Manager Introduction, EVENT_RECEIVE - Receive event condition, Top
+@end ifinfo
+@chapter Signal Manager
+@ifinfo
+@menu
+* Signal Manager Introduction::
+* Signal Manager Background::
+* Signal Manager Operations::
+* Signal Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager
+@end ifinfo
+@section Introduction
+
+The signal manager provides the capabilities required
+for asynchronous communication. The directives provided by the
+signal manager are:
+
+@itemize @bullet
+@item @code{signal_catch} - Establish an ASR
+@item @code{signal_send} - Send signal set to a task
+@end itemize
+
+@ifinfo
+@node Signal Manager Background, Signal Manager Definitions, Signal Manager Introduction, Signal Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Signal Manager Definitions::
+* A Comparison of ASRs and ISRs::
+* Building a Signal Set::
+* Building an ASR's Mode::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Signal Manager Definitions, A Comparison of ASRs and ISRs, Signal Manager Background, Signal Manager Background
+@end ifinfo
+@subsection Signal Manager Definitions
+
+The signal manager allows a task to optionally define
+an asynchronous signal routine (ASR). An ASR is to a task what
+an ISR is to an application's set of tasks. When the processor
+is interrupted, the execution of an application is also
+interrupted and an ISR is given control. Similarly, when a
+signal is sent to a task, that task's execution path will be
+"interrupted" by the ASR. Sending a signal to a task has no
+effect on the receiving task's current execution state.
+
+A signal flag is used by a task (or ISR) to inform
+another task of the occurrence of a significant situation.
+Thirty-two signal flags are associated with each task. A
+collection of one or more signals is referred to as a signal
+set. A signal set is posted when it is directed (or sent) to a
+task. A pending signal is a signal that has been sent to a task
+with a valid ASR, but has not been processed by that task's ASR.
+
+
+@ifinfo
+@node A Comparison of ASRs and ISRs, Building a Signal Set, Signal Manager Definitions, Signal Manager Background
+@end ifinfo
+@subsection A Comparison of ASRs and ISRs
+
+The format of an ASR is similar to that of an ISR
+with the following exceptions:
+
+@itemize @bullet
+@item ISRs are scheduled by the processor hardware. ASRs are
+scheduled by RTEMS.
+
+@item ISRs do not execute in the context of a task and may
+invoke only a subset of directives. ASRs execute in the context
+of a task and may execute any directive.
+
+@item When an ISR is invoked, it is passed the vector number
+as its argument. When an ASR is invoked, it is passed the
+signal set as its argument.
+
+@item An ASR has a task mode which can be different from that
+of the task. An ISR does not execute as a task and, as a
+result, does not have a task mode.
+@end itemize
+
+@ifinfo
+@node Building a Signal Set, Building an ASR's Mode, A Comparison of ASRs and ISRs, Signal Manager Background
+@end ifinfo
+@subsection Building a Signal Set
+
+A signal set is built by a bitwise OR of the desired
+signals. The set of valid signals is SIGNAL_0 through
+SIGNAL_31. If a signal is not explicitly specified in the
+signal set, then it is not present. Signal values are
+specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as
+each signal appears exactly once in the component list.
+
+This example demonstrates the signal parameter used
+when sending the signal set consisting of SIGNAL_6, SIGNAL_15,
+and SIGNAL_31. The signal parameter provided to the signal_send
+directive should be SIGNAL_6 | SIGNAL_15 | SIGNAL_31.
+
+@ifinfo
+@node Building an ASR's Mode, Signal Manager Operations, Building a Signal Set, Signal Manager Background
+@end ifinfo
+@subsection Building an ASR's Mode
+
+In general, an ASR's mode is built by a bitwise OR of
+the desired mode components. The set of valid mode components
+is the same as those allowed with the task_create and task_mode
+directives. A complete list of mode options is provided in the
+following table:
+
+@itemize @bullet
+@item PREEMPT is masked by PREEMPT_MASK and enables preemption
+@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
+@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
+@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
+@item ASR is masked by ASR_MASK and enables ASR processing
+@item NO_ASR is masked by ASR_MASK and disables ASR processing
+@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
+@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+@end itemize
+
+Mode values are specifically designed to be mutually
+exclusive, therefore bitwise OR and addition operations are
+equivalent as long as each mode appears exactly once in the
+component list. A mode component listed as a default is not
+required to appear in the mode list, although it is a good
+programming practice to specify default components. If all
+defaults are desired, the mode DEFAULT_MODES should be specified
+on this call.
+
+This example demonstrates the mode parameter used
+with the signal_catch to establish an ASR which executes at
+interrupt level three and is non-preemptible. The mode should
+be set to INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the
+desired processor mode and interrupt level.
+
+@ifinfo
+@node Signal Manager Operations, Establishing an ASR, Building an ASR's Mode, Signal Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Establishing an ASR::
+* Sending a Signal Set::
+* Processing an ASR::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Establishing an ASR, Sending a Signal Set, Signal Manager Operations, Signal Manager Operations
+@end ifinfo
+@subsection Establishing an ASR
+
+The signal_catch directive establishes an ASR for the
+calling task. The address of the ASR and its execution mode are
+specified to this directive. The ASR's mode is distinct from
+the task's mode. For example, the task may allow preemption,
+while that task's ASR may have preemption disabled. Until a
+task calls signal_catch the first time, its ASR is invalid, and
+no signal sets can be sent to the task.
+
+A task may invalidate its ASR and discard all pending
+signals by calling signal_catch with a value of NULL for the
+ASR's address. When a task's ASR is invalid, new signal sets
+sent to this task are discarded.
+
+A task may disable ASR processing (NO_ASR) via the
+task_mode directive. When a task's ASR is disabled, the signals
+sent to it are left pending to be processed later when the ASR
+is enabled.
+
+Any directive that can be called from a task can also
+be called from an ASR. A task is only allowed one active ASR.
+Thus, each call to signal_catch replaces the previous one.
+
+Normally, signal processing is disabled for the ASR's
+execution mode, but if signal processing is enabled for the ASR,
+the ASR must be reentrant.
+
+@ifinfo
+@node Sending a Signal Set, Processing an ASR, Establishing an ASR, Signal Manager Operations
+@end ifinfo
+@subsection Sending a Signal Set
+
+The signal_send directive allows both tasks and ISRs
+to send signals to a target task. The target task and a set of
+signals are specified to the signal_send directive. The sending
+of a signal to a task has no effect on the execution state of
+that task. If the task is not the currently running task, then
+the signals are left pending and processed by the task's ASR the
+next time the task is dispatched to run. The ASR is executed
+immediately before the task is dispatched. If the currently
+running task sends a signal to itself or is sent a signal from
+an ISR, its ASR is immediately dispatched to run provided signal
+processing is enabled.
+
+If an ASR with signals enabled is preempted by
+another task or an ISR and a new signal set is sent, then a new
+copy of the ASR will be invoked, nesting the preempted ASR.
+Upon completion of processing the new signal set, control will
+return to the preempted ASR. In this situation, the ASR must be
+reentrant.
+
+Like events, identical signals sent to a task are not
+queued. In other words, sending the same signal multiple times
+to a task (without any intermediate signal processing occurring
+for the task), has the same result as sending that signal to
+that task once.
+
+@ifinfo
+@node Processing an ASR, Signal Manager Directives, Sending a Signal Set, Signal Manager Operations
+@end ifinfo
+@subsection Processing an ASR
+
+Asynchronous signals were designed to provide the
+capability to generate software interrupts. The processing of
+software interrupts parallels that of hardware interrupts. As a
+result, the differences between the formats of ASRs and ISRs is
+limited to the meaning of the single argument passed to an ASR.
+The ASR should have the following calling sequence and adhere to
+C calling conventions:
+
+@example
+rtems_asr user_routine(
+ rtems_signal_set signals
+);
+@end example
+
+When the ASR returns to RTEMS the mode and execution
+path of the interrupted task (or ASR) is restored to the context
+prior to entering the ASR.
+
+@ifinfo
+@node Signal Manager Directives, SIGNAL_CATCH - Establish an ASR, Processing an ASR, Signal Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* SIGNAL_CATCH - Establish an ASR::
+* SIGNAL_SEND - Send signal set to a task::
+@end menu
+@end ifinfo
+
+This section details the signal manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@ifinfo
+@node SIGNAL_CATCH - Establish an ASR, SIGNAL_SEND - Send signal set to a task, Signal Manager Directives, Signal Manager Directives
+@end ifinfo
+@subsection SIGNAL_CATCH - Establish an ASR
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_signal_catch(
+ rtems_asr_entry asr_handler,
+ rtems_mode mode
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - always successful
+
+@subheading DESCRIPTION:
+
+This directive establishes an asynchronous signal
+routine (ASR) for the calling task. The asr_handler parameter
+specifies the entry point of the ASR. If asr_handler is NULL,
+the ASR for the calling task is invalidated and all pending
+signals are cleared. Any signals sent to a task with an invalid
+ASR are discarded. The mode parameter specifies the execution
+mode for the ASR. This execution mode supersedes the task's
+execution mode while the ASR is executing.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+The following task mode constants are defined by RTEMS:
+
+@itemize @bullet
+@item PREEMPT is masked by PREEMPT_MASK and enables preemption
+@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
+@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
+@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
+@item ASR is masked by ASR_MASK and enables ASR processing
+@item NO_ASR is masked by ASR_MASK and disables ASR processing
+@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
+@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+@end itemize
+
+@page
+@ifinfo
+@node SIGNAL_SEND - Send signal set to a task, Partition Manager, SIGNAL_CATCH - Establish an ASR, Signal Manager Directives
+@end ifinfo
+@subsection SIGNAL_SEND - Send signal set to a task
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_signal_send(
+ rtems_id id,
+ rtems_signal_set signal_set
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - signal sent successfully@*
+@code{INVALID_ID} - task id invalid@*
+@code{NOT_DEFINED} - ASR invalid
+
+@subheading DESCRIPTION:
+
+This directive sends a signal set to the task
+specified in id. The signal_set parameter contains the signal
+set to be sent to the task.
+
+If a caller sends a signal set to a task with an
+invalid ASR, then an error code is returned to the caller. If a
+caller sends a signal set to a task whose ASR is valid but
+disabled, then the signal set will be caught and left pending
+for the ASR to process when it is enabled. If a caller sends a
+signal set to a task with an ASR that is both valid and enabled,
+then the signal set is caught and the ASR will execute the next
+time the task is dispatched to run.
+
+@subheading NOTES:
+
+Sending a signal set to a task has no effect on that
+task's state. If a signal set is sent to a blocked task, then
+the task will remain blocked and the signals will be processed
+when the task becomes the running task.
+
+Sending a signal set to a global task which does not
+reside on the local node will generate a request telling the
+remote node to send the signal set to the specified task.
+
diff --git a/doc/user/states.gif b/doc/user/states.gif
new file mode 100644
index 0000000000..cd0799ea2e
--- /dev/null
+++ b/doc/user/states.gif
Binary files differ
diff --git a/doc/user/task.t b/doc/user/task.t
new file mode 100644
index 0000000000..730bb73ad2
--- /dev/null
+++ b/doc/user/task.t
@@ -0,0 +1,1313 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Task Manager, Task Manager Introduction, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Top
+@end ifinfo
+
+@chapter Task Manager
+
+@ifinfo
+@menu
+* Task Manager Introduction::
+* Task Manager Background::
+* Task Manager Operations::
+* Task Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Task Manager Introduction, Task Manager Background, Task Manager, Task Manager
+@end ifinfo
+@section Introduction
+
+The task manager provides a comprehensive set of directives to
+create, delete, and administer tasks. The directives provided
+by the task manager are:
+
+@itemize @bullet
+@item @code{task_create} - Create a task
+@item @code{task_ident} - Get ID of a task
+@item @code{task_start} - Start a task
+@item @code{task_restart} - Restart a task
+@item @code{task_delete} - Delete a task
+@item @code{task_suspend} - Suspend a task
+@item @code{task_resume} - Resume a task
+@item @code{task_set_priority} - Set task priority
+@item @code{task_mode} - Change current task's mode
+@item @code{task_get_note} - Get task notepad entry
+@item @code{task_set_note} - Set task notepad entry
+@item @code{task_wake_after} - Wake up after interval
+@item @code{task_wake_when} - Wake up when specified
+@end itemize
+
+@ifinfo
+@node Task Manager Background, Task Definition, Task Manager Introduction, Task Manager
+@end ifinfo
+
+@section Background
+
+@ifinfo
+@menu
+* Task Definition::
+* Task Control Block::
+* Task States::
+* Task Priority::
+* Task Mode::
+* Accessing Task Arguments::
+* Floating Point Considerations::
+* Building a Task's Attribute Set::
+* Building a Mode and Mask::
+@end menu
+
+@end ifinfo
+
+@ifinfo
+@node Task Definition, Task Control Block, Task Manager Background, Task Manager Background
+@end ifinfo
+
+@subsection Task Definition
+
+Many definitions of a task have been proposed in computer
+literature. Unfortunately, none of these definitions
+encompasses all facets of the concept in a manner which is
+operating system independent. Several of the more common
+definitions are provided to enable each user to select a
+definition which best matches their own experience and
+understanding of the task concept:
+
+@itemize @bullet
+@item a "dispatchable" unit.
+
+@item an entity to which the processor is allocated.
+
+@item an atomic unit of a real-time, multiprocessor system.
+
+@item single threads of execution which concurrently compete for resources.
+
+@item a sequence of closely related computations which can execute
+concurrently with other computational sequences.
+
+@end itemize
+
+From RTEMS' perspective, a task is the smallest thread of
+execution which can compete on its own for system resources. A
+task is manifested by the existence of a task control block
+(TCB).
+
+@ifinfo
+@node Task Control Block, Task States, Task Definition, Task Manager Background
+@end ifinfo
+@subsection Task Control Block
+
+The Task Control Block (TCB) is an RTEMS defined data structure
+which contains all the information that is pertinent to the
+execution of a task. During system initialization, RTEMS
+reserves a TCB for each task configured. A TCB is allocated
+upon creation of the task and is returned to the TCB free list
+upon deletion of the task.
+
+The TCB's elements are modified as a result of system calls made
+by the application in response to external and internal stimuli.
+TCBs are the only RTEMS internal data structure that can be
+accessed by an application via user extension routines. The TCB
+contains a task's name, ID, current priority, current and
+starting states, execution mode, set of notepad locations, TCB
+user extension pointer, scheduling control structures, as well
+as data required by a blocked task.
+
+A task's context is stored in the TCB when a task switch occurs.
+When the task regains control of the processor, its context is
+restored from the TCB. When a task is restarted, the initial
+state of the task is restored from the starting context area in
+the task's TCB.
+
+@ifinfo
+@node Task States, Task Priority, Task Control Block, Task Manager Background
+@end ifinfo
+@subsection Task States
+
+A task may exist in one of the following five states:
+
+@itemize @bullet
+@item @code{executing} - Currently scheduled to the CPU
+@item @code{ready} - May be scheduled to the CPU
+@item @code{blocked} - Unable to be scheduled to the CPU
+@item @code{dormant} - Created task that is not started
+@item @code{non-existent} - Uncreated or deleted task
+@end itemize
+
+An active task may occupy the executing, ready, blocked or
+dormant state, otherwise the task is considered non-existent.
+One or more tasks may be active in the system simultaneously.
+Multiple tasks communicate, synchronize, and compete for system
+resources with each other via system calls. The multiple tasks
+appear to execute in parallel, but actually each is dispatched
+to the CPU for periods of time determined by the RTEMS
+scheduling algorithm. The scheduling of a task is based on its
+current state and priority.
+
+@ifinfo
+@node Task Priority, Task Mode, Task States, Task Manager Background
+@end ifinfo
+@subsection Task Priority
+
+A task's priority determines its importance in relation to the
+other tasks executing on the same processor. RTEMS supports 255
+levels of priority ranging from 1 to 255. Tasks of numerically
+smaller priority values are more important tasks than tasks of
+numerically larger priority values. For example, a task at
+priority level 5 is of higher privilege than a task at priority
+level 10. There is no limit to the number of tasks assigned to
+the same priority.
+
+Each task has a priority associated with it at all times. The
+initial value of this priority is assigned at task creation
+time. The priority of a task may be changed at any subsequent
+time.
+
+Priorities are used by the scheduler to determine which ready
+task will be allowed to execute. In general, the higher the
+logical priority of a task, the more likely it is to receive
+processor execution time.
+
+@ifinfo
+@node Task Mode, Accessing Task Arguments, Task Priority, Task Manager Background
+@end ifinfo
+@subsection Task Mode
+
+A task's mode is a combination of the following four components:
+
+@itemize @bullet
+@item preemption
+@item ASR processing
+@item timeslicing
+@item interrupt level
+@end itemize
+
+It is used to modify RTEMS' scheduling process and to alter the
+execution environment of the task.
+
+The preemption component allows a task to determine when control
+of the processor is relinquished. If preemption is disabled
+(NO_PREEMPT), the task will retain control of the processor as
+long as it is in the executing state -- even if a higher
+priority task is made ready. If preemption is enabled (PREEMPT)
+and a higher priority task is made ready, then the processor
+will be taken away from the current task immediately and given
+to the higher priority task.
+
+The timeslicing component is used by the RTEMS scheduler to
+determine how the processor is allocated to tasks of equal
+priority. If timeslicing is enabled (TIMESLICE), then RTEMS
+will limit the amount of time the task can execute before the
+processor is allocated to another ready task of equal priority.
+The length of the timeslice is application dependent and
+specified in the Configuration Table. If timeslicing is
+disabled (NO_TIMESLICE), then the task will be allowed to
+execute until a task of higher priority is made ready. If
+NO_PREEMPT is selected, then the timeslicing component is
+ignored by the scheduler.
+
+The asynchronous signal processing component is used to
+determine when received signals are to be processed by the task.
+ If signal processing is enabled (ASR), then signals sent to the
+task will be processed the next time the task executes. If
+signal processing is disabled (NO_ASR), then all signals
+received by the task will remain posted until signal processing
+is enabled. This component affects only tasks which have
+established a routine to process asynchronous signals.
+
+The interrupt level component is used to determine which
+interrupts will be enabled when the task is executing.
+INTERRUPT_LEVEL(n) specifies that the task will execute at
+interrupt level n.
+
+@itemize @bullet
+@item @code{PREEMPT} - enable preemption (default)
+@item @code{NO_PREEMPT} - disable preemption
+@item @code{NO_TIMESLICE} - disable timeslicing (default)
+@item @code{TIMESLICE} - enable timeslicing
+@item @code{ASR} - enable ASR processing (default)
+@item @code{NO_ASR} - disable ASR processing
+@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default)
+@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n
+@end itemize
+
+@ifinfo
+@node Accessing Task Arguments, Floating Point Considerations, Task Mode, Task Manager Background
+@end ifinfo
+@subsection Accessing Task Arguments
+
+All RTEMS tasks are invoked with a single argument which is
+specified when they are started or restarted. The argument is
+commonly used to communicate startup information to the task.
+The simplest manner in which to define a task which accesses it
+argument is:
+
+@example
+rtems_task user_task(
+ rtems_task_argument argument
+);
+@end example
+
+Application tasks requiring more information may view this
+single argument as an index into an array of parameter blocks.
+
+@ifinfo
+@node Floating Point Considerations, Building a Task's Attribute Set, Accessing Task Arguments, Task Manager Background
+@end ifinfo
+@subsection Floating Point Considerations
+
+Creating a task with the FLOATING_POINT flag results in
+additional memory being allocated for the TCB to store the state
+of the numeric coprocessor during task switches. This
+additional memory is NOT allocated for NO_FLOATING_POINT tasks.
+Saving and restoring the context of a FLOATING_POINT task takes
+longer than that of a NO_FLOATING_POINT task because of the
+relatively large amount of time required for the numeric
+coprocessor to save or restore its computational state.
+
+Since RTEMS was designed specifically for embedded military
+applications which are floating point intensive, the executive
+is optimized to avoid unnecessarily saving and restoring the
+state of the numeric coprocessor. The state of the numeric
+coprocessor is only saved when a FLOATING_POINT task is
+dispatched and that task was not the last task to utilize the
+coprocessor. In a system with only one FLOATING_POINT task, the
+state of the numeric coprocessor will never be saved or
+restored.
+
+Although the overhead imposed by FLOATING_POINT tasks is
+minimal, some applications may wish to completely avoid the
+overhead associated with FLOATING_POINT tasks and still utilize
+a numeric coprocessor. By preventing a task from being
+preempted while performing a sequence of floating point
+operations, a NO_FLOATING_POINT task can utilize the numeric
+coprocessor without incurring the overhead of a FLOATING_POINT
+context switch. This approach also avoids the allocation of a
+floating point context area. However, if this approach is taken
+by the application designer, NO tasks should be created as
+FLOATING_POINT tasks. Otherwise, the floating point context
+will not be correctly maintained because RTEMS assumes that the
+state of the numeric coprocessor will not be altered by
+NO_FLOATING_POINT tasks.
+
+If the supported processor type does not have hardware floating
+capabilities or a standard numeric coprocessor, RTEMS will not
+provide built-in support for hardware floating point on that
+processor. In this case, all tasks are considered
+NO_FLOATING_POINT whether created as FLOATING_POINT or
+NO_FLOATING_POINT tasks. A floating point emulation software
+library must be utilized for floating point operations.
+
+On some processors, it is possible to disable the floating point
+unit dynamically. If this capability is supported by the target
+processor, then RTEMS will utilize this capability to enable the
+floating point unit only for tasks which are created with the
+FLOATING_POINT attribute. The consequence of a
+NO_FLOATING_POINT task attempting to access the floating point
+unit is CPU dependent but will i general result in an exception
+condition.
+
+@ifinfo
+@node Building a Task's Attribute Set, Building a Mode and Mask, Floating Point Considerations, Task Manager Background
+@end ifinfo
+@subsection Building a Task's Attribute Set
+
+In general, an attribute set is built by a bitwise OR of the
+desired components. The set of valid task attribute components
+is listed below:
+
+@itemize @bullet
+@item @code{NO_FLOATING_POINT} - does not use coprocessor (default)
+@item @code{FLOATING_POINT} - uses numeric coprocessor
+@item @code{LOCAL} - local task (default)
+@item @code{GLOBAL} - global task
+@end itemize
+
+Attribute values are specifically designed to be mutually
+exclusive, therefore bitwise OR and addition operations are
+equivalent as long as each attribute appears exactly once in the
+component list. A component listed as a default is not required
+to appear in the component list, although it is a good
+programming practice to specify default components. If all
+defaults are desired, then DEFAULT_ATTRIBUTES should be used.
+
+This example demonstrates the attribute_set parameter needed to
+create a local task which utilizes the numeric coprocessor. The
+attribute_set parameter could be FLOATING_POINT or LOCAL |
+FLOATING_POINT. The attribute_set parameter can be set to
+FLOATING_POINT because LOCAL is the default for all created
+tasks. If the task were global and used the numeric
+coprocessor, then the attribute_set parameter would be GLOBAL |
+FLOATING_POINT.
+
+@ifinfo
+@node Building a Mode and Mask, Task Manager Operations, Building a Task's Attribute Set, Task Manager Background
+@end ifinfo
+@subsection Building a Mode and Mask
+
+In general, a mode and its corresponding mask is built by a
+bitwise OR of the desired components. The set of valid mode
+constants and each mode's corresponding mask constant is
+listed below:
+
+@ifset use-ascii
+@itemize @bullet
+@item PREEMPT is masked by PREEMPT_MASK and enables preemption
+@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
+@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
+@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
+@item ASR is masked by ASR_MASK and enables ASR processing
+@item NO_ASR is masked by ASR_MASK and disables ASR processing
+@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
+@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+@end itemize
+@end ifset
+
+@ifset use-tex
+@sp 1
+@c this is temporary
+@itemize @bullet
+@item PREEMPT is masked by PREEMPT_MASK and enables preemption
+@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
+@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
+@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
+@item ASR is masked by ASR_MASK and enables ASR processing
+@item NO_ASR is masked by ASR_MASK and disables ASR processing
+@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
+@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+
+@end itemize
+
+@tex
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=3 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
+ <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
+ <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
+<TR><TD ALIGN=center>PREEMPT</TD>
+ <TD ALIGN=center>PREEMPT_MASK</TD>
+ <TD ALIGN=center>enables preemption</TD></TR>
+<TR><TD ALIGN=center>NO_PREEMPT</TD>
+ <TD ALIGN=center>PREEMPT_MASK</TD>
+ <TD ALIGN=center>disables preemption</TD></TR>
+<TR><TD ALIGN=center>NO_TIMESLICE</TD>
+ <TD ALIGN=center>TIMESLICE_MASK</TD>
+ <TD ALIGN=center>disables timeslicing</TD></TR>
+<TR><TD ALIGN=center>TIMESLICE</TD>
+ <TD ALIGN=center>TIMESLICE_MASK</TD>
+ <TD ALIGN=center>enables timeslicing</TD></TR>
+<TR><TD ALIGN=center>ASR</TD>
+ <TD ALIGN=center>ASR_MASK</TD>
+ <TD ALIGN=center>enables ASR processing</TD></TR>
+<TR><TD ALIGN=center>NO_ASR</TD>
+ <TD ALIGN=center>ASR_MASK</TD>
+ <TD ALIGN=center>disables ASR processing</TD></TR>
+<TR><TD ALIGN=center>INTERRUPT_LEVEL(0)</TD>
+ <TD ALIGN=center>INTERRUPT_MASK</TD>
+ <TD ALIGN=center>enables all interrupts</TD></TR>
+<TR><TD ALIGN=center>INTERRUPT_LEVEL(n)</TD>
+ <TD ALIGN=center>INTERRUPT_MASK</TD>
+ <TD ALIGN=center>sets interrupts level n</TD></TR>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+
+
+
+Mode values are specifically designed to be mutually exclusive,
+therefore bitwise OR and addition operations are equivalent as
+long as each mode appears exactly once in the component list. A
+mode component listed as a default is not required to appear in
+the mode component list, although it is a good programming
+practice to specify default components. If all defaults are
+desired, the mode DEFAULT_MODES and the mask ALL_MODE_MASKS
+should be used.
+
+The following example demonstrates the mode and mask parameters
+used with the task_mode directive to place a task at interrupt
+level 3 and make it non-preemptible. The mode should be set to
+INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the desired
+preemption mode and interrupt level, while the mask parameter
+should be set to INTERRUPT_MASK | NO_PREEMPT_MASK to indicate
+that the calling task's interrupt level and preemption mode are
+being altered.
+
+@ifinfo
+@node Task Manager Operations, Creating Tasks, Building a Mode and Mask, Task Manager
+@end ifinfo
+
+@section Operations
+
+@ifinfo
+@menu
+* Creating Tasks::
+* Obtaining Task IDs::
+* Starting and Restarting Tasks::
+* Suspending and Resuming Tasks::
+* Delaying the Currently Executing Task::
+* Changing Task Priority::
+* Changing Task Mode::
+* Notepad Locations::
+* Task Deletion::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating Tasks, Obtaining Task IDs, Task Manager Operations, Task Manager Operations
+@end ifinfo
+@subsection Creating Tasks
+
+The task_create directive creates a task by allocating a task
+control block, assigning the task a user-specified name,
+allocating it a stack and floating point context area, setting a
+user-specified initial priority, setting a user-specified
+initial mode, and assigning it a task ID. Newly created tasks
+are initially placed in the dormant state. All RTEMS tasks
+execute in the most privileged mode of the processor.
+
+@ifinfo
+@node Obtaining Task IDs, Starting and Restarting Tasks, Creating Tasks, Task Manager Operations
+@end ifinfo
+@subsection Obtaining Task IDs
+
+When a task is created, RTEMS generates a unique task ID and
+assigns it to the created task until it is deleted. The task ID
+may be obtained by either of two methods. First, as the result
+of an invocation of the task_create directive, the task ID is
+stored in a user provided location. Second, the task ID may be
+obtained later using the task_ident directive. The task ID is
+used by other directives to manipulate this task.
+
+@ifinfo
+@node Starting and Restarting Tasks, Suspending and Resuming Tasks, Obtaining Task IDs, Task Manager Operations
+@end ifinfo
+@subsection Starting and Restarting Tasks
+
+The task_start directive is used to place a dormant task in the
+ready state. This enables the task to compete, based on its
+current priority, for the processor and other system resources.
+Any actions, such as suspension or change of priority, performed
+on a task prior to starting it are nullified when the task is
+started.
+
+With the task_start directive the user specifies the task's
+starting address and argument. The argument is used to
+communicate some startup information to the task. As part of
+this directive, RTEMS initializes the task's stack based upon
+the task's initial execution mode and start address. The
+starting argument is passed to the task in accordance with the
+target processor's calling convention.
+
+The task_restart directive restarts a task at its initial
+starting address with its original priority and execution mode,
+but with a possibly different argument. The new argument may be
+used to distinguish between the original invocation of the task
+and subsequent invocations. The task's stack and control block
+are modified to reflect their original creation values.
+Although references to resources that have been requested are
+cleared, resources allocated by the task are NOT automatically
+returned to RTEMS. A task cannot be restarted unless it has
+previously been started (i.e. dormant tasks cannot be
+restarted). All restarted tasks are placed in the ready state.
+
+@ifinfo
+@node Suspending and Resuming Tasks, Delaying the Currently Executing Task, Starting and Restarting Tasks, Task Manager Operations
+@end ifinfo
+@subsection Suspending and Resuming Tasks
+
+The task_suspend directive is used to place either the caller or
+another task into a suspended state. The task remains suspended
+until a task_resume directive is issued. This implies that a
+task may be suspended as well as blocked waiting either to
+acquire a resource or for the expiration of a timer.
+
+The task_resume directive is used to remove another task from
+the suspended state. If the task is not also blocked, resuming
+it will place it in the ready state, allowing it to once again
+compete for the processor and resources. If the task was
+blocked as well as suspended, this directive clears the
+suspension and leaves the task in the blocked state.
+
+@ifinfo
+@node Delaying the Currently Executing Task, Changing Task Priority, Suspending and Resuming Tasks, Task Manager Operations
+@end ifinfo
+@subsection Delaying the Currently Executing Task
+
+The task_wake_after directive creates a sleep timer which allows
+a task to go to sleep for a specified interval. The task is
+blocked until the delay interval has elapsed, at which time the
+task is unblocked. A task calling the task_wake_after directive
+with a delay interval of YIELD_PROCESSOR ticks will yield the
+processor to any other ready task of equal or greater priority
+and remain ready to execute.
+
+The task_wake_when directive creates a sleep timer which allows
+a task to go to sleep until a specified date and time. The
+calling task is blocked until the specified date and time has
+occurred, at which time the task is unblocked.
+
+@ifinfo
+@node Changing Task Priority, Changing Task Mode, Delaying the Currently Executing Task, Task Manager Operations
+@end ifinfo
+@subsection Changing Task Priority
+
+The task_set_priority directive is used to obtain or change the
+current priority of either the calling task or another task. If
+the new priority requested is CURRENT_PRIORITY or the task's
+actual priority, then the current priority will be returned and
+the task's priority will remain unchanged. If the task's
+priority is altered, then the task will be scheduled according
+to its new priority.
+
+The task_restart directive resets the priority of a task to its
+original value.
+
+@ifinfo
+@node Changing Task Mode, Notepad Locations, Changing Task Priority, Task Manager Operations
+@end ifinfo
+@subsection Changing Task Mode
+
+The task_mode directive is used to obtain or change the current
+execution mode of the calling task. A task's execution mode is
+used to enable preemption, timeslicing, ASR processing, and to
+set the task's interrupt level.
+
+The task_restart directive resets the mode of a task to its
+original value.
+
+@ifinfo
+@node Notepad Locations, Task Deletion, Changing Task Mode, Task Manager Operations
+@end ifinfo
+@subsection Notepad Locations
+
+RTEMS provides sixteen notepad locations for each task. Each
+notepad location may contain a note consisting of four bytes of
+information. RTEMS provides two directives, task_set_note and
+task_get_note, that enable a user to access and change the
+notepad locations. The task_set_note directive enables the user
+to set a task's notepad entry to a specified note. The
+task_get_note directive allows the user to obtain the note
+contained in any one of the sixteen notepads of a specified task.
+
+@ifinfo
+@node Task Deletion, Task Manager Directives, Notepad Locations, Task Manager Operations
+@end ifinfo
+@subsection Task Deletion
+
+RTEMS provides the task_delete directive to allow a task to
+delete itself or any other task. This directive removes all
+RTEMS references to the task, frees the task's control block,
+removes it from resource wait queues, and deallocates its stack
+as well as the optional floating point context. The task's name
+and ID become inactive at this time, and any subsequent
+references to either of them is invalid. In fact, RTEMS may
+reuse the task ID for another task which is created later in the
+application.
+
+Unexpired delay timers (i.e. those used by task_wake_after and
+task_wake_when) and timeout timers associated with the task are
+automatically deleted, however, other resources dynamically
+allocated by the task are NOT automatically returned to RTEMS.
+Therefore, before a task is deleted, all of its dynamically
+allocated resources should be deallocated by the user. This may
+be accomplished by instructing the task to delete itself rather
+than directly deleting the task. Other tasks may instruct a
+task to delete itself by sending a "delete self" message, event,
+or signal, or by restarting the task with special arguments
+which instruct the task to delete itself.
+
+@ifinfo
+@node Task Manager Directives, TASK_CREATE - Create a task, Task Deletion, Task Manager
+@end ifinfo
+
+@section Directives
+
+@ifinfo
+@menu
+* TASK_CREATE - Create a task::
+* TASK_IDENT - Get ID of a task::
+* TASK_START - Start a task::
+* TASK_RESTART - Restart a task::
+* TASK_DELETE - Delete a task::
+* TASK_SUSPEND - Suspend a task::
+* TASK_RESUME - Resume a task::
+* TASK_SET_PRIORITY - Set task priority::
+* TASK_MODE - Change current task's mode::
+* TASK_GET_NOTE - Get task notepad entry::
+* TASK_SET_NOTE - Set task notepad entry::
+* TASK_WAKE_AFTER - Wake up after interval::
+* TASK_WAKE_WHEN - Wake up when specified::
+@end menu
+@end ifinfo
+
+This section details the task manager's directives. A
+subsection is dedicated to each of this manager's directives and
+describes the calling sequence, related constants, usage, and
+status codes.
+
+@page
+
+@ifinfo
+@node TASK_CREATE - Create a task, TASK_IDENT - Get ID of a task, Task Manager Directives, Task Manager Directives
+@end ifinfo
+@subsection TASK_CREATE - Create a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_create(
+ rtems_name name,
+ rtems_task_priority initial_priority,
+ rtems_unsigned32 stack_size,
+ rtems_mode initial_modes,
+ rtems_attribute attribute_set,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task created successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{INVALID_SIZE} - stack too small@*
+@code{INVALID_PRIORITY} - invalid task priority@*
+@code{MP_NOT_CONFIGURED} - multiprocessing not configured@*
+@code{TOO_MANY} - too many tasks created@*
+@code{UNSATISFIED} - not enough memory for stack/FP context@*
+@code{TOO_MANY} - too many global objects
+
+@subheading DESCRIPTION:
+This directive creates a task which resides on the local node.
+It allocates and initializes a TCB, a stack, and an optional
+floating point context area. The mode parameter contains values
+which sets the task's initial execution mode. The
+FLOATING_POINT attribute should be specified if the created task
+is to use a numeric coprocessor. For performance reasons, it is
+recommended that tasks not using the numeric coprocessor should
+specify the NO_FLOATING_POINT attribute. If the GLOBAL
+attribute is specified, the task can be accessed from remote
+nodes. The task id, returned in id, is used in other task
+related directives to access the task. When created, a task is
+placed in the dormant state and can only be made ready to
+execute using the directive task_start.
+
+@subheading NOTES:
+This directive will not cause the calling task to be preempted.
+
+Valid task priorities range from a high of 1 to a low of 255.
+
+RTEMS supports a maximum of 256 interrupt levels which are
+mapped onto the interrupt levels actually supported by the
+target processor.
+
+The requested stack size should be at least MINIMUM_STACK_SIZE
+bytes. The value of MINIMUM_STACK_SIZE is processor dependent.
+Application developers should consider the stack usage of the
+device drivers when calculating the stack size required for
+tasks which utilize the driver.
+
+The following task attribute constants are defined by RTEMS:
+
+@itemize @bullet
+@item @code{NO_FLOATING_POINT} - does not use coprocessor (default)
+@item @code{FLOATING_POINT} - uses numeric coprocessor
+@item @code{LOCAL} - local task (default)
+@item @code{GLOBAL} - global task
+@end itemize
+
+The following task mode constants are defined by RTEMS:
+
+@itemize @bullet
+@item @code{PREEMPT} - enable preemption (default)
+@item @code{NO_PREEMPT} - disable preemption
+@item @code{NO_TIMESLICE} - disable timeslicing (default)
+@item @code{TIMESLICE} - enable timeslicing
+@item @code{ASR} - enable ASR processing (default)
+@item @code{NO_ASR} - disable ASR processing
+@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default)
+@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n
+@end itemize
+
+Tasks should not be made global unless remote tasks must
+interact with them. This avoids the system overhead incurred by
+the creation of a global task. When a global task is created,
+the task's name and id must be transmitted to every node in the
+system for insertion in the local copy of the global object
+table.
+
+The total number of global objects, including tasks, is limited
+by the maximum_global_objects field in the Configuration Table.
+
+@page
+
+@ifinfo
+@node TASK_IDENT - Get ID of a task, TASK_START - Start a task, TASK_CREATE - Create a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_IDENT - Get ID of a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_ident(
+ rtems_name name,
+ rtems_unsigned32 node,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task identified successfully@*
+@code{INVALID_NAME} - invalid task name@*
+@code{INVALID_NODE} - invalid node id
+
+@subheading DESCRIPTION:
+This directive obtains the task id associated with the task name
+specified in name. A task may obtain its own id by specifying
+SELF or its own task name in name. If the task name is not
+unique, then the task id returned will match one of the tasks
+with that name. However, this task id is not guaranteed to
+correspond to the desired task. The task id, returned in id, is
+used in other task related directives to access the task.
+
+@subheading NOTES:
+This directive will not cause the running task to be preempted.
+
+If node is SEARCH_ALL_NODES, all nodes are searched with the
+local node being searched first. All other nodes are searched
+with the lowest numbered node searched first.
+
+If node is a valid node number which does not represent the
+local node, then only the tasks exported by the designated node
+are searched.
+
+This directive does not generate activity on remote nodes. It
+accesses only the local copy of the global object table.
+
+@page
+
+@ifinfo
+@node TASK_START - Start a task, TASK_RESTART - Restart a task, TASK_IDENT - Get ID of a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_START - Start a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_start(
+ rtems_id id,
+ rtems_task_entry entry_point,
+ rtems_task_argument argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - ask started successfully@*
+@code{INVALID_ADDRESS} - invalid task entry point@*
+@code{INVALID_ID} - invalid task id@*
+@code{INCORRECT_STATE} - task not in the dormant state@*
+@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task
+
+@subheading DESCRIPTION:
+This directive readies the task, specified by tid, for execution
+based on the priority and execution mode specified when the task
+was created. The starting address of the task is given in
+entry_point. The task's starting argument is contained in
+argument. This argument can be a single value or used as an
+index into an array of parameter blocks.
+
+@subheading NOTES:
+The calling task will be preempted if its preemption mode is
+enabled and the task being started has a higher priority.
+
+Any actions performed on a dormant task such as suspension or
+change of priority are nullified when the task is initiated via
+the task_start directive.
+
+@page
+
+@ifinfo
+@node TASK_RESTART - Restart a task, TASK_DELETE - Delete a task, TASK_START - Start a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_RESTART - Restart a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_restart(
+ rtems_id id,
+ rtems_task_argument argument
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task restarted successfully@*
+@code{INVALID_ID} - task id invalid@*
+@code{INCORRECT_STATE} - task never started@*
+@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
+
+@subheading DESCRIPTION:
+This directive resets the task specified by id to begin
+execution at its original starting address. The task's priority
+and execution mode are set to the original creation values. If
+the task is currently blocked, RTEMS automatically makes the
+task ready. A task can be restarted from any state, except the
+dormant state.
+
+The task's starting argument is contained in argument. This
+argument can be a single value or an index into an array of
+parameter blocks. This new argument may be used to distinguish
+between the initial task_start of the task and any ensuing calls
+to task_restart of the task. This can be beneficial in deleting
+a task. Instead of deleting a task using the task_delete
+directive, a task can delete another task by restarting that
+task, and allowing that task to release resources back to RTEMS
+and then delete itself.
+
+@subheading NOTES:
+If id is SELF, the calling task will be restarted and will not
+return from this directive.
+
+The calling task will be preempted if its preemption mode is
+enabled and the task being restarted has a higher priority.
+
+The task must reside on the local node, even if the task was
+created with the GLOBAL option.
+
+@page
+
+@ifinfo
+@node TASK_DELETE - Delete a task, TASK_SUSPEND - Suspend a task, TASK_RESTART - Restart a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_DELETE - Delete a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task restarted successfully@*
+@code{INVALID_ID} - task id invalid@*
+@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
+
+@subheading DESCRIPTION:
+This directive deletes a task, either the calling task or
+another task, as specified by id. RTEMS stops the execution of
+the task and reclaims the stack memory, any allocated delay or
+timeout timers, the TCB, and, if the task is FLOATING_POINT, its
+floating point context area. RTEMS does not reclaim the
+following resources: region segments, partition buffers,
+semaphores, timers, or rate monotonic periods.
+
+@subheading NOTES:
+A task is responsible for releasing its resources back to RTEMS
+before deletion. To insure proper deallocation of resources, a
+task should not be deleted unless it is unable to execute or
+does not hold any RTEMS resources. If a task holds RTEMS
+resources, the task should be allowed to deallocate its
+resources before deletion. A task can be directed to release
+its resources and delete itself by restarting it with a special
+argument or by sending it a message, an event, or a signal.
+
+Deletion of the current task (SELF) will force RTEMS to select
+another task to execute.
+
+When a global task is deleted, the task id must be transmitted
+to every node in the system for deletion from the local copy of
+the global object table.
+
+The task must reside on the local node, even if the task was
+created with the GLOBAL option.
+
+@page
+
+@ifinfo
+@node TASK_SUSPEND - Suspend a task, TASK_RESUME - Resume a task, TASK_DELETE - Delete a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_SUSPEND - Suspend a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_suspend(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task restarted successfully@*
+@code{INVALID_ID} - task id invalid@*
+@code{ALREADY_SUSPENDED} - task already suspended
+
+@subheading DESCRIPTION:
+This directive suspends the task specified by id from further
+execution by placing it in the suspended state. This state is
+additive to any other blocked state that the task may already be
+in. The task will not execute again until another task issues
+the task_resume directive for this task and any blocked state
+has been removed.
+
+@subheading NOTES:
+The requesting task can suspend itself by specifying SELF as id.
+In this case, the task will be suspended and a successful
+return code will be returned when the task is resumed.
+
+Suspending a global task which does not reside on the local node
+will generate a request to the remote node to suspend the
+specified task.
+
+@page
+
+@ifinfo
+@node TASK_RESUME - Resume a task, TASK_SET_PRIORITY - Set task priority, TASK_SUSPEND - Suspend a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_RESUME - Resume a task
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_resume(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task restarted successfully@*
+@code{INVALID_ID} - task id invalid@*
+@code{INCORRECT_STATE} - task not suspended
+
+@subheading DESCRIPTION:
+This directive removes the task specified by id from the
+suspended state. If the task is in the ready state after the
+suspension is removed, then it will be scheduled to run. If the
+task is still in a blocked state after the suspension is
+removed, then it will remain in that blocked state.
+
+@subheading NOTES:
+The running task may be preempted if its preemption mode is
+enabled and the local task being resumed has a higher priority.
+
+Resuming a global task which does not reside on the local node
+will generate a request to the remote node to resume the
+specified task.
+
+@page
+
+@ifinfo
+@node TASK_SET_PRIORITY - Set task priority, TASK_MODE - Change current task's mode, TASK_RESUME - Resume a task, Task Manager Directives
+@end ifinfo
+@subsection TASK_SET_PRIORITY - Set task priority
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_set_priority(
+ rtems_id id,
+ rtems_task_priority new_priority,
+ rtems_task_priority *old_priority
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task priority set successfully@*
+@code{INVALID_ID} - invalid task id@*
+@code{INVALID_PRIORITY} - invalid task priority
+
+@subheading DESCRIPTION:
+This directive manipulates the priority of the task specified by
+id. An id of SELF is used to indicate the calling task. When
+new_priority is not equal to CURRENT_PRIORITY, the specified
+task's previous priority is returned in old_priority. When
+new_priority is CURRENT_PRIORITY, the specified task's current
+priority is returned in old_priority. Valid priorities range
+from a high of 1 to a low of 255.
+
+@subheading NOTES:
+The calling task may be preempted if its preemption mode is
+enabled and it lowers its own priority or raises another task's
+priority.
+
+Setting the priority of a global task which does not reside on
+the local node will generate a request to the remote node to
+change the priority of the specified task.
+
+If the task specified by id is currently holding any binary
+semaphores which use the priority inheritance algorithm, then
+the task's priority cannot be lowered immediately. If the
+task's priority were lowered immediately, then priority
+inversion results. The requested lowering of the task's
+priority will occur when the task has released all priority
+inheritance binary semaphores. The task's priority can be
+increased regardless of the task's use of priority inheritance
+binary semaphores.
+
+@page
+
+@ifinfo
+@node TASK_MODE - Change current task's mode, TASK_GET_NOTE - Get task notepad entry, TASK_SET_PRIORITY - Set task priority, Task Manager Directives
+@end ifinfo
+@subsection TASK_MODE - Change current task's mode
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_mode(
+ rtems_mode mode_set,
+ rtems_mode mask,
+ rtems_mode *previous_mode_set
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task mode set successfully
+
+@subheading DESCRIPTION:
+This directive manipulates the execution mode of the calling
+task. A task's execution mode enables and disables preemption,
+timeslicing, asynchronous signal processing, as well as
+specifying the current interrupt level. To modify an execution
+mode, the mode class(es) to be changed must be specified in the
+mask parameter and the desired mode(s) must be specified in the
+mode parameter.
+
+@subheading NOTES:
+The calling task will be preempted if it enables preemption and
+a higher priority task is ready to run.
+
+Enabling timeslicing has no effect if preemption is enabled.
+
+A task can obtain its current execution mode, without modifying
+it, by calling this directive with a mask value of CURRENT_MODE.
+
+To temporarily disable the processing of a valid ASR, a task
+should call this directive with the NO_ASR indicator specified
+in mode.
+
+The set of task mode constants and each mode's corresponding
+mask constant is provided in the following table:
+
+@ifset use-ascii
+@itemize @bullet
+@item PREEMPT is masked by PREEMPT_MASK and enables preemption
+@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
+@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
+@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
+@item ASR is masked by ASR_MASK and enables ASR processing
+@item NO_ASR is masked by ASR_MASK and disables ASR processing
+@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
+@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+
+@end itemize
+@end ifset
+
+@ifset use-tex
+@sp 1
+@c this is temporary
+@itemize @bullet
+@item PREEMPT is masked by PREEMPT_MASK and enables preemption
+@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
+@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
+@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
+@item ASR is masked by ASR_MASK and enables ASR processing
+@item NO_ASR is masked by ASR_MASK and disables ASR processing
+@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
+@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+
+@end itemize
+
+@tex
+@end tex
+@end ifset
+
+@ifset use-html
+@html
+<CENTER>
+ <TABLE COLS=3 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
+ <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
+ <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
+<TR><TD ALIGN=center>PREEMPT</TD>
+ <TD ALIGN=center>PREEMPT_MASK</TD>
+ <TD ALIGN=center>enables preemption</TD></TR>
+<TR><TD ALIGN=center>NO_PREEMPT</TD>
+ <TD ALIGN=center>PREEMPT_MASK</TD>
+ <TD ALIGN=center>disables preemption</TD></TR>
+<TR><TD ALIGN=center>NO_TIMESLICE</TD>
+ <TD ALIGN=center>TIMESLICE_MASK</TD>
+ <TD ALIGN=center>disables timeslicing</TD></TR>
+<TR><TD ALIGN=center>TIMESLICE</TD>
+ <TD ALIGN=center>TIMESLICE_MASK</TD>
+ <TD ALIGN=center>enables timeslicing</TD></TR>
+<TR><TD ALIGN=center>ASR</TD>
+ <TD ALIGN=center>ASR_MASK</TD>
+ <TD ALIGN=center>enables ASR processing</TD></TR>
+<TR><TD ALIGN=center>NO_ASR</TD>
+ <TD ALIGN=center>ASR_MASK</TD>
+ <TD ALIGN=center>disables ASR processing</TD></TR>
+<TR><TD ALIGN=center>INTERRUPT_LEVEL(0)</TD>
+ <TD ALIGN=center>INTERRUPT_MASK</TD>
+ <TD ALIGN=center>enables all interrupts</TD></TR>
+<TR><TD ALIGN=center>INTERRUPT_LEVEL(n)</TD>
+ <TD ALIGN=center>INTERRUPT_MASK</TD>
+ <TD ALIGN=center>sets interrupts level n</TD></TR>
+ </TABLE>
+</CENTER>
+@end html
+@end ifset
+
+@page
+
+@ifinfo
+@node TASK_GET_NOTE - Get task notepad entry, TASK_SET_NOTE - Set task notepad entry, TASK_MODE - Change current task's mode, Task Manager Directives
+@end ifinfo
+@subsection TASK_GET_NOTE - Get task notepad entry
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_get_note(
+ rtems_id id,
+ rtems_unsigned32 notepad,
+ rtems_unsigned32 *note
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - note obtained successfully@*
+@code{INVALID_ID} - invalid task id@*
+@code{INVALID_NUMBER} - invalid notepad location
+
+@subheading DESCRIPTION:
+This directive returns the note contained in the notepad
+location of the task specified by id.
+
+@subheading NOTES:
+This directive will not cause the running task to be preempted.
+
+If id is set to SELF, the calling task accesses its own notepad.
+
+@c This version of the paragraph avoids the overfull hbox error.
+@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
+@c sixteen notepad locations.
+
+The sixteen notepad locations can be accessed using the constants
+NOTEPAD_0 through NOTEPAD_15.
+
+Getting a note of a global task which does not reside on the
+local node will generate a request to the remote node to obtain
+the notepad entry of the specified task.
+
+@page
+
+@ifinfo
+@node TASK_SET_NOTE - Set task notepad entry, TASK_WAKE_AFTER - Wake up after interval, TASK_GET_NOTE - Get task notepad entry, Task Manager Directives
+@end ifinfo
+@subsection TASK_SET_NOTE - Set task notepad entry
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_set_note(
+ rtems_id id,
+ rtems_unsigned32 notepad,
+ rtems_unsigned32 note
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - task's note set successfully@*
+@code{INVALID_ID} - invalid task id@*
+@code{INVALID_NUMBER} - invalid notepad location
+
+@subheading DESCRIPTION:
+This directive sets the notepad entry for the task specified by
+id to the value note.
+
+@subheading NOTES:
+If id is set to SELF, the calling task accesses its own notepad
+locations.
+
+This directive will not cause the running task to be preempted.
+
+@c This version of the paragraph avoids the overfull hbox error.
+@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
+@c sixteen notepad locations.
+
+The sixteen notepad locations can be accessed using the constants
+NOTEPAD_0 through NOTEPAD_15.
+
+Setting a notepad location of a global task which does not
+reside on the local node will generate a request to the remote
+node to set the specified notepad entry.
+
+@page
+
+@ifinfo
+@node TASK_WAKE_AFTER - Wake up after interval, TASK_WAKE_WHEN - Wake up when specified, TASK_SET_NOTE - Set task notepad entry, Task Manager Directives
+@end ifinfo
+@subsection TASK_WAKE_AFTER - Wake up after interval
+
+@subheading CALLING SEQUENCE:
+@example
+rtems_status_code rtems_task_wake_after(
+ rtems_interval ticks
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - always successful
+
+@subheading DESCRIPTION:
+This directive blocks the calling task for the specified number
+of system clock ticks. When the requested interval has elapsed,
+the task is made ready. The clock_tick directive automatically
+updates the delay period.
+
+@subheading NOTES:
+Setting the system date and time with the clock_set directive
+has no effect on a task_wake_after blocked task.
+
+A task may give up the processor and remain in the ready state
+by specifying a value of YIELD_PROCESSOR in ticks.
+
+The maximum timer interval that can be specified is the maximum
+value which can be represented by the rtems_unsigned32 type.
+
+@page
+
+@ifinfo
+@node TASK_WAKE_WHEN - Wake up when specified, Interrupt Manager, TASK_WAKE_AFTER - Wake up after interval, Task Manager Directives
+@end ifinfo
+@subsection TASK_WAKE_WHEN - Wake up when specified
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_task_wake_when(
+ rtems_time_of_day *time_buffer
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - awakened at date/time successfully@*
+@code{INVALID_TIME_OF_DAY} - invalid time buffer@*
+@code{NOT_DEFINED} - system date and time is not set
+
+@subheading DESCRIPTION:
+This directive blocks a task until the date and time specified
+in time_buffer. At the requested date and time, the calling
+task will be unblocked and made ready to execute.
+
+@subheading NOTES:
+The ticks portion of time_buffer structure is ignored. The
+timing granularity of this directive is a second.
diff --git a/doc/user/timer.t b/doc/user/timer.t
new file mode 100644
index 0000000000..d0dcb8ba71
--- /dev/null
+++ b/doc/user/timer.t
@@ -0,0 +1,441 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node Timer Manager, Timer Manager Introduction, CLOCK_TICK - Announce a clock tick, Top
+@end ifinfo
+@chapter Timer Manager
+@ifinfo
+@menu
+* Timer Manager Introduction::
+* Timer Manager Background::
+* Timer Manager Operations::
+* Timer Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Timer Manager Introduction, Timer Manager Background, Timer Manager, Timer Manager
+@end ifinfo
+@section Introduction
+
+The timer manager provides support for timer
+facilities. The directives provided by the timer manager are:
+
+@itemize @bullet
+@item @code{timer_create} - Create a timer
+@item @code{timer_ident} - Get ID of a timer
+@item @code{timer_cancel} - Cancel a timer
+@item @code{timer_delete} - Delete a timer
+@item @code{timer_fire_after} - Fire timer after interval
+@item @code{timer_fire_when} - Fire timer when specified
+@item @code{timer_reset} - Reset an interval timer
+@end itemize
+
+
+@ifinfo
+@node Timer Manager Background, Timers, Timer Manager Introduction, Timer Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Timers::
+* Timer Service Routines::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Timers, Timer Service Routines, Timer Manager Background, Timer Manager Background
+@end ifinfo
+@subsection Timers
+
+A timer is an RTEMS object which allows the
+application to schedule operations to occur at specific times in
+the future. User supplied timer service routines are invoked by
+the clock_tick directive when the timer fires. Timer service
+routines may perform any operations or directives which normally
+would be performed by the application code which invoked the
+clock_tick directive.
+
+The timer can be used to implement watchdog routines
+which only fire to denote that an application error has
+occurred. The timer is reset at specific points in the
+application to insure that the watchdog does not fire. Thus, if
+the application does not reset the watchdog timer, then the
+timer service routine will fire to indicate that the application
+has failed to reach a reset point. This use of a timer is
+sometimes referred to as a "keep alive" or a "deadman" timer.
+
+@ifinfo
+@node Timer Service Routines, Timer Manager Operations, Timers, Timer Manager Background
+@end ifinfo
+@subsection Timer Service Routines
+
+The timer service routine should adhere to C calling
+conventions and have a prototype similar to the following::
+
+@example
+rtems_timer_service_routine user_routine(
+ rtems_id timer_id,
+ void *user_data
+);
+@end example
+
+
+
+Where the timer_id parameter is the RTEMS object ID
+of the timer which is being fired and user_data is a pointer to
+user-defined information which may be utilized by the timer
+service routine. The argument user_data may be NULL.
+
+@ifinfo
+@node Timer Manager Operations, Creating a Timer, Timer Service Routines, Timer Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating a Timer::
+* Obtaining Timer IDs::
+* Initiating an Interval Timer::
+* Initiating a Time of Day Timer::
+* Canceling a Timer::
+* Resetting a Timer::
+* Deleting a Timer::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating a Timer, Obtaining Timer IDs, Timer Manager Operations, Timer Manager Operations
+@end ifinfo
+@subsection Creating a Timer
+
+The timer_create directive creates a timer by
+allocating a Timer Control Block (TMCB), assigning the timer a
+user-specified name, and assigning it a timer ID. Newly created
+timers do not have a timer service routine associated with them
+and are not active.
+
+@ifinfo
+@node Obtaining Timer IDs, Initiating an Interval Timer, Creating a Timer, Timer Manager Operations
+@end ifinfo
+@subsection Obtaining Timer IDs
+
+When a timer is created, RTEMS generates a unique
+timer ID and assigns it to the created timer until it is
+deleted. The timer ID may be obtained by either of two methods.
+First, as the result of an invocation of the timer_create
+directive, the timer ID is stored in a user provided location.
+Second, the timer ID may be obtained later using the timer_ident
+directive. The timer ID is used by other directives to
+manipulate this timer.
+
+@ifinfo
+@node Initiating an Interval Timer, Initiating a Time of Day Timer, Obtaining Timer IDs, Timer Manager Operations
+@end ifinfo
+@subsection Initiating an Interval Timer
+
+The timer_fire_after directive initiates a timer to
+fire a user provided timer service routine after the specified
+number of clock ticks have elapsed. When the interval has
+elapsed, the timer service routine will be invoked from the
+clock_tick directive.
+
+@ifinfo
+@node Initiating a Time of Day Timer, Canceling a Timer, Initiating an Interval Timer, Timer Manager Operations
+@end ifinfo
+@subsection Initiating a Time of Day Timer
+
+The timer_fire_when directive initiates a timer to
+fire a user provided timer service routine when the specified
+time of day has been reached. When the interval has elapsed,
+the timer service routine will be invoked from the clock_tick
+directive.
+
+@ifinfo
+@node Canceling a Timer, Resetting a Timer, Initiating a Time of Day Timer, Timer Manager Operations
+@end ifinfo
+@subsection Canceling a Timer
+
+The timer_cancel directive is used to halt the
+specified timer. Once canceled, the timer service routine will
+not fire unless the timer is reinitiated. The timer can be
+reinitiated using the timer_reset, timer_fire_after, and
+timer_fire_when directives.
+
+@ifinfo
+@node Resetting a Timer, Deleting a Timer, Canceling a Timer, Timer Manager Operations
+@end ifinfo
+@subsection Resetting a Timer
+
+The timer_reset directive is used to restore an
+interval timer initiated by a previous invocation of
+timer_fire_after to its original interval length. The timer
+service routine is not changed or fired by this directive.
+
+@ifinfo
+@node Deleting a Timer, Timer Manager Directives, Resetting a Timer, Timer Manager Operations
+@end ifinfo
+@subsection Deleting a Timer
+
+The timer_delete directive is used to delete a timer.
+If the timer is running and has not expired, the timer is
+automatically canceled. The timer's control block is returned
+to the TMCB free list when it is deleted. A timer can be
+deleted by a task other than the task which created the timer.
+Any subsequent references to the timer's name and ID are invalid.
+
+@ifinfo
+@node Timer Manager Directives, TIMER_CREATE - Create a timer, Deleting a Timer, Timer Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* TIMER_CREATE - Create a timer::
+* TIMER_IDENT - Get ID of a timer::
+* TIMER_CANCEL - Cancel a timer::
+* TIMER_DELETE - Delete a timer::
+* TIMER_FIRE_AFTER - Fire timer after interval::
+* TIMER_FIRE_WHEN - Fire timer when specified::
+* TIMER_RESET - Reset an interval timer::
+@end menu
+@end ifinfo
+
+This section details the timer manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@ifinfo
+@node TIMER_CREATE - Create a timer, TIMER_IDENT - Get ID of a timer, Timer Manager Directives, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_CREATE - Create a timer
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_create(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer created successfully@*
+@code{INVALID_NAME} - invalid timer name@*
+@code{TOO_MANY} - too many timers created
+
+@subheading DESCRIPTION:
+
+This directive creates a timer. The assigned timer
+id is returned in id. This id is used to access the timer with
+other timer manager directives. For control and maintenance of
+the timer, RTEMS allocates a TMCB from the local TMCB free pool
+and initializes it.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node TIMER_IDENT - Get ID of a timer, TIMER_CANCEL - Cancel a timer, TIMER_CREATE - Create a timer, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_IDENT - Get ID of a timer
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_ident(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer identified successfully@*
+@code{INVALID_NAME} - timer name not found
+
+@subheading DESCRIPTION:
+
+This directive obtains the timer id associated with
+the timer name to be acquired. If the timer name is not unique,
+then the timer id will match one of the timers with that name.
+However, this timer id is not guaranteed to correspond to the
+desired timer. The timer id is used to access this timer in
+other timer related directives.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+@page
+@ifinfo
+@node TIMER_CANCEL - Cancel a timer, TIMER_DELETE - Delete a timer, TIMER_IDENT - Get ID of a timer, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_CANCEL - Cancel a timer
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_cancel(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer canceled successfully@*
+@code{INVALID_ID} - invalid timer id
+
+@subheading DESCRIPTION:
+
+This directive cancels the timer id. This timer will
+be reinitiated by the next invocation of timer_reset,
+timer_fire_after, or timer_fire_when with id.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be preempted.
+
+@page
+@ifinfo
+@node TIMER_DELETE - Delete a timer, TIMER_FIRE_AFTER - Fire timer after interval, TIMER_CANCEL - Cancel a timer, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_DELETE - Delete a timer
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer deleted successfully@*
+@code{INVALID_ID} - invalid timer id
+
+@subheading DESCRIPTION:
+
+This directive deletes the timer specified by id. If
+the timer is running, it is automatically canceled. The TMCB
+for the deleted timer is reclaimed by RTEMS.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+A timer can be deleted by a task other than the task
+which created the timer.
+
+@page
+@ifinfo
+@node TIMER_FIRE_AFTER - Fire timer after interval, TIMER_FIRE_WHEN - Fire timer when specified, TIMER_DELETE - Delete a timer, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_FIRE_AFTER - Fire timer after interval
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_fire_after(
+ rtems_id id,
+ rtems_interval ticks,
+ rtems_timer_service_routine_entry routine,
+ void *user_data
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer initiated successfully@*
+@code{INVALID_ID} - invalid timer id@*
+@code{INVALID_NUMBER} - invalid interval
+
+@subheading DESCRIPTION:
+
+This directive initiates the timer specified by id.
+If the timer is running, it is automatically canceled before
+being initiated. The timer is scheduled to fire after an
+interval ticks clock ticks has passed. When the timer fires,
+the timer service routine routine will be invoked with the
+argument user_data.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+@page
+@ifinfo
+@node TIMER_FIRE_WHEN - Fire timer when specified, TIMER_RESET - Reset an interval timer, TIMER_FIRE_AFTER - Fire timer after interval, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_FIRE_WHEN - Fire timer when specified
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_fire_when(
+ rtems_id id,
+ rtems_time_of_day *wall_time,
+ rtems_timer_service_routine_entry routine,
+ void *user_data
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer initiated successfully@*
+@code{INVALID_ID} - invalid timer id@*
+@code{NOT_DEFINED} - system date and time is not set@*
+@code{INVALID_CLOCK} - invalid time of day
+
+@subheading DESCRIPTION:
+
+This directive initiates the timer specified by id.
+If the timer is running, it is automatically canceled before
+being initiated. The timer is scheduled to fire at the time of
+day specified by wall_time. When the timer fires, the timer
+service routine routine will be invoked with the argument
+user_data.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+@page
+@ifinfo
+@node TIMER_RESET - Reset an interval timer, Semaphore Manager, TIMER_FIRE_WHEN - Fire timer when specified, Timer Manager Directives
+@end ifinfo
+@subsection TIMER_RESET - Reset an interval timer
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_timer_reset(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - timer reset successfully@*
+@code{INVALID_ID} - invalid timer id@*
+@code{NOT_DEFINED} - attempted to reset a when timer
+
+@subheading DESCRIPTION:
+
+This directive resets the timer associated with id.
+This timer must have been previously initiated with a
+timer_fire_after directive. If active the timer is canceled,
+after which the timer is reinitiated using the same interval and
+timer service routine which the original timer_fire_after
+directive used.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be preempted.
+
diff --git a/doc/user/userext.t b/doc/user/userext.t
new file mode 100644
index 0000000000..8166aa1a0e
--- /dev/null
+++ b/doc/user/userext.t
@@ -0,0 +1,649 @@
+@c
+@c COPYRIGHT (c) 1996.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+
+@ifinfo
+@node User Extensions Manager, User Extensions Manager Introduction, Heterogeneous Systems, Top
+@end ifinfo
+@chapter User Extensions Manager
+@ifinfo
+@menu
+* User Extensions Manager Introduction::
+* User Extensions Manager Background::
+* User Extensions Manager Operations::
+* User Extensions Manager Directives::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node User Extensions Manager Introduction, User Extensions Manager Background, User Extensions Manager, User Extensions Manager
+@end ifinfo
+@section Introduction
+
+The RTEMS User Extensions Manager allows the
+application developer to augment the executive by allowing them
+to supply extension routines which are invoked at critical
+system events. The directives provided by the user extensions
+manager are:
+
+@itemize @bullet
+@item @code{extension_create} - Create an extension set
+@item @code{extension_ident} - Get ID of an extension set
+@item @code{extension_delete} - Delete an extension set
+@end itemize
+
+@ifinfo
+@node User Extensions Manager Background, Extension Sets, User Extensions Manager Introduction, User Extensions Manager
+@end ifinfo
+@section Background
+@ifinfo
+@menu
+* Extension Sets::
+* TCB Extension Area::
+* Extensions::
+* TASK_CREATE Extension::
+* TASK_START Extension::
+* TASK_RESTART Extension::
+* TASK_DELETE Extension::
+* TASK_SWITCH Extension::
+* TASK_POST_SWITCH Extension::
+* TASK_BEGIN Extension::
+* TASK_EXITTED Extension::
+* FATAL Error Extension::
+* Order of Invocation::
+@end menu
+@end ifinfo
+
+User extension routines are invoked when the
+following system events occur:
+
+@itemize @bullet
+@item Task creation
+@item Task initiation
+@item Task reinitiation
+@item Task deletion
+@item Task context switch
+@item Post task context switch
+@item Task begin
+@item Task exits
+@item Fatal error detection
+@end itemize
+
+These extensions are invoked as a function with
+arguments that are appropriate to the system event.
+
+@ifinfo
+@node Extension Sets, TCB Extension Area, User Extensions Manager Background, User Extensions Manager Background
+@end ifinfo
+@subsection Extension Sets
+
+An extension set is defined as a set of routines
+which are invoked at each of the critical system events at which
+user extension routines are invoked. Together a set of these
+routines typically perform a specific functionality such as
+performance monitoring or debugger support. RTEMS is informed of
+the entry points which constitute an extension set via the
+following structure:
+
+@example
+@group
+typedef struct @{
+ User_extensions_thread_create_extension thread_create;
+ User_extensions_thread_start_extension thread_start;
+ User_extensions_thread_restart_extension thread_restart;
+ User_extensions_thread_delete_extension thread_delete;
+ User_extensions_thread_switch_extension thread_switch;
+ User_extensions_thread_post_switch_extension thread_post_switch;
+ User_extensions_thread_begin_extension thread_begin;
+ User_extensions_thread_exitted_extension thread_exitted;
+ User_extensions_fatal_error_extension fatal;
+@} User_extensions_Table;
+@end group
+@end example
+
+
+RTEMS allows the user to have multiple extension sets
+active at the same time. First, a single static extension set
+may be defined as the application's User Extension Table which
+is included as part of the Configuration Table. This extension
+set is active for the entire life of the system and may not be
+deleted. This extension set is especially important because it
+is the only way the application can provided a FATAL error
+extension which is invoked if RTEMS fails during the
+initialize_executive directive. The static extension set is
+optional and may be configured as NULL if no static extension
+set is required.
+
+Second, the user can install dynamic extensions using
+the extension_create directive. These extensions are RTEMS
+objects in that they have a name, an ID, and can be dynamically
+created and deleted. In contrast to the static extension set,
+these extensions can only be created and installed after the
+initialize_executive directive successfully completes execution.
+Dynamic extensions are useful for encapsulating the
+functionality of an extension set. For example, the application
+could use extensions to manage a special coprocessor, do
+performance monitoring, and to do stack bounds checking. Each
+of these extension sets could be written and installed
+independently of the others.
+
+All user extensions are optional and RTEMS places no
+naming restrictions on the user.
+
+@ifinfo
+@node TCB Extension Area, Extensions, Extension Sets, User Extensions Manager Background
+@end ifinfo
+@subsection TCB Extension Area
+
+RTEMS provides for a pointer to a user-defined data
+area for each extension set to be linked to each task's control
+block. This set of pointers is an extension of the TCB and can
+be used to store additional data required by the user's
+extension functions. It is also possible for a user extension
+to utilize the notepad locations associated with each task
+although this may conflict with application usage of those
+particular notepads.
+
+The TCB extension is an array of pointers in the TCB.
+The number of pointers in the area is the same as the number of
+user extension sets configured. This allows an application to
+augment the TCB with user-defined information. For example, an
+application could implement task profiling by storing timing
+statistics in the TCB's extended memory area. When a task
+context switch is being executed, the TASK_SWITCH extension
+could read a real-time clock to calculate how long the task
+being swapped out has run as well as timestamp the starting time
+for the task being swapped in.
+
+If used, the extended memory area for the TCB should
+be allocated and the TCB extension pointer should be set at the
+time the task is created or started by either the TASK_CREATE or
+TASK_START extension. The application is responsible for
+managing this extended memory area for the TCBs. The memory may
+be reinitialized by the TASK_RESTART extension and should be
+deallocated by the TASK_DELETE extension when the task is
+deleted. Since the TCB extension buffers would most likely be
+of a fixed size, the RTEMS partition manager could be used to
+manage the application's extended memory area. The application
+could create a partition of fixed size TCB extension buffers and
+use the partition manager's allocation and deallocation
+directives to obtain and release the extension buffers.
+
+@ifinfo
+@node Extensions, TASK_CREATE Extension, TCB Extension Area, User Extensions Manager Background
+@end ifinfo
+@subsection Extensions
+
+The sections that follow will contain a description
+of each extension. Each section will contain a prototype of a
+function with the appropriate calling sequence for the
+corresponding extension. The names given for the C function and
+its arguments are all defined by the user. The names used in
+the examples were arbitrarily chosen and impose no naming
+conventions on the user.
+
+@ifinfo
+@node TASK_CREATE Extension, TASK_START Extension, Extensions, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_CREATE Extension
+
+The TASK_CREATE extension directly corresponds to the
+task_create directive. If this extension is defined in any
+static or dynamic extension set and a task is being created,
+then the extension routine will automatically be invoked by
+RTEMS. The extension should have a prototype similar to the
+following:
+
+@example
+rtems_extension user_task_create(
+ rtems_tcb *current_task,
+ rtems_tcb *new_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the currently executing task, and new_task can be used to access
+the TCB for the new task being created. This extension is
+invoked from the task_create directive after new_task has been
+completely initialized, but before it is placed on a ready TCB
+chain.
+
+@ifinfo
+@node TASK_START Extension, TASK_RESTART Extension, TASK_CREATE Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_START Extension
+
+The TASK_START extension directly corresponds to the
+task_start directive. If this extension is defined in any
+static or dynamic extension set and a task is being started,
+then the extension routine will automatically be invoked by
+RTEMS. The extension should have a prototype similar to the
+following:
+
+@example
+rtems_extension user_task_start(
+ rtems_tcb *current_task,
+ rtems_tcb *started_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the currently executing task, and started_task can be used to
+access the TCB for the dormant task being started. This
+extension is invoked from the task_start directive after
+started_task has been made ready to start execution, but before
+it is placed on a ready TCB chain.
+
+@ifinfo
+@node TASK_RESTART Extension, TASK_DELETE Extension, TASK_START Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_RESTART Extension
+
+The TASK_RESTART extension directly corresponds to
+the task_restart directive. If this extension is defined in any
+static or dynamic extension set and a task is being restarted,
+then the extension should have a prototype similar to the
+following:
+
+@example
+rtems_extension user_task_restart(
+ rtems_tcb *current_task,
+ rtems_tcb *restarted_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the currently executing task, and restarted_task can be used to
+access the TCB for the task being restarted. This extension is
+invoked from the task_restart directive after restarted_task has
+been made ready to start execution, but before it is placed on a
+ready TCB chain.
+
+@ifinfo
+@node TASK_DELETE Extension, TASK_SWITCH Extension, TASK_RESTART Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_DELETE Extension
+
+The TASK_DELETE extension is associated with the
+task_delete directive. If this extension is defined in any
+static or dynamic extension set and a task is being deleted,
+then the extension routine will automatically be invoked by
+RTEMS. The extension should have a prototype similar to the
+following:
+
+@example
+rtems_extension user_task_delete(
+ rtems_tcb *current_task,
+ rtems_tcb *deleted_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the currently executing task, and deleted_task can be used to
+access the TCB for the task being deleted. This extension is
+invoked from the task_delete directive after the TCB has been
+removed from a ready TCB chain, but before all its resources
+including the TCB have been returned to their respective free
+pools. This extension should not call any RTEMS directives if a
+task is deleting itself (current_task is equal to deleted_task).
+
+@ifinfo
+@node TASK_SWITCH Extension, TASK_POST_SWITCH Extension, TASK_DELETE Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_SWITCH Extension
+
+The TASK_SWITCH extension corresponds to a task
+context switch. If this extension is defined in any static or
+dynamic extension set and a task context switch is in progress,
+then the extension routine will automatically be invoked by
+RTEMS. The extension should have a prototype similar to the
+following:
+
+@example
+rtems_extension user_task_switch(
+ rtems_tcb *current_task,
+ rtems_tcb *heir_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the task that is being swapped out, and heir_task can be used to
+access the TCB for the task being swapped in. This extension is
+invoked from RTEMS' dispatcher routine after the current_task
+context has been saved, but before the heir_task context has
+been restored. This extension should not call any RTEMS
+directives.
+
+@ifinfo
+@node TASK_POST_SWITCH Extension, TASK_BEGIN Extension, TASK_SWITCH Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_POST_SWITCH Extension
+
+The TASK_POST_SWITCH extension corresponds to a task
+context switch. If this extension is defined in any static or
+dynamic extension set and a raw task context switch has been
+completed, then the extension routine will automatically be
+invoked by RTEMS. The extension should have a prototype similar
+to the following:
+
+@example
+rtems_extension user_task_post_switch(
+ rtems_tcb *current_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the task that is being swapped out, and heir_task can be used to
+access the TCB for the task being swapped in. This extension is
+invoked from RTEMS' dispatcher routine after the current_task
+context has been restored and the extension runs in the context
+of the current_task.
+
+@ifinfo
+@node TASK_BEGIN Extension, TASK_EXITTED Extension, TASK_POST_SWITCH Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_BEGIN Extension
+
+The TASK_BEGIN extension is invoked when a task
+begins execution. It is invoked immediately before the body of
+the starting procedure and executes in the context in the task.
+This user extension have a prototype similar to the following:
+
+@example
+rtems_extension user_task_begin(
+ rtems_tcb *current_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the currently executing task which has begun. The distinction
+between the TASK_BEGIN and TASK_START extension is that the
+TASK_BEGIN extension is executed in the context of the actual
+task while the TASK_START extension is executed in the context
+of the task performing the task_start directive. For most
+extensions, this is not a critical distinction.
+
+@ifinfo
+@node TASK_EXITTED Extension, FATAL Error Extension, TASK_BEGIN Extension, User Extensions Manager Background
+@end ifinfo
+@subsection TASK_EXITTED Extension
+
+The TASK_EXITTED extension is invoked when a task
+exits the body of the starting procedure by either an implicit
+or explicit return statement. This user extension have a
+prototype similar to the following:
+
+@example
+rtems_extension user_task_exitted(
+ rtems_tcb *current_task
+);
+@end example
+
+where current_task can be used to access the TCB for
+the currently executing task which has just exitted.
+
+Although exiting of task is often considered to be a
+fatal error, this extension allows recovery by either restarting
+or deleting the exiting task. If the user does not wish to
+recover, then a fatal error may be reported. If the user does
+not provide a TASK_EXITTED extension or the provided handler
+returns control to RTEMS, then the RTEMS default handler will be
+used. This default handler invokes the directive
+fatal_error_occurred with the TASK_EXITTED directive status.
+
+@lowersections
+
+@ifinfo
+@node FATAL Error Extension, Order of Invocation, TASK_EXITTED Extension, User Extensions Manager Background
+@end ifinfo
+@subsection FATAL Error Extension
+
+The FATAL error extension is associated with the
+fatal_error_occurred directive. If this extension is defined in
+any static or dynamic extension set and the fatal_error_occurred
+directive has been invoked, then this extension will be called.
+This extension should have a prototype similar to the following:
+
+@example
+rtems_extension user_fatal_error_extension(
+ Internal_errors_Source the_source,
+ rtems_boolean is_internal,
+ rtems_unsigned32 the_error
+);
+@end example
+
+where the_error is the error code passed to the
+fatal_error_occurred directive. This extension is invoked from
+the fatal_error_occurred directive.
+
+If defined, the user's FATAL error extension is
+invoked before RTEMS' default fatal error routine is invoked and
+the processor is stopped. For example, this extension could be
+used to pass control to a debugger when a fatal error occurs.
+This extension should not call any RTEMS directives.
+
+@raisesections
+
+@ifinfo
+@node Order of Invocation, User Extensions Manager Operations, FATAL Error Extension, User Extensions Manager Background
+@end ifinfo
+@subsection Order of Invocation
+
+When one of the critical system events occur, the
+user extensions are invoked in either "forward" or "reverse"
+order. Forward order indicates that the static extension set is
+invoked followed by the dynamic extension sets in the order in
+which they were created. Reverse order means that the dynamic
+extension sets are invoked in the opposite of the order in which
+they were created followed by the static extension set. By
+invoking the extension sets in this order, extensions can be
+built upon one another. At the following system events, the
+extensions are invoked in forward order:
+
+@itemize @bullet
+@item Task creation
+@item Task initiation
+@item Task reinitiation
+@item Task deletion
+@item Task context switch
+@item Post task context switch
+@item Task begins to execute
+@end itemize
+
+
+At the following system events, the extensions are
+invoked in reverse order:
+
+@itemize @bullet
+@item Task deletion
+@item Fatal error detection
+@end itemize
+
+At these system events, the extensions are invoked in
+reverse order to insure that if an extension set is built upon
+another, the more complicated extension is invoked before the
+extension set it is built upon. For example, by invoking the
+static extension set last it is known that the "system" fatal
+error extension will be the last fatal error extension executed.
+Another example is use of the task delete extension by the
+Standard C Library. Extension sets which are installed after
+the Standard C Library will operate correctly even if they
+utilize the C Library because the C Library's TASK_DELETE
+extension is invoked after that of the other extensions.
+
+@ifinfo
+@node User Extensions Manager Operations, Creating an Extension Set, Order of Invocation, User Extensions Manager
+@end ifinfo
+@section Operations
+@ifinfo
+@menu
+* Creating an Extension Set::
+* Obtaining Extension Set IDs::
+* Deleting an Extension Set::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Creating an Extension Set, Obtaining Extension Set IDs, User Extensions Manager Operations, User Extensions Manager Operations
+@end ifinfo
+@subsection Creating an Extension Set
+
+The extension_create directive creates and installs
+an extension set by allocating a Extension Set Control Block
+(ESCB), assigning the extension set a user-specified name, and
+assigning it an extension set ID. Newly created extension sets
+are immediately installed and are invoked upon the next system
+even supporting an extension.
+
+@ifinfo
+@node Obtaining Extension Set IDs, Deleting an Extension Set, Creating an Extension Set, User Extensions Manager Operations
+@end ifinfo
+@subsection Obtaining Extension Set IDs
+
+When an extension set is created, RTEMS generates a
+unique extension set ID and assigns it to the created extension
+set until it is deleted. The extension ID may be obtained by
+either of two methods. First, as the result of an invocation of
+the extension_create directive, the extension set ID is stored
+in a user provided location. Second, the extension set ID may
+be obtained later using the extension_ident directive. The
+extension set ID is used by other directives to manipulate this
+extension set.
+
+@ifinfo
+@node Deleting an Extension Set, User Extensions Manager Directives, Obtaining Extension Set IDs, User Extensions Manager Operations
+@end ifinfo
+@subsection Deleting an Extension Set
+
+The extension_delete directive is used to delete an
+extension set. The extension set's control block is returned to
+the ESCB free list when it is deleted. An extension set can be
+deleted by a task other than the task which created the
+extension set. Any subsequent references to the extension's
+name and ID are invalid.
+
+@ifinfo
+@node User Extensions Manager Directives, EXTENSION_CREATE - Create a extension set, Deleting an Extension Set, User Extensions Manager
+@end ifinfo
+@section Directives
+@ifinfo
+@menu
+* EXTENSION_CREATE - Create a extension set::
+* EXTENSION_IDENT - Get ID of a extension set::
+* EXTENSION_DELETE - Delete a extension set::
+@end menu
+@end ifinfo
+
+This section details the user extension manager's
+directives. A subsection is dedicated to each of this manager's
+directives and describes the calling sequence, related
+constants, usage, and status codes.
+
+@page
+@ifinfo
+@node EXTENSION_CREATE - Create a extension set, EXTENSION_IDENT - Get ID of a extension set, User Extensions Manager Directives, User Extensions Manager Directives
+@end ifinfo
+@subsection EXTENSION_CREATE - Create a extension set
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_extension_create(
+ rtems_name name,
+ rtems_extensions_table *table,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - extension set created successfully@*
+@code{INVALID_NAME} - invalid extension set name@*
+@code{TOO_MANY} - too many extension sets created
+
+@subheading DESCRIPTION:
+
+This directive creates a extension set. The assigned
+extension set id is returned in id. This id is used to access
+the extension set with other user extension manager directives.
+For control and maintenance of the extension set, RTEMS
+allocates an ESCB from the local ESCB free pool and initializes
+it.
+
+@subheading NOTES:
+
+This directive will not cause the calling task to be
+preempted.
+
+@page
+@ifinfo
+@node EXTENSION_IDENT - Get ID of a extension set, EXTENSION_DELETE - Delete a extension set, EXTENSION_CREATE - Create a extension set, User Extensions Manager Directives
+@end ifinfo
+@subsection EXTENSION_IDENT - Get ID of a extension set
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_extension_ident(
+ rtems_name name,
+ rtems_id *id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - extension set identified successfully@*
+@code{INVALID_NAME} - extension set name not found
+
+@subheading DESCRIPTION:
+
+This directive obtains the extension set id
+associated with the extension set name to be acquired. If the
+extension set name is not unique, then the extension set id will
+match one of the extension sets with that name. However, this
+extension set id is not guaranteed to correspond to the desired
+extension set. The extension set id is used to access this
+extension set in other extension set related directives.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+@page
+@ifinfo
+@node EXTENSION_DELETE - Delete a extension set, Configuring a System, EXTENSION_IDENT - Get ID of a extension set, User Extensions Manager Directives
+@end ifinfo
+@subsection EXTENSION_DELETE - Delete a extension set
+
+@subheading CALLING SEQUENCE:
+
+@example
+rtems_status_code rtems_extension_delete(
+ rtems_id id
+);
+@end example
+
+@subheading DIRECTIVE STATUS CODES:
+@code{SUCCESSFUL} - extension set deleted successfully@*
+@code{INVALID_ID} - invalid extension set id
+
+@subheading DESCRIPTION:
+
+This directive deletes the extension set specified by
+id. If the extension set is running, it is automatically
+canceled. The ESCB for the deleted extension set is reclaimed
+by RTEMS.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.
+
+A extension set can be deleted by a task other than
+the task which created the extension set.
+
+@subheading NOTES:
+
+This directive will not cause the running task to be
+preempted.