Index: ada_user/ada_user.rst
===================================================================
--- ada_user/ada_user.rst	(revision 5daabd23cfd13662e74ce8d069204882eb1fbad9)
+++ ada_user/ada_user.rst	(revision 5daabd23cfd13662e74ce8d069204882eb1fbad9)
@@ -0,0 +1,22895 @@
+:orphan:
+
+
+
+.. COMMENT: %**end of header
+
+.. COMMENT: COPYRIGHT (c) 1989-2014.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: Master file for the Ada User's Guide
+
+.. COMMENT: Joel's Questions
+
+.. COMMENT: 1.  Why does paragraphindent only impact makeinfo?
+
+.. COMMENT: 2.  Why does paragraphindent show up in HTML?
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: The following determines which set of the tables and figures we will use.
+
+.. COMMENT: We default to ASCII but if available TeX or HTML versions will
+
+.. COMMENT: be used instead.
+
+.. COMMENT: @clear use-html
+
+.. COMMENT: @clear use-tex
+
+.. COMMENT: The following variable says to use texinfo or html for the two column
+
+.. COMMENT: texinfo tables.  For somethings the format does not look good in html.
+
+.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
+
+.. COMMENT: good printed.
+
+.. COMMENT: Custom whitespace adjustments.  We could fiddle a bit more.
+
+.. COMMENT: variable substitution info:
+
+.. COMMENT: the language is @value{LANGUAGE}
+
+.. COMMENT: NOTE:  don't use underscore in the name
+
+.. COMMENT: Title Page Stuff
+
+.. COMMENT: I don't really like having a short title page.  -joel
+
+.. COMMENT: @shorttitlepage RTEMS Applications Ada User's Guide
+
+======================
+RTEMS Ada Userâs Guide
+======================
+
+.. COMMENT: COPYRIGHT (c) 1988-2015.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
+
+.. COMMENT: can force the copyright description onto a left hand page.
+
+COPYRIGHT Â© 1988 - 2015.
+
+On-Line Applications Research Corporation (OAR).
+
+The authors have used their best efforts in preparing
+this material.  These efforts include the development, research,
+and testing of the theories and programs to determine their
+effectiveness.  No warranty of any kind, expressed or implied,
+with regard to the software or the material contained in this
+document is provided.  No liability arising out of the
+application or use of any product described in this document is
+assumed.  The authors reserve the right to revise this material
+and to make changes from time to time in the content hereof
+without obligation to notify anyone of such revision or changes.
+
+The RTEMS Project is hosted at http://www.rtems.org.  Any
+inquiries concerning RTEMS, its related support components, or its
+documentation should be directed to the Community Project hosted athttp://www.rtems.org.
+
+Any inquiries for commercial services including training, support, custom
+development, application development assistance should be directed tohttp://www.rtems.com.
+
+.. COMMENT: This prevents a black box from being printed on "overflow" lines.
+
+.. COMMENT: The alternative is to rework a sentence to avoid this problem.
+
+RTEMS Applications Ada Userâs Guide
+###################################
+
+List of Figures
+###############
+
+.. COMMENT: COPYRIGHT (c) 1989-2015.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+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 following processor families:
+
+- Altera NIOS II
+
+- Analog Devices Blackfin
+
+- Atmel AVR
+
+- ARM
+
+- Freescale (formerly Motorola) MC68xxx
+
+- Freescale (formerly Motorola) MC683xx
+
+- Freescale (formerly Motorola) ColdFire
+
+- Intel i386 and above
+
+- Lattice Semiconductor LM32
+
+- NEC V850
+
+- MIPS
+
+- PowerPC
+
+- Renesas (formerly Hitachi) SuperH
+
+- Renesas (formerly Hitachi) H8/300
+
+- Renesas M32C
+
+- SPARC v7, v8, and V9
+
+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
+4.10.99.0 of the Ada interface
+to RTEMS.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: This chapter is missing the following figures:
+
+.. COMMENT: Figure 1-1  RTEMS Application Architecture
+
+.. COMMENT: Figure 1-2  RTEMS Internal Architecture
+
+Overview
+########
+
+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:
+
+- multitasking capabilities
+
+- homogeneous and heterogeneous multiprocessor systems
+
+- event-driven, priority-based, preemptive scheduling
+
+- optional rate monotonic scheduling
+
+- intertask communication and synchronization
+
+- priority inheritance
+
+- responsive interrupt management
+
+- dynamic memory allocation
+
+- high level of user configurability
+
+This manual describes the usage of RTEMS for
+applications written in the Ada programming language.  Those
+implementation details that are processor dependent are provided
+in the Applications Supplement documents.  A supplement
+document which addresses specific architectural issues that
+affect RTEMS is provided for each processor type that is
+supported.
+
+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.
+
+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.
+
+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.
+
+.. code:: c
+
+    +-----------------------------------------------------------+
+    |             Application Dependent Software                |
+    |        +----------------------------------------+         |
+    |        |    Standard Application Components     |         |
+    |        |                          +-------------+---+     |
+    |    +---+-----------+              |                 |     |
+    |    | Board Support |              |      RTEMS      |     |
+    |    |    Package    |              |                 |     |
+    +----+---------------+--------------+-----------------+-----|
+    |                      Target Hardware                      |
+    +-----------------------------------------------------------+
+
+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.
+
+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:
+
+.. code:: c
+
+    +-----------------------------------------------+
+    |          RTEMS Executive Interface            |
+    +-----------------------------------------------+
+    |                 RTEMS Core                    |
+    +-----------------------------------------------+
+    |              CPU Dependent Code               |
+    +-----------------------------------------------+
+
+Subsequent chapters present a detailed description of the capabilities
+provided by each of the following RTEMS managers:
+
+- initialization
+
+- task
+
+- interrupt
+
+- clock
+
+- timer
+
+- semaphore
+
+- message
+
+- event
+
+- signal
+
+- partition
+
+- region
+
+- dual ported memory
+
+- I/O
+
+- fatal error
+
+- rate monotonic
+
+- user extensions
+
+- multiprocessing
+
+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.
+
+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.
+
+Memory Requirements
+===================
+
+Since memory is a critical resource in many real-time
+embedded systems, RTEMS was specifically designed to automatically
+leave out all services that are not required from the run-time
+environment.  Features such as networking, various fileystems,
+and many other features are completely optional.  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.
+
+RTEMS requires RAM to manage each instance of an RTEMS object
+that is created.  Thus the more RTEMS objects an application
+needs, the more memory that must be reserved.  See:ref:`Configuring a System <Configuring-a-System>` for more details.
+
+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.
+
+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 Ada, a basic
+understanding of the Ada 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.
+
+Conventions
+===========
+
+The following conventions are used in this manual:
+
+- Significant words or phrases as well as all directive
+  names are printed in bold type.
+
+- 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
+  record definitions which can be incorporated into the user
+  application.
+
+- A number of type definitions are provided by RTEMS and
+  can be found in rtems.h.
+
+- The characters "0x" preceding a number indicates that
+  the number is in hexadecimal format.  Any other numbers are
+  assumed to be in decimal format.
+
+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:
+
+- Calling sequence
+
+- Directive status codes
+
+- Description
+
+- Notes
+
+The following provides an overview of the remainder
+of this manual:
+
+Chapter 2:
+    Key Concepts: presents an introduction to the ideas which are common
+    across multiple RTEMS managers.
+
+Chapter 3:
+    RTEMS Data Types: describes the fundamental data types shared
+    by the services in the RTEMS Classic API.
+
+Chapter 4:
+    Scheduling Concepts: details the various RTEMS scheduling algorithms
+    and task state transitions.
+
+Chapter 5:
+    Initialization Manager: describes the functionality and directives
+    provided by the Initialization Manager.
+
+Chapter 6:
+    Task Manager: describes the functionality and directives provided
+    by the Task Manager.
+
+Chapter 7:
+    Interrupt Manager: describes the functionality and directives
+    provided by the Interrupt Manager.
+
+Chapter 8:
+    Clock Manager: describes the functionality and directives
+    provided by the Clock Manager.
+
+Chapter 9:
+    Timer Manager: describes the functionality and directives provided
+    by the Timer Manager.
+
+Chapter 10:
+    Rate Monotonic Manager: describes the functionality and directives
+    provided by the Rate Monotonic Manager.
+
+Chapter 11:
+    Semaphore Manager: describes the functionality and directives
+    provided by the Semaphore Manager.
+
+Chapter 12:
+    Barrier Manager: describes the functionality and directives
+    provided by the Barrier Manager.
+
+Chapter 13:
+    Message Manager: describes the functionality and directives
+    provided by the Message Manager.
+
+Chapter 14:
+    Event Manager: describes the
+    functionality and directives provided by the Event Manager.
+
+Chapter 15:
+    Signal Manager: describes the
+    functionality and directives provided by the Signal Manager.
+
+Chapter 16:
+    Partition Manager: describes the
+    functionality and directives provided by the Partition Manager.
+
+Chapter 17:
+    Region Manager: describes the
+    functionality and directives provided by the Region Manager.
+
+Chapter 18:
+    Dual-Ported Memory Manager: describes
+    the functionality and directives provided by the Dual-Ported
+    Memory Manager.
+
+Chapter 19:
+    I/O Manager: describes the
+    functionality and directives provided by the I/O Manager.
+
+Chapter 20:
+    Fatal Error Manager: describes the functionality and directives
+    provided by the Fatal Error Manager.
+
+Chapter 21:
+    Board Support Packages: defines the
+    functionality required of user-supplied board support packages.
+
+Chapter 22:
+    User Extensions: shows the user how to
+    extend RTEMS to incorporate custom features.
+
+Chapter 23:
+    Configuring a System: details the process by which one tailors RTEMS
+    for a particular single-processor or multiprocessor application.
+
+Chapter 24:
+    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.
+
+Chapter 25:
+    Stack Bounds Checker: presents the capabilities of the RTEMS
+    task stack checker which can report stack usage as well as detect
+    bounds violations.
+
+Chapter 26:
+    CPU Usage Statistics: presents the capabilities of the CPU Usage
+    statistics gathered on a per task basis along with the mechanisms
+    for reporting and resetting the statistics.
+
+Chapter 27:
+    Object Services: presents a collection of helper services useful
+    when manipulating RTEMS objects. These include methods to assist
+    in obtaining an objectâs name in printable form. Additional services
+    are provided to decompose an object Id and determine which API
+    and object class it belongs to.
+
+Chapter 28:
+    Chains: presents the methods provided to build, iterate and
+    manipulate doubly-linked chains. This manager makes the
+    chain implementation used internally by RTEMS to user space
+    applications.
+
+Chapter 29:
+    Timespec Helpers: presents a set of helper services useful
+    when manipulating POSIX ``struct timespec`` instances.
+
+Chapter 30:
+    Constant Bandwidth Server Scheduler API::
+
+Chapter 31:
+    Directive Status Codes: provides a definition of each of the
+    directive status codes referenced in this manual.
+
+Chapter 32:
+    Example Application: provides a template for simple RTEMS applications.
+
+Chapter 33:
+    Glossary: defines terms used throughout this manual.
+
+.. COMMENT: COPYRIGHT (c) 1988-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: The following figure was replaced with an ASCII equivalent.
+
+.. COMMENT: Figure 2-1 Object ID Composition
+
+Key Concepts
+############
+
+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.
+
+Objects
+=======
+
+.. index:: 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.
+
+Object Names
+------------
+.. index:: object name
+.. index:: rtems_object_name
+
+An object name is an unsigned thirty-two bit entity
+associated with the object by the user.  The data type``rtems.name`` is used to store object names... index:: rtems_build_name
+
+Although not required by RTEMS, object names are often
+composed of four ASCII characters which help identify that object.
+For example, a task which causes a light to blink might be
+called "LITE".  The ``rtems.build_name`` routine
+is provided to build an object name from four ASCII characters.
+The following example illustrates this:
+
+.. code:: c
+
+    My_Name : RTEMS.Name;
+    My_Name = RTEMS.Build_Name( 'L', 'I', 'T', 'E' );
+
+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.
+
+Object IDs
+----------
+
+.. index:: object ID
+.. index:: object ID composition
+.. index:: rtems_id
+
+An object ID is a unique unsigned integer value which uniquely identifies
+an object instance.  Object IDs are passed as arguments to many directives
+in RTEMS and RTEMS translates the ID to an internal object pointer. The
+efficient manipulation of object IDs is critical to the performance
+of RTEMS services.  Because of this, there are two object Id formats
+defined.  Each target architecture specifies which format it will use.
+There is a thirty-two bit format which is used for most of the supported
+architectures and supports multiprocessor configurations.  There is also
+a simpler sixteen bit format which is appropriate for smaller target
+architectures and does not support multiprocessor configurations.
+
+Thirty-Two Object ID Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The thirty-two bit format for an object ID is composed of four parts: API,
+object class, node, and index.  The data type ``rtems.id``
+is used to store object IDs.
+
+.. code:: c
+
+    31      27 26   24 23          16 15                             0
+    +---------+-------+--------------+-------------------------------+
+    |         |       |              |                               |
+    |  Class  |  API  |     Node     |             Index             |
+    |         |       |              |                               |
+    +---------+-------+--------------+-------------------------------+
+
+The most significant five bits are the object class.  The next
+three bits indicate the API to which the object class belongs.
+The next eight bits (16-23) 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.
+
+Sixteen Bit Object ID Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The sixteen bit format for an object ID is composed of three parts: API,
+object class, and index.  The data type ``rtems.id``
+is used to store object IDs.
+
+.. code:: c
+
+    15      11 10    8 7            0
+    +---------+-------+--------------+
+    |         |       |              |
+    |  Class  |  API  |    Index     |
+    |         |       |              |
+    +---------+-------+--------------+
+
+The sixteen-bit format is designed to be as similar as possible to the
+thrity-two bit format.  The differences are limited to the eliminatation
+of the node field and reduction of the index field from sixteen-bits
+to 8-bits.  Thus the sixteen bit format only supports up to 255 object
+instances per API/Class combination and single processor systems.
+As this format is typically utilized by sixteen-bit processors with
+limited address space, this is more than enough object instances.
+
+Object ID Description
+---------------------
+
+The 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.
+
+In addition, services are provided to portably examine the
+subcomponents of an RTEMS ID.  These services are
+described in detail later in this manual but are prototyped
+as follows:.. index:: obtaining class from object ID
+.. index:: obtaining node from object ID
+.. index:: obtaining index from object ID
+.. index:: get class from object ID
+.. index:: get node from object ID
+.. index:: get index from object ID
+.. index:: rtems_object_id_get_api
+.. index:: rtems_object_id_get_class
+.. index:: rtems_object_id_get_node
+.. index:: rtems_object_id_get_index
+
+.. code:: c
+
+    uint32_t rtems_object_id_get_api( rtems_id );
+    uint32_t rtems_object_id_get_class( rtems_id );
+    uint32_t rtems_object_id_get_node( rtems_id );
+    uint32_t rtems_object_id_get_index( rtems_id );
+
+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.
+
+Communication and Synchronization
+=================================
+.. index:: 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:
+
+- Data transfer between cooperating tasks
+
+- Data transfer between tasks and ISRs
+
+- Synchronization of cooperating tasks
+
+- Synchronization of tasks and ISRs
+
+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:
+
+- Semaphore
+
+- Message Queue
+
+- Event
+
+- Signal
+
+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.
+
+Time
+====
+.. index:: 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... index:: rtems_interval
+
+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.
+All intervals are specified using data type``rtems.interval``.
+
+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.
+The data type ``rtems.time_of_day`` is used to specify
+calendar time in RTEMS services.
+See :ref:`Time and Date Data Structures <Clock-Manager-Time-and-Date-Data-Structures>`... index:: rtems_time_of_day
+
+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.
+
+Memory Management
+=================
+.. index:: 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:
+
+- Region
+
+- Partition
+
+- Dual Ported Memory
+
+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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+RTEMS Data Types
+################
+
+Introduction
+============
+
+This chapter contains a complete list of the RTEMS primitive
+data types in alphabetical order.  This is intended to be
+an overview and the user is encouraged to look at the appropriate
+chapters in the manual for more information about the
+usage of the various data types.
+
+List of Data Types
+==================
+
+The following is a complete list of the RTEMS primitive
+data types in alphabetical order:
+
+- .. index:: rtems_address
+  ``rtems.address`` is the data type used to manage
+  addresses.  It is equivalent to
+  the System.Address data type.
+
+- .. index:: rtems_asr
+  ``rtems.asr`` is the return type for an
+  RTEMS ASR.
+
+- .. index:: rtems_asr_entry
+  ``rtems.asr_entry`` is the address of
+  the entry point to an RTEMS ASR.
+
+- .. index:: rtems_attribute
+  ``rtems.attribute`` is the data type used
+  to manage the attributes for RTEMS objects.  It is primarily
+  used as an argument to object create routines to specify
+  characteristics of the new object.
+
+- .. index:: rtems_boolean
+  ``rtems.boolean`` may only take on the
+  values of ``TRUE`` and ``FALSE``.
+  This type is deprecated. Use "bool" instead.
+
+- .. index:: rtems_context
+  ``rtems.context`` is the CPU dependent
+  data structure used to manage the integer and system
+  register portion of each taskâs context.
+
+- .. index:: rtems_context_fp
+  ``rtems.context_fp`` is the CPU dependent
+  data structure used to manage the floating point portion of
+  each taskâs context.
+
+- .. index:: rtems_device_driver
+  ``rtems.device_driver`` is the
+  return type for a RTEMS device driver routine.
+
+- .. index:: rtems_device_driver_entry
+  ``rtems.device_driver_entry`` is the
+  entry point to a RTEMS device driver routine.
+
+- .. index:: rtems_device_major_number
+  ``rtems.device_major_number`` is the
+  data type used to manage device major numbers.
+
+- .. index:: rtems_device_minor_number
+  ``rtems.device_minor_number`` is the
+  data type used to manage device minor numbers.
+
+- .. index:: rtems_double
+  ``rtems.double`` is the RTEMS data
+  type that corresponds to double precision floating point
+  on the target hardware.
+  This type is deprecated. Use "double" instead.
+
+- .. index:: rtems_event_set
+  ``rtems.event_set`` is the data
+  type used to manage and manipulate RTEMS event sets
+  with the Event Manager.
+
+- .. index:: rtems_extension
+  ``rtems.extension`` is the return type
+  for RTEMS user extension routines.
+
+- .. index:: rtems_fatal_extension
+  ``rtems.fatal_extension`` is the
+  entry point for a fatal error user extension handler routine.
+
+- .. index:: rtems_id
+  ``rtems.id`` is the data type used
+  to manage and manipulate RTEMS object IDs.
+
+- .. index:: rtems_interrupt_frame
+  ``rtems.interrupt_frame`` is the
+  data structure that defines the format of the interrupt
+  stack frame as it appears to a user ISR.  This data
+  structure may not be defined on all ports.
+
+- .. index:: rtems_interrupt_level
+  ``rtems.interrupt_level`` is the
+  data structure used with the ``rtems.interrupt_disable``,``rtems.interrupt_enable``, and``rtems.interrupt_flash`` routines.  This
+  data type is CPU dependent and usually corresponds to
+  the contents of the processor register containing
+  the interrupt mask level.
+
+- .. index:: rtems_interval
+  ``rtems.interval`` is the data
+  type used to manage and manipulate time intervals.
+  Intervals are non-negative integers used to measure
+  the length of time in clock ticks.
+
+- .. index:: rtems_isr
+  ``rtems.isr`` is the return type
+  of a function implementing an RTEMS ISR.
+
+- .. index:: rtems_isr_entry
+  ``rtems.isr_entry`` is the address of
+  the entry point to an RTEMS ISR.  It is equivalent to the
+  entry point of the function implementing the ISR.
+
+- .. index:: rtems_mp_packet_classes
+  ``rtems.mp_packet_classes`` is the
+  enumerated type which specifies the categories of
+  multiprocessing messages.  For example, one of the
+  classes is for messages that must be processed by
+  the Task Manager.
+
+- .. index:: rtems_mode
+  ``rtems.mode`` is the data type
+  used to manage and dynamically manipulate the execution
+  mode of an RTEMS task.
+
+- .. index:: rtems_mpci_entry
+  ``rtems.mpci_entry`` is the return type
+  of an RTEMS MPCI routine.
+
+- .. index:: rtems_mpci_get_packet_entry
+  ``rtems.mpci_get_packet_entry`` is the address of
+  the entry point to the get packet routine for an MPCI implementation.
+
+- .. index:: rtems_mpci_initialization_entry
+  ``rtems.mpci_initialization_entry`` is the address of
+  the entry point to the initialization routine for an MPCI implementation.
+
+- .. index:: rtems_mpci_receive_packet_entry
+  ``rtems.mpci_receive_packet_entry`` is the address of
+  the entry point to the receive packet routine for an MPCI implementation.
+
+- .. index:: rtems_mpci_return_packet_entry
+  ``rtems.mpci_return_packet_entry`` is the address of
+  the entry point to the return packet routine for an MPCI implementation.
+
+- .. index:: rtems_mpci_send_packet_entry
+  ``rtems.mpci_send_packet_entry`` is the address of
+  the entry point to the send packet routine for an MPCI implementation.
+
+- .. index:: rtems_mpci_table
+  ``rtems.mpci_table`` is the data structure
+  containing the configuration information for an MPCI.
+
+- .. index:: rtems_name
+  ``rtems.name`` is the data type used to
+  contain the name of a Classic API object.  It is an unsigned
+  thirty-two bit integer which can be treated as a numeric
+  value or initialized using ``rtems.build_name`` to
+  contain four ASCII characters.
+
+- .. index:: rtems_option
+  ``rtems.option`` is the data type
+  used to specify which behavioral options the caller desires.
+  It is commonly used with potentially blocking directives to specify
+  whether the caller is willing to block or return immediately with an error
+  indicating that the resource was not available.
+
+- .. index:: rtems_packet_prefix
+  ``rtems.packet_prefix`` is the data structure
+  that defines the first bytes in every packet sent between nodes
+  in an RTEMS multiprocessor system.  It contains routing information
+  that is expected to be used by the MPCI layer.
+
+- .. index:: rtems_signal_set
+  ``rtems.signal_set`` is the data
+  type used to manage and manipulate RTEMS signal sets
+  with the Signal Manager.
+
+- .. index:: int8_t
+  ``int8_t`` is the C99 data type that corresponds to signed eight
+  bit integers.  This data type is defined by RTEMS in a manner that
+  ensures it is portable across different target processors.
+
+- .. index:: int16_t
+  ``int16_t`` is the C99 data type that corresponds to signed
+  sixteen bit integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+- .. index:: int32_t
+  ``int32_t`` is the C99 data type that corresponds to signed
+  thirty-two bit integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+- .. index:: int64_t
+  ``int64_t`` is the C99 data type that corresponds to signed
+  sixty-four bit integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+- .. index:: rtems_single
+  ``rtems.single`` is the RTEMS data
+  type that corresponds to single precision floating point
+  on the target hardware.
+  This type is deprecated. Use "float" instead.
+
+- .. index:: rtems_status_codes
+  ``rtems.status_codes`` is the return type for most
+  RTEMS services.  This is an enumerated type of approximately twenty-five
+  values.  In general, when a service returns a particular status code, it
+  indicates that a very specific error condition has occurred.
+
+- .. index:: rtems_task
+  ``rtems.task`` is the return type for an
+  RTEMS Task.
+
+- .. index:: rtems_task_argument
+  ``rtems.task_argument`` is the data
+  type for the argument passed to each RTEMS task. In RTEMS 4.7
+  and older, this is an unsigned thirty-two bit integer.  In
+  RTEMS 4.8 and newer, this is based upon the C99 type ``uintptr_t``
+  which is guaranteed to be an integer large enough to hold a
+  pointer on the target architecture.
+
+- .. index:: rtems_task_begin_extension
+  ``rtems.task_begin_extension`` is the
+  entry point for a task beginning execution user extension handler routine.
+
+- .. index:: rtems_task_create_extension
+  ``rtems.task_create_extension`` is the
+  entry point for a task creation execution user extension handler routine.
+
+- .. index:: rtems_task_delete_extension
+  ``rtems.task_delete_extension`` is the
+  entry point for a task deletion user extension handler routine.
+
+- .. index:: rtems_task_entry
+  ``rtems.task_entry`` is the address of
+  the entry point to an RTEMS ASR.  It is equivalent to the
+  entry point of the function implementing the ASR.
+
+- .. index:: rtems_task_exitted_extension
+  ``rtems.task_exitted_extension`` is the
+  entry point for a task exitted user extension handler routine.
+
+- .. index:: rtems_task_priority
+  ``rtems.task_priority`` is the data type
+  used to manage and manipulate task priorities.
+
+- .. index:: rtems_task_restart_extension
+  ``rtems.task_restart_extension`` is the
+  entry point for a task restart user extension handler routine.
+
+- .. index:: rtems_task_start_extension
+  ``rtems.task_start_extension`` is the
+  entry point for a task start user extension handler routine.
+
+- .. index:: rtems_task_switch_extension
+  ``rtems.task_switch_extension`` is the
+  entry point for a task context switch user extension handler routine.
+
+- .. index:: rtems_tcb
+  ``rtems.tcb`` is the data structure associated
+  with each task in an RTEMS system.
+
+- .. index:: rtems_time_of_day
+  ``rtems.time_of_day`` is the data structure
+  used to manage and manipulate calendar time in RTEMS.
+
+- .. index:: rtems_timer_service_routine
+  ``rtems.timer_service_routine`` is the
+  return type for an RTEMS Timer Service Routine.
+
+- .. index:: rtems_timer_service_routine_entry
+  ``rtems.timer_service_routine_entry`` is the address of
+  the entry point to an RTEMS TSR.  It is equivalent to the
+  entry point of the function implementing the TSR.
+
+- .. index:: rtems_vector_number
+  ``rtems.vector_number`` is the data
+  type used to manage and manipulate interrupt vector numbers.
+
+- .. index:: uint8_t
+  ``uint8_t`` is the C99 data type that corresponds to unsigned
+  eight bit integers.  This data type is defined by RTEMS in a manner that
+  ensures it is portable across different target processors.
+
+- .. index:: uint16_t
+  ``uint16_t`` is the C99 data type that corresponds to unsigned
+  sixteen bit integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+- .. index:: uint32_t
+  ``uint32_t`` is the C99 data type that corresponds to unsigned
+  thirty-two bit integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+- .. index:: uint64_t
+  ``uint64_t`` is the C99 data type that corresponds to unsigned
+  sixty-four bit integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+- .. index:: uintptr_t
+  ``uintptr_t`` is the C99 data type that corresponds to the
+  unsigned integer type that is of sufficient size to represent addresses
+  as unsigned integers.  This data type is defined by RTEMS in a manner
+  that ensures it is portable across different target processors.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Initialization Manager
+######################
+
+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:
+
+- ``rtems.initialize_executive`` - Initialize RTEMS
+
+- ``rtems.shutdown_executive`` - Shutdown RTEMS
+
+Background
+==========
+
+Initialization Tasks
+--------------------
+.. index:: 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 ensure
+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.
+
+System Initialization
+---------------------
+
+System Initialization begins with board reset and continues
+through RTEMS initialization, initialization of all device
+drivers, and eventually a context switch to the first user
+task.  Remember, that interrupts are disabled during
+initialization and the *initialization context* is not
+a task in any sense and the user should be very careful
+during initialization.
+
+The BSP must ensure that the there is enough stack
+space reserved for the initialization context to
+successfully execute the initialization routines for
+all device drivers and, in multiprocessor configurations, the
+Multiprocessor Communications Interface Layer initialization
+routine.
+
+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
+default implementation of this task consists of an infinite
+loop. RTEMS allows the Idle Task body to be replaced by a CPU
+specific implementation, a BSP specific implementation or an
+application specific implementation.
+
+The Idle Task is preemptible and *WILL* be preempted when
+any other task is made ready to execute.  This characteristic is
+critical to the overall behavior of any application.
+
+Initialization Manager Failure
+------------------------------
+
+The ``rtems.fatal_error_occurred`` directive will
+be invoked from ``rtems.initialize_executive``
+for any of the following reasons:
+
+- If either the Configuration Table or the CPU Dependent
+  Information Table is not provided.
+
+- 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.
+
+- If the size of the RTEMS RAM Workspace is not large
+  enough to initialize and configure the system.
+
+- If the interrupt stack size specified is too small.
+
+- If multiprocessing is configured and the node entry in
+  the Multiprocessor Configuration Table is not between one and
+  the maximum_nodes entry.
+
+- If a multiprocessor system is being configured and no
+  Multiprocessor Communications Interface is specified.
+
+- 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.
+
+- If any of the user initialization tasks cannot be
+  created or started successfully.
+
+A discussion of RTEMS actions when a fatal error occurs
+may be found :ref:`Fatal Error Manager Announcing a Fatal Error <Fatal-Error-Manager-Announcing-a-Fatal-Error>`.
+
+Operations
+==========
+
+Initializing RTEMS
+------------------
+
+The Initialization Manager ``rtems.initialize_executive``
+directives is called by the ``boot_card`` routine.  The ``boot_card``
+routine is invoked by the Board Support Package once a basic C run-time
+environment is set up.  This consists of
+
+- a valid and accessible text section, read-only data, read-write data and
+  zero-initialized data,
+
+- an initialization stack large enough to initialize the rest of the Board
+  Support Package, RTEMS and the device drivers,
+
+- all registers and components mandated by Application Binary Interface, and
+
+- disabled interrupts.
+
+The ``rtems.initialize_executive`` directive uses a system
+initialization linker set to initialize only those parts of the overall RTEMS
+feature set that is necessary for a particular application.  See :ref:`Linker
+Sets <Linker-Sets>`.  Each RTEMS feature used the application may optionally register an
+initialization handler.  The system initialization API is available via``#included <rtems/sysinit.h>``.
+
+A list of all initialization steps follows.  Some steps are optional depending
+on the requested feature set of the application.  The initialization steps are
+execute in the order presented here.
+
+:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS`
+    The work areas consisting of C Program Heap and the RTEMS Workspace are
+    initialized by the Board Support Package.  This step is mandatory.
+
+:dfn:`RTEMS_SYSINIT_BSP_START`
+    Basic initialization step provided by the Board Support Package.  This step is
+    mandatory.
+
+:dfn:`RTEMS_SYSINIT_DATA_STRUCTURES`
+    This directive is called when the Board Support Package has completed its basic
+    initialization and allows RTEMS to initialize the application environment based
+    upon the information in the Configuration Table, User Initialization Tasks
+    Table, Device Driver Table, User Extension Table, Multiprocessor Configuration
+    Table, and the Multiprocessor Communications Interface (MPCI) Table.
+
+:dfn:`RTEMS_SYSINIT_BSP_LIBC`
+    Depending on the application configuration the IO library and root filesystem
+    is initialized.  This step is mandatory.
+
+:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS`
+    This directive performs initialization that must occur between basis RTEMS data
+    structure initialization and device driver initialization.  In particular, in a
+    multiprocessor configuration, this directive will create the MPCI Server Task.
+
+:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
+    Initialization step performed right before device drivers are initialized
+    provided by the Board Support Package.  This step is mandatory.
+
+:dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS`
+    This step initializes all statically configured device drivers and performs all
+    RTEMS initialization which requires device drivers to be initialized.  This
+    step is mandatory.
+    In a multiprocessor configuration, this service will initialize the
+    Multiprocessor Communications Interface (MPCI) and synchronize with the other
+    nodes in the system.
+
+:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS`
+    Initialization step performed right after device drivers are initialized
+    provided by the Board Support Package.  This step is mandatory.
+
+The final action of the ``rtems.initialize_executive`` directive
+is to start multitasking.  RTEMS does not return to the initialization context
+and the initialization stack may be re-used for interrupt processing.
+
+Many of RTEMS actions during initialization are based upon
+the contents of the Configuration Table.  For more information
+regarding the format and contents of this table, please refer
+to the chapter :ref:`Configuring a System <Configuring-a-System>`.
+
+The final action 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.  The initialization stack may be re-used
+for interrupt processing.
+
+Shutting Down RTEMS
+-------------------
+
+The ``rtems.shutdown_executive`` directive is invoked by the
+application to end multitasking and terminate the system.
+
+Directives
+==========
+
+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.
+
+INITIALIZE_EXECUTIVE - Initialize RTEMS
+---------------------------------------
+.. index:: initialize RTEMS
+.. index:: start multitasking
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+Iterates through the system initialization linker set and invokes the
+registered handlers.  The final step is to start multitasking.
+
+**NOTES:**
+
+This directive should be called by ``boot_card`` only.
+
+This directive *does not return* to the caller.  Errors in the initialization
+sequence are usually fatal and lead to a system termination.
+
+SHUTDOWN_EXECUTIVE - Shutdown RTEMS
+-----------------------------------
+.. index:: shutdown RTEMS
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Shutdown_Executive(
+    Status : in     RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive is called when the application wishes to shutdown RTEMS.  The
+system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and
+the specified ``result`` code.
+
+**NOTES:**
+
+This directive *must* be the last RTEMS directive
+invoked by an application and it *does not return* to the caller.
+
+This directive may be called any time.
+
+.. COMMENT: COPYRIGHT (c) 1988-2014.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Task Manager
+############
+
+.. index:: tasks
+
+Introduction
+============
+
+The task manager provides a comprehensive set of directives to
+create, delete, and administer tasks.  The directives provided
+by the task manager are:
+
+- ``rtems.task_create`` - Create a task
+
+- ``rtems.task_ident`` - Get ID of a task
+
+- ``rtems.task_self`` - Obtain ID of caller
+
+- ``rtems.task_start`` - Start a task
+
+- ``rtems.task_restart`` - Restart a task
+
+- ``rtems.task_delete`` - Delete a task
+
+- ``rtems.task_suspend`` - Suspend a task
+
+- ``rtems.task_resume`` - Resume a task
+
+- ``rtems.task_is_suspended`` - Determine if a task is suspended
+
+- ``rtems.task_set_priority`` - Set task priority
+
+- ``rtems.task_mode`` - Change current taskâs mode
+
+- ``rtems.task_wake_after`` - Wake up after interval
+
+- ``rtems.task_wake_when`` - Wake up when specified
+
+- ``rtems.iterate_over_all_threads`` - Iterate Over Tasks
+
+- ``rtems.task_variable_add`` - Associate per task variable
+
+- ``rtems.task_variable_get`` - Obtain value of a a per task variable
+
+- ``rtems.task_variable_delete`` - Remove per task variable
+
+Background
+==========
+
+Task Definition
+---------------
+.. index:: 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:
+
+- a "dispatchable" unit.
+
+- an entity to which the processor is allocated.
+
+- an atomic unit of a real-time, multiprocessor system.
+
+- single threads of execution which concurrently compete for resources.
+
+- a sequence of closely related computations which can execute
+  concurrently with other computational sequences.
+
+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).
+
+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, 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.
+
+Task States
+-----------
+.. index:: task states
+
+A task may exist in one of the following five states:
+
+- *executing* - Currently scheduled to the CPU
+
+- *ready* - May be scheduled to the CPU
+
+- *blocked* - Unable to be scheduled to the CPU
+
+- *dormant* - Created task that is not started
+
+- *non-existent* - Uncreated or deleted task
+
+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.
+
+Task Priority
+-------------
+.. index:: task priority
+.. index:: priority, task
+.. index:: rtems_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.  The data type``rtems.task_priority`` is used to store task
+priorities.
+
+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.
+
+Task Mode
+---------
+.. index:: task mode
+.. index:: rtems_task_mode
+
+A taskâs execution mode is a combination of the following
+four components:
+
+- preemption
+
+- ASR processing
+
+- timeslicing
+
+- interrupt level
+
+It is used to modify RTEMSâ scheduling process and to alter the
+execution environment of the task.  The data type``rtems.task_mode`` is used to manage the task
+execution mode... index:: preemption
+
+The preemption component allows a task to determine when control of the
+processor is relinquished.  If preemption is disabled
+(``RTEMS.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
+(``RTEMS.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... index:: timeslicing
+
+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 (``RTEMS.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 (``RTEMS.NO_TIMESLICE``), then the task will be
+allowed to execute until a task of higher priority is made ready.  If``RTEMS.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 (``RTEMS.ASR``), then signals
+sent to the task will be processed the next time the task executes.  If
+signal processing is disabled (``RTEMS.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... index:: interrupt level, task
+
+The interrupt level component is used to determine which
+interrupts will be enabled when the task is executing.``RTEMS.INTERRUPT_LEVEL(n)``
+specifies that the task will execute at interrupt level n.
+
+- ``RTEMS.PREEMPT`` - enable preemption (default)
+
+- ``RTEMS.NO_PREEMPT`` - disable preemption
+
+- ``RTEMS.NO_TIMESLICE`` - disable timeslicing (default)
+
+- ``RTEMS.TIMESLICE`` - enable timeslicing
+
+- ``RTEMS.ASR`` - enable ASR processing (default)
+
+- ``RTEMS.NO_ASR`` - disable ASR processing
+
+- ``RTEMS.INTERRUPT_LEVEL(0)`` - enable all interrupts (default)
+
+- ``RTEMS.INTERRUPT_LEVEL(n)`` - execute at interrupt level n
+
+The set of default modes may be selected by specifying the``RTEMS.DEFAULT_MODES`` constant.
+
+Accessing Task Arguments
+------------------------
+.. index:: task arguments
+.. index:: task prototype
+
+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:
+
+.. code:: c
+
+    procedure User_Task (
+    Argument : in    RTEMS.Task_Argument_Ptr
+    );
+
+Application tasks requiring more information may view this
+single argument as an index into an array of parameter blocks.
+
+Floating Point Considerations
+-----------------------------
+.. index:: floating point
+
+Creating a task with the ``RTEMS.FLOATING_POINT`` attribute
+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 ``RTEMS.NO_FLOATING_POINT`` tasks. Saving
+and restoring the context of a ``RTEMS.FLOATING_POINT`` task
+takes longer than that of a ``RTEMS.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``RTEMS.FLOATING_POINT`` task is dispatched and that task was
+not the last task to utilize the coprocessor.  In a system with only one``RTEMS.FLOATING_POINT`` task, the state of the numeric
+coprocessor will never be saved or restored.
+
+Although the overhead imposed by ``RTEMS.FLOATING_POINT`` tasks
+is minimal, some applications may wish to completely avoid the overhead
+associated with ``RTEMS.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``RTEMS.NO_FLOATING_POINT`` task can utilize the numeric
+coprocessor without incurring the overhead of a``RTEMS.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 ``RTEMS.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``RTEMS.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 ``RTEMS.NO_FLOATING_POINT``
+whether created as ``RTEMS.FLOATING_POINT`` or``RTEMS.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 ``RTEMS.FLOATING_POINT``
+attribute.  The consequence of a ``RTEMS.NO_FLOATING_POINT``
+task attempting to access the floating point unit is CPU dependent but will
+generally result in an exception condition.
+
+Per Task Variables
+------------------
+.. index:: per task variables
+
+Per task variables are deprecated, see the warning below.
+
+Per task variables are used to support global variables whose value
+may be unique to a task. After indicating that a variable should be
+treated as private (i.e. per-task) the task can access and modify the
+variable, but the modifications will not appear to other tasks, and
+other tasksâ modifications to that variable will not affect the value
+seen by the task.  This is accomplished by saving and restoring the
+variableâs value each time a task switch occurs to or from the calling task.
+
+The value seen by other tasks, including those which have not added the
+variable to their set and are thus accessing the variable as a common
+location shared among tasks, cannot be affected by a task once it has
+added a variable to its local set.  Changes made to the variable by
+other tasks will not affect the value seen by a task which has added the
+variable to its private set.
+
+This feature can be used when a routine is to be spawned repeatedly as
+several independent tasks.  Although each task will have its own stack,
+and thus separate stack variables, they will all share the same static and
+global variables.  To make a variable not shareable (i.e. a "global" variable
+that is specific to a single task), the tasks can call``rtems_task_variable_add`` to make a separate copy of the variable
+for each task, but all at the same physical address.
+
+Task variables increase the context switch time to and from the
+tasks that own them so it is desirable to minimize the number of
+task variables.  One efficient method is to have a single task
+variable that is a pointer to a dynamically allocated structure
+containing the taskâs private "global" data.
+
+A critical point with per-task variables is that each task must separately
+request that the same global variable is per-task private.
+
+*WARNING*: Per-Task variables are inherently broken on SMP systems. They
+only work correctly when there is one task executing in the system and
+that task is the logical owner of the value in the per-task variableâs
+location. There is no way for a single memory image to contain the
+correct value for each task executing on each core. Consequently,
+per-task variables are disabled in SMP configurations of RTEMS.
+Instead the application developer should
+consider the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys
+are not enabled in all RTEMS configurations.
+
+Building a Task Attribute Set
+-----------------------------
+.. index:: task attributes, building
+
+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:
+
+- ``RTEMS.NO_FLOATING_POINT`` - does not use coprocessor (default)
+
+- ``RTEMS.FLOATING_POINT`` - uses numeric coprocessor
+
+- ``RTEMS.LOCAL`` - local task (default)
+
+- ``RTEMS.GLOBAL`` - global task
+
+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 ``RTEMS.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 ``RTEMS.FLOATING_POINT`` or``RTEMS.LOCAL or RTEMS.FLOATING_POINT``.
+The attribute_set parameter can be set to``RTEMS.FLOATING_POINT`` because ``RTEMS.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``RTEMS.GLOBAL or RTEMS.FLOATING_POINT``.
+
+Building a Mode and Mask
+------------------------
+.. index:: task mode, building
+
+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:
+
+- ``RTEMS.PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and enables preemption
+
+- ``RTEMS.NO_PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and disables preemption
+
+- ``RTEMS.NO_TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and disables timeslicing
+
+- ``RTEMS.TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and enables timeslicing
+
+- ``RTEMS.ASR`` is masked by``RTEMS.ASR_MASK`` and enables ASR processing
+
+- ``RTEMS.NO_ASR`` is masked by``RTEMS.ASR_MASK`` and disables ASR processing
+
+- ``RTEMS.INTERRUPT_LEVEL(0)`` is masked by``RTEMS.INTERRUPT_MASK`` and enables all interrupts
+
+- ``RTEMS.INTERRUPT_LEVEL(n)`` is masked by``RTEMS.INTERRUPT_MASK`` and sets interrupts level n
+
+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 ``RTEMS.DEFAULT_MODES`` and the
+mask ``RTEMS.ALL_MODE_MASKS`` should be used.
+
+The following example demonstrates the mode and mask parameters used with
+the ``rtems.task_mode``
+directive to place a task at interrupt level 3 and make it
+non-preemptible.  The mode should be set to``RTEMS.INTERRUPT_LEVEL(3)  or
+RTEMS.NO_PREEMPT`` to indicate the desired preemption mode and
+interrupt level, while the mask parameter should be set to``RTEMS.INTERRUPT_MASK or
+RTEMS.NO_PREEMPT_MASK`` to indicate that the calling taskâs
+interrupt level and preemption mode are being altered.
+
+Operations
+==========
+
+Creating Tasks
+--------------
+
+The ``rtems.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.
+
+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 ``rtems.task_create``
+directive, the task ID is
+stored in a user provided location.  Second, the task ID may be
+obtained later using the ``rtems.task_ident``
+directive.  The task ID is
+used by other directives to manipulate this task.
+
+Starting and Restarting Tasks
+-----------------------------
+
+The ``rtems.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 ``rtems.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 ``rtems.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.
+
+Suspending and Resuming Tasks
+-----------------------------
+
+The ``rtems.task_suspend``
+directive is used to place either the caller or
+another task into a suspended state.  The task remains suspended
+until a ``rtems.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 ``rtems.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.
+
+Suspending a task which is already suspended or resuming a
+task which is not suspended is considered an error.
+The ``rtems.task_is_suspended`` can be used to
+determine if a task is currently suspended.
+
+Delaying the Currently Executing Task
+-------------------------------------
+
+The ``rtems.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 ``rtems.task_wake_after``
+directive with a delay
+interval of ``RTEMS.YIELD_PROCESSOR`` ticks will yield the
+processor to any other ready task of equal or greater priority and remain
+ready to execute.
+
+The ``rtems.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.
+
+Changing Task Priority
+----------------------
+
+The ``rtems.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``RTEMS.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 ``rtems.task_restart``
+directive resets the priority of a task to its
+original value.
+
+Changing Task Mode
+------------------
+
+The ``rtems.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 ``rtems.task_restart``
+directive resets the mode of a task to its
+original value.
+
+Task Deletion
+-------------
+
+RTEMS provides the ``rtems.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``rtems.task_wake_after`` and``rtems.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.
+
+Transition Advice for Obsolete Directives
+-----------------------------------------
+
+Notepads
+~~~~~~~~
+
+Task notepads and the associated directives``rtems.task_get_note`` and``rtems.task_set_note`` were removed after the 4.11 Release
+Series. These were never thread-safe to access and subject to conflicting
+use of the notepad index by libraries which were designed independently.
+
+It is recommended that applications be modified to use services
+which are thread safe and not subject to issues with multiple applications
+conflicting over the key (e.g. notepad index) selection. For most
+applications, POSIX Keys should be used. These are available in all RTEMS
+build configurations. It is also possible that Thread Local Storage is
+an option for some use cases.
+
+Directives
+==========
+
+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.
+
+TASK_CREATE - Create a task
+---------------------------
+.. index:: create a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Create (
+    Name             : in     RTEMS.Name;
+    Initial_Priority : in     RTEMS.Task_Priority;
+    Stack_Size       : in     RTEMS.Unsigned32;
+    Initial_Modes    : in     RTEMS.Mode;
+    Attribute_Set    : in     RTEMS.Attribute;
+    ID               :    out RTEMS.ID;
+    Result           :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task created successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - invalid task name
+``RTEMS.INVALID_PRIORITY`` - invalid task priority
+``RTEMS.MP_NOT_CONFIGURED`` - multiprocessing not configured
+``RTEMS.TOO_MANY`` - too many tasks created
+``RTEMS.UNSATISFIED`` - not enough memory for stack/FP context
+``RTEMS.TOO_MANY`` - too many global objects
+
+**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``RTEMS.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 ``RTEMS.NO_FLOATING_POINT`` attribute.
+If the ``RTEMS.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 ``rtems.task_start``.
+
+**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.
+
+If the requested stack size is less than the configured
+minimum stack size, then RTEMS will use the configured
+minimum as the stack size for this task.  In addition
+to being able to specify the task stack size as a integer,
+there are two constants which may be specified:
+
+- ``RTEMS.MINIMUM_STACK_SIZE``
+  is the minimum stack size *RECOMMENDED* for use on this processor.
+  This value is selected by the RTEMS developers conservatively to
+  minimize the risk of blown stacks for most user applications.
+  Using this constant when specifying the task stack size, indicates
+  that the stack size will be at least``RTEMS.MINIMUM_STACK_SIZE`` bytes in size.  If the
+  user configured minimum stack size is larger than the recommended
+  minimum, then it will be used.
+
+- ``RTEMS.CONFIGURED_MINIMUM_STACK_SIZE``
+  indicates that this task is to be created with a stack size
+  of the minimum stack size that was configured by the application.
+  If not explicitly configured by the application, the default
+  configured minimum stack size is the processor dependent value``RTEMS.MINIMUM_STACK_SIZE``.  Since this uses
+  the configured minimum stack size value, you may get a stack
+  size that is smaller or larger than the recommended minimum.  This
+  can be used to provide large stacks for all tasks on complex
+  applications or small stacks on applications that are trying
+  to conserve memory.
+
+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:
+
+- ``RTEMS.NO_FLOATING_POINT`` - does not use coprocessor (default)
+
+- ``RTEMS.FLOATING_POINT`` - uses numeric coprocessor
+
+- ``RTEMS.LOCAL`` - local task (default)
+
+- ``RTEMS.GLOBAL`` - global task
+
+The following task mode constants are defined by RTEMS:
+
+- ``RTEMS.PREEMPT`` - enable preemption (default)
+
+- ``RTEMS.NO_PREEMPT`` - disable preemption
+
+- ``RTEMS.NO_TIMESLICE`` - disable timeslicing (default)
+
+- ``RTEMS.TIMESLICE`` - enable timeslicing
+
+- ``RTEMS.ASR`` - enable ASR processing (default)
+
+- ``RTEMS.NO_ASR`` - disable ASR processing
+
+- ``RTEMS.INTERRUPT_LEVEL(0)`` - enable all interrupts (default)
+
+- ``RTEMS.INTERRUPT_LEVEL(n)`` - execute at interrupt level n
+
+The interrupt level portion of the task execution mode
+supports a maximum of 256 interrupt levels.  These levels are
+mapped onto the interrupt levels actually supported by the
+target processor in a processor dependent fashion.
+
+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.
+
+TASK_IDENT - Get ID of a task
+-----------------------------
+.. index:: get ID of a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Ident (
+    Name   : in     RTEMS.Name;
+    Node   : in     RTEMS.Node;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task identified successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - invalid task name
+``RTEMS.INVALID_NODE`` - invalid node id
+
+**DESCRIPTION:**
+
+This directive obtains the task id associated with the task name
+specified in name.  A task may obtain its own id by specifying``RTEMS.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.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+If node is ``RTEMS.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.
+
+TASK_SELF - Obtain ID of caller
+-------------------------------
+.. index:: obtain ID of caller
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Task_Self return RTEMS.ID;
+
+**DIRECTIVE STATUS CODES:**
+
+Returns the object Id of the calling task.
+
+**DESCRIPTION:**
+
+This directive returns the Id of the calling task.
+
+**NOTES:**
+
+If called from an interrupt service routine, this directive
+will return the Id of the interrupted task.
+
+TASK_START - Start a task
+-------------------------
+.. index:: starting a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Start (
+    ID          : in     RTEMS.ID;
+    Entry_Point : in     RTEMS.Task_Entry;
+    Argument    : in     RTEMS.Task_Argument;
+    Result      :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - ask started successfully
+``RTEMS.INVALID_ADDRESS`` - invalid task entry point
+``RTEMS.INVALID_ID`` - invalid task id
+``RTEMS.INCORRECT_STATE`` - task not in the dormant state
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - cannot start remote task
+
+**DESCRIPTION:**
+
+This directive readies the task, specified by ``id``, 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.  The type of this numeric argument is an unsigned
+integer type with the property that any valid pointer to void can be converted
+to this type and then converted back to a pointer to void.  The result will
+compare equal to the original pointer.
+
+**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 ``rtems.task_start`` directive.
+
+TASK_RESTART - Restart a task
+-----------------------------
+.. index:: restarting a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Restart (
+    ID       : in     RTEMS.ID;
+    Argument : in     RTEMS.Task_Argument;
+    Result   :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task restarted successfully
+``RTEMS.INVALID_ID`` - task id invalid
+``RTEMS.INCORRECT_STATE`` - task never started
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - cannot restart remote task
+
+**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.  The type of this
+numeric argument is an unsigned integer type with the property that any valid
+pointer to void can be converted to this type and then converted back to a
+pointer to void.  The result will compare equal to the original pointer.  This
+new argument may be used to distinguish
+between the initial ``rtems.task_start``
+of the task and any ensuing calls
+to ``rtems.task_restart``
+of the task.  This can be beneficial in deleting
+a task.  Instead of deleting a task using
+the ``rtems.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.
+
+**NOTES:**
+
+If id is ``RTEMS.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 ``RTEMS.GLOBAL`` option.
+
+TASK_DELETE - Delete a task
+---------------------------
+.. index:: deleting a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task deleted successfully
+``RTEMS.INVALID_ID`` - task id invalid
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - cannot restart remote task
+
+**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 ``RTEMS.FLOATING_POINT``, its
+floating point context area.  RTEMS does not reclaim the
+following resources: region segments, partition buffers,
+semaphores, timers, or rate monotonic periods.
+
+**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 (``RTEMS.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 ``RTEMS.GLOBAL`` option.
+
+TASK_SUSPEND - Suspend a task
+-----------------------------
+.. index:: suspending a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Suspend (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task suspended successfully
+``RTEMS.INVALID_ID`` - task id invalid
+``RTEMS.ALREADY_SUSPENDED`` - task already suspended
+
+**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 ``rtems.task_resume``
+directive for this task and any blocked state
+has been removed.
+
+**NOTES:**
+
+The requesting task can suspend itself by specifying ``RTEMS.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.
+
+If the task specified by id is already suspended, then the``RTEMS.ALREADY_SUSPENDED`` status code is returned.
+
+TASK_RESUME - Resume a task
+---------------------------
+.. index:: resuming a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Resume (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task resumed successfully
+``RTEMS.INVALID_ID`` - task id invalid
+``RTEMS.INCORRECT_STATE`` - task not suspended
+
+**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.
+
+**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.
+
+If the task specified by id is not suspended, then the``RTEMS.INCORRECT_STATE`` status code is returned.
+
+TASK_IS_SUSPENDED - Determine if a task is Suspended
+----------------------------------------------------
+.. index:: is task suspended
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Is_Suspended (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task is NOT suspended
+``RTEMS.ALREADY_SUSPENDED`` - task is currently suspended
+``RTEMS.INVALID_ID`` - task id invalid
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive returns a status code indicating whether or
+not the specified task is currently suspended.
+
+**NOTES:**
+
+This operation is not currently supported on remote tasks.
+
+TASK_SET_PRIORITY - Set task priority
+-------------------------------------
+.. index:: rtems_task_set_priority
+.. index:: current task priority
+.. index:: set task priority
+.. index:: get task priority
+.. index:: obtain task priority
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Set_Priority (
+    ID           : in     RTEMS.ID;
+    New_Priority : in     RTEMS.Task_Priority;
+    Old_Priority :    out RTEMS.Task_Priority;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task priority set successfully
+``RTEMS.INVALID_ID`` - invalid task id
+``RTEMS.INVALID_ADDRESS`` - invalid return argument pointer
+``RTEMS.INVALID_PRIORITY`` - invalid task priority
+
+**DESCRIPTION:**
+
+This directive manipulates the priority of the task specified by
+id.  An id of ``RTEMS.SELF`` is used to indicate
+the calling task.  When new_priority is not equal to``RTEMS.CURRENT_PRIORITY``, the specified
+taskâs previous priority is returned in old_priority.  When
+new_priority is ``RTEMS.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.
+
+**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.
+
+In case the new priority equals the current priority of the task, then nothing
+happens.
+
+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.
+
+TASK_MODE - Change the current task mode
+----------------------------------------
+.. index:: current task mode
+.. index:: set task mode
+.. index:: get task mode
+.. index:: set task preemption mode
+.. index:: get task preemption mode
+.. index:: obtain task mode
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Mode (
+    Mode_Set          : in     RTEMS.Mode;
+    Mask              : in     RTEMS.Mode;
+    Previous_Mode_Set : in     RTEMS.Mode;
+    Result            :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - task mode set successfully
+``RTEMS.INVALID_ADDRESS`` - ``previous_mode_set`` is NULL
+
+**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.
+
+**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 disabled.  For
+a task to be timesliced, that task must have both preemption and
+timeslicing enabled.
+
+A task can obtain its current execution mode, without modifying
+it, by calling this directive with a mask value of``RTEMS.CURRENT_MODE``.
+
+To temporarily disable the processing of a valid ASR, a task
+should call this directive with the ``RTEMS.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:
+
+- ``RTEMS.PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and enables preemption
+
+- ``RTEMS.NO_PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and disables preemption
+
+- ``RTEMS.NO_TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and disables timeslicing
+
+- ``RTEMS.TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and enables timeslicing
+
+- ``RTEMS.ASR`` is masked by``RTEMS.ASR_MASK`` and enables ASR processing
+
+- ``RTEMS.NO_ASR`` is masked by``RTEMS.ASR_MASK`` and disables ASR processing
+
+- ``RTEMS.INTERRUPT_LEVEL(0)`` is masked by``RTEMS.INTERRUPT_MASK`` and enables all interrupts
+
+- ``RTEMS.INTERRUPT_LEVEL(n)`` is masked by``RTEMS.INTERRUPT_MASK`` and sets interrupts level n
+
+TASK_WAKE_AFTER - Wake up after interval
+----------------------------------------
+.. index:: delay a task for an interval
+.. index:: wake up after an interval
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Wake_After (
+    Ticks  : in     RTEMS.Interval;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - always successful
+
+**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 ``rtems.clock_tick``
+directive automatically updates the delay period.
+
+**NOTES:**
+
+Setting the system date and time with the``rtems.clock_set`` directive
+has no effect on a ``rtems.task_wake_after`` blocked task.
+
+A task may give up the processor and remain in the ready state
+by specifying a value of ``RTEMS.YIELD_PROCESSOR`` in ticks.
+
+The maximum timer interval that can be specified is the maximum
+value which can be represented by the uint32_t type.
+
+A clock tick is required to support the functionality of this directive.
+
+TASK_WAKE_WHEN - Wake up when specified
+---------------------------------------
+.. index:: delay a task until a wall time
+.. index:: wake up at a wall time
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Wake_When (
+    Time_Buffer : in     RTEMS.Time_Of_Day;
+    Result      :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - awakened at date/time successfully
+``RTEMS.INVALID_ADDRESS`` - ``time_buffer`` is NULL
+``RTEMS.INVALID_TIME_OF_DAY`` - invalid time buffer
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+
+**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.
+
+**NOTES:**
+
+The ticks portion of time_buffer record is ignored.  The
+timing granularity of this directive is a second.
+
+A clock tick is required to support the functionality of this directive.
+
+ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
+---------------------------------------------
+.. index:: iterate over all threads
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+**DIRECTIVE STATUS CODES: NONE**
+
+**DESCRIPTION:**
+
+This directive iterates over all of the existant threads in the
+system and invokes ``routine`` on each of them.  The user should
+be careful in accessing the contents of ``the_thread``.
+
+This routine is intended for use in diagnostic utilities and is
+not intented for routine use in an operational system.
+
+**NOTES:**
+
+There is NO protection while this routine is called.  Thus it is
+possible that ``the_thread`` could be deleted while this is operating.
+By not having protection, the user is free to invoke support routines
+from the C Library which require semaphores for data structures.
+
+TASK_VARIABLE_ADD - Associate per task variable
+-----------------------------------------------
+.. index:: per-task variable
+.. index:: task private variable
+.. index:: task private data
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    type Task_Variable_Dtor is access procedure (
+    Argument : in     RTEMS.Address;
+    );
+    procedure Task_Variable_Add (
+    ID            : in     RTEMS.ID;
+    Task_Variable : in     RTEMS.Address;
+    Dtor          : in     RTEMS.Task_Variable_Dtor;
+    Result        :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - per task variable added successfully
+``RTEMS.INVALID_ADDRESS`` - ``task_variable`` is NULL
+``RTEMS.INVALID_ID`` - invalid task id
+``RTEMS.NO_MEMORY`` - invalid task id
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive adds the memory location specified by the
+ptr argument to the context of the given task.  The variable will
+then be private to the task.  The task can access and modify the
+variable, but the modifications will not appear to other tasks, and
+other tasksâ modifications to that variable will not affect the value
+seen by the task.  This is accomplished by saving and restoring the
+variableâs value each time a task switch occurs to or from the calling task.
+If the dtor argument is non-NULL it specifies the address of a âdestructorâ
+function which will be called when the task is deleted.  The argument
+passed to the destructor function is the taskâs value of the variable.
+
+**NOTES:**
+
+This directive is deprecated and task variables will be removed.
+
+Task variables increase the context switch time to and from the
+tasks that own them so it is desirable to minimize the number of
+task variables.  One efficient method
+is to have a single task variable that is a pointer to a dynamically
+allocated structure containing the taskâs private âglobalâ data.
+In this case the destructor function could be âfreeâ.
+
+Per-task variables are disabled in SMP configurations and this service
+is not available.
+
+TASK_VARIABLE_GET - Obtain value of a per task variable
+-------------------------------------------------------
+.. index:: get per-task variable
+.. index:: obtain per-task variable
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Variable_Get (
+    ID                  : in     RTEMS.ID;
+    Task_Variable       :    out RTEMS.Address;
+    Task_Variable_Value :    out RTEMS.Address;
+    Result              :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - per task variable obtained successfully
+``RTEMS.INVALID_ADDRESS`` - ``task_variable`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``task_variable_value`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``task_variable`` is not found
+``RTEMS.NO_MEMORY`` - invalid task id
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive looks up the private value of a task variable for a
+specified task and stores that value in the location pointed to by
+the result argument.  The specified task is usually not the calling
+task, which can get its private value by directly accessing the variable.
+
+**NOTES:**
+
+This directive is deprecated and task variables will be removed.
+
+If you change memory which ``task_variable_value`` points to,
+remember to declare that memory as volatile, so that the compiler
+will optimize it correctly.  In this case both the pointer``task_variable_value`` and data referenced by ``task_variable_value``
+should be considered volatile.
+
+Per-task variables are disabled in SMP configurations and this service
+is not available.
+
+TASK_VARIABLE_DELETE - Remove per task variable
+-----------------------------------------------
+.. index:: per-task variable
+.. index:: task private variable
+.. index:: task private data
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Task_Variable_Delete (
+    ID                  : in     RTEMS.ID;
+    Task_Variable       :    out RTEMS.Address;
+    Result              :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - per task variable deleted successfully
+``RTEMS.INVALID_ID`` - invalid task id
+``RTEMS.NO_MEMORY`` - invalid task id
+``RTEMS.INVALID_ADDRESS`` - ``task_variable`` is NULL
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive removes the given location from a taskâs context.
+
+**NOTES:**
+
+This directive is deprecated and task variables will be removed.
+
+Per-task variables are disabled in SMP configurations and this service
+is not available.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Interrupt Manager
+#################
+
+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:
+
+- ``rtems.interrupt_catch`` - Establish an ISR
+
+- ``rtems.interrupt_disable`` - Disable Interrupts
+
+- ``rtems.interrupt_enable`` - Enable Interrupts
+
+- ``rtems.interrupt_flash`` - Flash Interrupt
+
+- ``rtems.interrupt_local_disable`` - Disable Interrupts on Current Processor
+
+- ``rtems.interrupt_local_enable`` - Enable Interrupts on Current Processor
+
+- ``rtems.interrupt_lock_initialize`` - Initialize an ISR Lock
+
+- ``rtems.interrupt_lock_acquire`` - Acquire an ISR Lock
+
+- ``rtems.interrupt_lock_release`` - Release an ISR Lock
+
+- ``rtems.interrupt_lock_acquire_isr`` - Acquire an ISR Lock from ISR
+
+- ``rtems.interrupt_lock_release_isr`` - Release an ISR Lock from ISR
+
+- ``rtems.interrupt_is_in_progress`` - Is an ISR in Progress
+
+Background
+==========
+
+Processing an Interrupt
+-----------------------
+.. index:: interrupt processing
+
+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 Ada 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... index:: rtems_vector_number
+
+The ``rtems.interrupt_catch``
+directive connects a procedure to
+an interrupt vector.  The vector number is managed using
+the ``rtems.vector_number`` data type.
+
+The interrupt service routine is assumed
+to abide by these conventions and have a prototype similar to
+the following:
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+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:
+
+- ** *The interrupt manager must be used for all ISRs which
+  may be interrupted by the highest priority ISR which invokes an
+  RTEMS directive.*
+
+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.
+
+RTEMS Interrupt Levels
+----------------------
+.. index:: 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 Applications Supplement document for a specific
+target processor.
+
+Disabling of Interrupts by RTEMS
+--------------------------------
+.. index:: disabling interrupts
+
+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
+ensure 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 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.
+
+Operations
+==========
+
+Establishing an ISR
+-------------------
+
+The ``rtems.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.
+
+Directives Allowed from an ISR
+------------------------------
+
+Using the interrupt manager ensures 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:
+
+- Task Management
+  Although it is acceptable to operate on the RTEMS_SELF task (e.g.
+  the currently executing task), while in an ISR, this will refer
+  to the interrupted task.  Most of the time, it is an application
+  implementation error to use RTEMS_SELF from an ISR.
+  - rtems_task_suspend
+  - rtems_task_resume
+
+- Interrupt Management
+  - rtems_interrupt_enable
+  - rtems_interrupt_disable
+  - rtems_interrupt_flash
+  - rtems_interrupt_lock_acquire
+  - rtems_interrupt_lock_release
+  - rtems_interrupt_lock_acquire_isr
+  - rtems_interrupt_lock_release_isr
+  - rtems_interrupt_is_in_progress
+  - rtems_interrupt_catch
+
+- Clock Management
+  - rtems_clock_set
+  - rtems_clock_get
+  - rtems_clock_get_tod
+  - rtems_clock_get_tod_timeval
+  - rtems_clock_get_seconds_since_epoch
+  - rtems_clock_get_ticks_per_second
+  - rtems_clock_get_ticks_since_boot
+  - rtems_clock_get_uptime
+  - rtems_clock_set_nanoseconds_extension
+  - rtems_clock_tick
+
+- Timer Management
+  - rtems_timer_cancel
+  - rtems_timer_reset
+  - rtems_timer_fire_after
+  - rtems_timer_fire_when
+  - rtems_timer_server_fire_after
+  - rtems_timer_server_fire_when
+
+- Event Management
+  - rtems_event_send
+  - rtems_event_system_send
+  - rtems_event_transient_send
+
+- Semaphore Management
+  - rtems_semaphore_release
+
+- Message Management
+  - rtems_message_queue_send
+  - rtems_message_queue_urgent
+
+- Signal Management
+  - rtems_signal_send
+
+- Dual-Ported Memory Management
+  - rtems_port_external_to_internal
+  - rtems_port_internal_to_external
+
+- IO Management
+  The following services are safe to call from an ISR if and only if
+  the device driver service invoked is also safe.  The IO Manager itself
+  is safe but the invoked driver entry point may or may not be.
+  - rtems_io_initialize
+  - rtems_io_open
+  - rtems_io_close
+  - rtems_io_read
+  - rtems_io_write
+  - rtems_io_control
+
+- Fatal Error Management
+  - rtems_fatal
+  - rtems_fatal_error_occurred
+
+- Multiprocessing
+  - rtems_multiprocessing_announce
+
+Directives
+==========
+
+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.
+
+INTERRUPT_CATCH - Establish an ISR
+----------------------------------
+.. index:: establish an ISR
+.. index:: install an ISR
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - ISR established successfully
+``RTEMS.INVALID_NUMBER`` - illegal vector number
+``RTEMS.INVALID_ADDRESS`` - illegal ISR entry point or invalid ``old_isr_handler``
+
+**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``.
+
+To release an interrupt vector, pass the old handlerâs address obtained
+when the vector was first capture.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+INTERRUPT_DISABLE - Disable Interrupts
+--------------------------------------
+.. index:: disable interrupts
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Interrupt_Disable return RTEMS.ISR_Level;
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive disables all maskable interrupts and returns
+the previous ``level``.  A later invocation of the``rtems.interrupt_enable`` directive should be used to
+restore the interrupt level.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+This directive is only available on uni-processor configurations.  The
+directive ``rtems.interrupt_local_disable`` is available on all
+configurations.
+
+INTERRUPT_ENABLE - Enable Interrupts
+------------------------------------
+.. index:: enable interrupts
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Interrupt_Enable (
+    Level : in     RTEMS.ISR_Level
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive enables maskable interrupts to the ``level``
+which was returned by a previous call to``rtems.interrupt_disable``.
+Immediately prior to invoking this directive, maskable interrupts should
+be disabled by a call to ``rtems.interrupt_disable``
+and will be enabled when this directive returns to the caller.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+This directive is only available on uni-processor configurations.  The
+directive ``rtems.interrupt_local_enable`` is available on all
+configurations.
+
+INTERRUPT_FLASH - Flash Interrupts
+----------------------------------
+.. index:: flash interrupts
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Interrupt_Flash (
+    Level : in     RTEMS.ISR_Level
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive temporarily enables maskable interrupts to the ``level``
+which was returned by a previous call to``rtems.interrupt_disable``.
+Immediately prior to invoking this directive, maskable interrupts should
+be disabled by a call to ``rtems.interrupt_disable``
+and will be redisabled when this directive returns to the caller.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+This directive is only available on uni-processor configurations.  The
+directives ``rtems.interrupt_local_disable`` and``rtems.interrupt_local_enable`` is available on all
+configurations.
+
+INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
+-----------------------------------------------------------------
+.. index:: disable interrupts
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive disables all maskable interrupts and returns
+the previous ``level``.  A later invocation of the``rtems.interrupt_local_enable`` directive should be used to
+restore the interrupt level.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+On SMP configurations this will not ensure system wide mutual exclusion.  Use
+interrupt locks instead.
+
+INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
+---------------------------------------------------------------
+.. index:: enable interrupts
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive enables maskable interrupts to the ``level``
+which was returned by a previous call to``rtems.interrupt_local_disable``.
+Immediately prior to invoking this directive, maskable interrupts should
+be disabled by a call to ``rtems.interrupt_local_disable``
+and will be enabled when this directive returns to the caller.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
+--------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+Initializes an interrupt lock.
+
+**NOTES:**
+
+Concurrent initialization leads to unpredictable results.
+
+INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+Interrupts will be disabled.  On SMP configurations this directive acquires a
+SMP lock.
+
+**NOTES:**
+
+This directive will not cause the calling thread to be preempted.  This
+directive can be used in thread and interrupt context.
+
+INTERRUPT_LOCK_RELEASE - Release an ISR Lock
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+The interrupt status will be restored.  On SMP configurations this directive
+releases a SMP lock.
+
+**NOTES:**
+
+This directive will not cause the calling thread to be preempted.  This
+directive can be used in thread and interrupt context.
+
+INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
+---------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+The interrupt status will remain unchanged.  On SMP configurations this
+directive acquires a SMP lock.
+
+In case the corresponding interrupt service routine can be interrupted by
+higher priority interrupts and these interrupts enter the critical section
+protected by this lock, then the result is unpredictable.
+
+**NOTES:**
+
+This directive should be called from the corresponding interrupt service
+routine.
+
+INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
+---------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+The interrupt status will remain unchanged.  On SMP configurations this
+directive releases a SMP lock.
+
+**NOTES:**
+
+This directive should be called from the corresponding interrupt service
+routine.
+
+INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
+------------------------------------------------
+.. index:: is interrupt in progress
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Interrupt_Is_In_Progress return RTEMS.Boolean;
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns ``TRUE`` if the processor is currently
+servicing an interrupt and ``FALSE`` otherwise.  A return value
+of ``TRUE`` indicates that the caller is an interrupt service
+routine, *NOT* a task.  The directives available to an interrupt
+service routine are restricted.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Clock Manager
+#############
+
+.. index:: clock
+
+Introduction
+============
+
+The clock manager provides support for time of day
+and other time related capabilities.  The directives provided by
+the clock manager are:
+
+- ``rtems.clock_set`` - Set date and time
+
+- ``rtems.clock_get`` - Get date and time information
+
+- ``rtems.clock_get_tod`` - Get date and time in TOD format
+
+- ``rtems.clock_get_tod_timeval`` - Get date and time in timeval format
+
+- ``rtems.clock_get_seconds_since_epoch`` - Get seconds since epoch
+
+- ``rtems.clock_get_ticks_per_second`` - Get ticks per second
+
+- ``rtems.clock_get_ticks_since_boot`` - Get current ticks counter value
+
+- ``rtems.clock_tick_later`` - Get tick value in the future
+
+- ``rtems.clock_tick_later_usec`` - Get tick value in the future in microseconds
+
+- ``rtems.clock_tick_before`` - Is tick value is before a point in time
+
+- ``rtems.clock_get_uptime`` - Get time since boot
+
+- ``rtems.clock_get_uptime_timeval`` - Get time since boot in timeval format
+
+- ``rtems.clock_get_uptime_seconds`` - Get seconds since boot
+
+- ``rtems.clock_get_uptime_nanoseconds`` - Get nanoseconds since boot
+
+- ``rtems.clock_set_nanoseconds_extension`` - Install the nanoseconds since last tick handler
+
+- ``rtems.clock_tick`` - Announce a clock tick
+
+Background
+==========
+
+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 ``rtems.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.
+
+.. _Clock-Manager-Time-and-Date-Data-Structures:
+
+Time and Date Data Structures
+-----------------------------
+
+The clock facilities of the clock manager operate
+upon calendar time.  These directives utilize the following date
+and time record for the native time and date format:
+
+.. code:: c
+
+    type Time_Of_Day is
+    record
+    Year    : RTEMS.Unsigned32; -- year, A.D.
+    Month   : RTEMS.Unsigned32; -- month, 1 .. 12
+    Day     : RTEMS.Unsigned32; -- day, 1 .. 31
+    Hour    : RTEMS.Unsigned32; -- hour, 0 .. 23
+    Minute  : RTEMS.Unsigned32; -- minute, 0 .. 59
+    Second  : RTEMS.Unsigned32; -- second, 0 .. 59
+    Ticks   : RTEMS.Unsigned32; -- elapsed ticks between seconds
+    end record;
+
+The native date and time format is the only format
+supported when setting the system date and time using the``rtems.clock_set`` directive.  Some applications
+expect to operate on a "UNIX-style" date and time data structure.  The``rtems.clock_get_tod_timeval`` always returns
+the date and time in ``struct timeval`` format.  The``rtems.clock_get`` directive can optionally return
+the current date and time in this format.
+
+The ``struct timeval`` data structure has two fields: ``tv_sec``
+and ``tv_usec`` which are seconds and microseconds, respectively.
+The ``tv_sec`` field in this data structure is the number of seconds
+since the POSIX epoch of January 1, 1970 but will never be prior to
+the RTEMS epoch of January 1, 1988.
+
+Clock Tick and Timeslicing
+--------------------------
+.. index:: 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 ``rtems.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.
+
+Delays
+------
+.. index:: 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``rtems.task_wake_after``
+and ``rtems.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.
+
+Timeouts
+--------
+.. index:: timeouts
+
+Timeouts are a special type of timer automatically
+created when the timeout option is used on the``rtems.message_queue_receive``,``rtems.event_receive``,``rtems.semaphore_obtain`` and``rtems.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.
+
+Operations
+==========
+
+Announcing a Tick
+-----------------
+
+RTEMS provides the ``rtems.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``rtems.clock_tick`` directive per second.  The
+frequency of ``rtems.clock_tick``
+calls determines the resolution
+(granularity) for all time dependent RTEMS actions.  For
+example, calling ``rtems.clock_tick``
+ten times per second yields a higher
+resolution than calling ``rtems.clock_tick``
+two times per second.  The ``rtems.clock_tick``
+directive is responsible for maintaining both
+calendar time and the dynamic set of timers.
+
+Setting the Time
+----------------
+
+The ``rtems.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 ``rtems.clock_set`` directive.
+
+Obtaining the Time
+------------------
+
+The ``rtems.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``rtems.clock_get`` directive is
+dependent on the option selected by the caller.  This
+is specified using one of the following constants
+associated with the enumerated type``rtems.clock_get_options``:.. index:: rtems_clock_get_options
+
+- ``RTEMS.CLOCK_GET_TOD`` - obtain native style date and time
+
+- ``RTEMS.CLOCK_GET_TIME_VALUE`` - obtain UNIX-style
+  date and time
+
+- ``RTEMS.CLOCK_GET_TICKS_SINCE_BOOT`` - obtain number of ticks
+  since RTEMS was initialized
+
+- ``RTEMS.CLOCK_GET_SECONDS_SINCE_EPOCH`` - obtain number
+  of seconds since RTEMS epoch
+
+- ``RTEMS.CLOCK_GET_TICKS_PER_SECOND`` - obtain number of clock
+  ticks per second
+
+Calendar time operations will return an error code if
+invoked before the date and time have been set.
+
+Directives
+==========
+
+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.
+
+CLOCK_SET - Set date and time
+-----------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: set the time of day
+
+.. code:: c
+
+    procedure Clock_Set (
+    Time_Buffer : in     RTEMS.Time_Of_Day;
+    Result      :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - date and time set successfully
+``RTEMS.INVALID_ADDRESS`` - ``time_buffer`` is NULL
+``RTEMS.INVALID_CLOCK`` - invalid time of day
+
+**DESCRIPTION:**
+
+This directive sets the system date and time.  The
+date, time, and ticks in the time_buffer record are all
+range-checked, and an error is returned if any one is out of its
+valid range.
+
+**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``rtems.clock_set`` is required to re-initialize
+the system date and time to application specific specifications.
+
+CLOCK_GET - Get date and time information
+-----------------------------------------
+.. index:: obtain the time of day
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Clock_Get (
+    Option      : in     RTEMS.Clock_Get_Options;
+    Time_Buffer : in     RTEMS.Address;
+    Result      :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - current time obtained successfully
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+``RTEMS.INVALID_ADDRESS`` - ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive is deprecated.
+
+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 ``RTEMS.CLOCK_GET_SECONDS_SINCE_EPOCH``,``RTEMS.CLOCK_GET_TOD``, or``RTEMS.CLOCK_GET_TIME_VALUE``) and the date and time
+has not been set with a previous call to``rtems.clock_set``, then the``RTEMS.NOT_DEFINED`` status code is returned.
+The caller can always obtain the number of ticks per second (option is``RTEMS.CLOCK_GET_TICKS_PER_SECOND``) and the number of
+ticks since the executive was initialized option is``RTEMS.CLOCK_GET_TICKS_SINCE_BOOT``).
+
+The ``option`` argument may taken on any value of the enumerated
+type ``rtems_clock_get_options``.  The data type expected for``time_buffer`` is based on the value of ``option`` as
+indicated below:.. index:: rtems_clock_get_options
+
+- ``RTEMS.Clock_Get_TOD`` - Address of an variable of
+  type RTEMS.Time_Of_Day
+
+- ``RTEMS.Clock_Get_Seconds_Since_Epoch`` - Address of an
+  variable of type RTEMS.Interval
+
+- ``RTEMS.Clock_Get_Ticks_Since_Boot`` - Address of an
+  variable of type RTEMS.Interval
+
+- ``RTEMS.Clock_Get_Ticks_Per_Second`` - Address of an
+  variable of type RTEMS.Interval
+
+- ``RTEMS.Clock_Get_Time_Value`` - Address of an variable of
+  type RTEMS.Clock_Time_Value
+
+**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``rtems.clock_set`` is required to re-initialize the
+system date and time to application specific specifications.
+
+CLOCK_GET_TOD - Get date and time in TOD format
+-----------------------------------------------
+.. index:: obtain the time of day
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Clock_Get_TOD (
+    Time_Buffer : in     RTEMS.Time_Of_Day;
+    Result      :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - current time obtained successfully
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+``RTEMS.INVALID_ADDRESS`` - ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive obtains the system date and time.  If the date and time
+has not been set with a previous call to``rtems.clock_set``, then the``RTEMS.NOT_DEFINED`` status code is returned.
+
+**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``rtems.clock_set`` is required to re-initialize the
+system date and time to application specific specifications.
+
+CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
+-----------------------------------------------------------
+.. index:: obtain the time of day
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Clock_Get_TOD_Timeval (
+    Time   : in     RTEMS.Timeval;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - current time obtained successfully
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+``RTEMS.INVALID_ADDRESS`` - ``time`` is NULL
+
+**DESCRIPTION:**
+
+This directive obtains the system date and time in POSIX``struct timeval`` format.  If the date and time
+has not been set with a previous call to``rtems.clock_set``, then the``RTEMS.NOT_DEFINED`` status code is returned.
+
+**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``rtems.clock_set`` is required to re-initialize the
+system date and time to application specific specifications.
+
+CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
+-------------------------------------------------------
+.. index:: obtain seconds since epoch
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Clock_Get_Seconds_Since_Epoch(
+    The_Interval :    out RTEMS.Interval;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - current time obtained successfully
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+``RTEMS.INVALID_ADDRESS`` - ``the_interval`` is NULL
+
+**DESCRIPTION:**
+
+This directive returns the number of seconds since the RTEMS
+epoch and the current system date and time.  If the date and time
+has not been set with a previous call to``rtems.clock_set``, then the``RTEMS.NOT_DEFINED`` status code is returned.
+
+**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``rtems.clock_set`` is required to re-initialize the
+system date and time to application specific specifications.
+
+CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
+-------------------------------------------------
+.. index:: obtain seconds since epoch
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Clock_Get_Ticks_Per_Seconds
+    return RTEMS.Interval;
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns the number of clock ticks per second.  This
+is strictly based upon the microseconds per clock tick that the
+application has configured.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
+------------------------------------------------------------
+.. index:: obtain ticks since boot
+.. index:: get current ticks counter value
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Clock_Get_Ticks_Since_Boot
+    return RTEMS.Interval;
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns the current tick counter value.  With a 1ms clock tick,
+this counter overflows after 50 days since boot.  This is the historical
+measure of uptime in an RTEMS system.  The newer service``rtems.clock_get_uptime`` is another and potentially more
+accurate way of obtaining similar information.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+CLOCK_TICK_LATER - Get tick value in the future
+-----------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DESCRIPTION:**
+
+Returns the ticks counter value delta ticks in the future.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
+--------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DESCRIPTION:**
+
+Returns the ticks counter value at least delta microseconds in the future.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+CLOCK_TICK_BEFORE - Is tick value is before a point in time
+-----------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DESCRIPTION:**
+
+Returns true if the current ticks counter value indicates a time before the
+time specified by the tick value and false otherwise.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+**EXAMPLE:**
+
+.. code:: c
+
+    status busy( void )
+    {
+    rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
+    do {
+    if ( ok() ) {
+    return success;
+    }
+    } while ( rtems_clock_tick_before( timeout ) );
+    return timeout;
+    }
+
+CLOCK_GET_UPTIME - Get the time since boot
+------------------------------------------
+.. index:: clock get uptime
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Clock_Get_Uptime (
+    Uptime :    out RTEMS.Timespec;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - clock tick processed successfully
+``RTEMS.INVALID_ADDRESS`` - ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive returns the seconds and nanoseconds since the
+system was booted.  If the BSP supports nanosecond clock
+accuracy, the time reported will probably be different on every
+call.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
+--------------------------------------------------------------------
+.. index:: clock get uptime
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns the seconds and microseconds since the
+system was booted.  If the BSP supports nanosecond clock
+accuracy, the time reported will probably be different on every
+call.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
+-----------------------------------------------------
+.. index:: clock get uptime
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+The system uptime in seconds.
+
+**DESCRIPTION:**
+
+This directive returns the seconds since the system was booted.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
+-------------------------------------------------------------
+.. index:: clock get nanoseconds uptime
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+The system uptime in nanoseconds.
+
+**DESCRIPTION:**
+
+This directive returns the nanoseconds since the system was booted.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
+---------------------------------------------------------------------------------
+.. index:: clock set nanoseconds extension
+.. index:: nanoseconds extension
+.. index:: nanoseconds time accuracy
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - clock tick processed successfully
+``RTEMS.INVALID_ADDRESS`` - ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive is used by the Clock device driver to install the``routine`` which will be invoked by the internal RTEMS method used to
+obtain a highly accurate time of day.  It is usually called during
+the initialization of the driver.
+
+When the ``routine`` is invoked, it will determine the number of
+nanoseconds which have elapsed since the last invocation of
+the ``rtems.clock_tick`` directive.  It should do
+this as quickly as possible with as little impact as possible
+on the device used as a clock source.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+This directive is called as part of every service to obtain the
+current date and time as well as timestamps.
+
+CLOCK_TICK - Announce a clock tick
+----------------------------------
+.. index:: clock tick
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Clock_Tick (
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - clock tick processed successfully
+
+**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.
+
+**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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Timer Manager
+#############
+
+.. index:: timers
+
+Introduction
+============
+
+The timer manager provides support for timer
+facilities.  The directives provided by the timer manager are:
+
+- ``rtems.timer_create`` - Create a timer
+
+- ``rtems.timer_ident`` - Get ID of a timer
+
+- ``rtems.timer_cancel`` - Cancel a timer
+
+- ``rtems.timer_delete`` - Delete a timer
+
+- ``rtems.timer_fire_after`` - Fire timer after interval
+
+- ``rtems.timer_fire_when`` - Fire timer when specified
+
+- ``rtems.timer_initiate_server`` - Initiate server for task-based timers
+
+- ``rtems.timer_server_fire_after`` - Fire task-based timer after interval
+
+- ``rtems.timer_server_fire_when`` - Fire task-based timer when specified
+
+- ``rtems.timer_reset`` - Reset an interval timer
+
+Background
+==========
+
+Required Support
+----------------
+
+A clock tick is required to support the functionality provided by this manager.
+
+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
+either the ``rtems.clock_tick`` directive or
+a special Timer Server task 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``rtems.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 ensure 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.
+
+Timer Server
+------------
+
+The Timer Server task is responsible for executing the timer
+service routines associated with all task-based timers.
+This task executes at a priority higher than any RTEMS application
+task, and is created non-preemptible, and thus can be viewed logically as
+the lowest priority interrupt.
+
+By providing a mechanism where timer service routines execute
+in task rather than interrupt space, the application is
+allowed a bit more flexibility in what operations a timer
+service routine can perform.  For example, the Timer Server
+can be configured to have a floating point context in which case
+it would be safe to perform floating point operations
+from a task-based timer.  Most of the time, executing floating
+point instructions from an interrupt service routine
+is not considered safe. However, since the Timer Server task
+is non-preemptible, only directives allowed from an ISR can be
+called in the timer service routine.
+
+The Timer Server is designed to remain blocked until a
+task-based timer fires.  This reduces the execution overhead
+of the Timer Server.
+
+Timer Service Routines
+----------------------
+
+The timer service routine should adhere to Ada calling
+conventions and have a prototype similar to the following:
+
+.. code:: c
+
+    procedure User_Routine(
+    Timer_ID  : in     RTEMS.ID;
+    User_Data : in     System.Address
+    );
+
+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.
+
+Operations
+==========
+
+Creating a Timer
+----------------
+
+The ``rtems.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.
+
+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``rtems.timer_create``
+directive, the timer ID is stored in a user provided location.
+Second, the timer ID may be obtained later using the``rtems.timer_ident`` directive.  The timer ID
+is used by other directives to manipulate this timer.
+
+Initiating an Interval Timer
+----------------------------
+
+The ``rtems.timer_fire_after``
+and ``rtems.timer_server_fire_after``
+directives initiate 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``rtems.clock_tick`` directive if it was initiated
+by the ``rtems.timer_fire_after`` directive
+and from the Timer Server task if initiated by the``rtems.timer_server_fire_after`` directive.
+
+Initiating a Time of Day Timer
+------------------------------
+
+The ``rtems.timer_fire_when``
+and ``rtems.timer_server_fire_when``
+directive initiate 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``rtems.clock_tick`` directive
+by the ``rtems.timer_fire_when`` directive
+and from the Timer Server task if initiated by the``rtems.timer_server_fire_when`` directive.
+
+Canceling a Timer
+-----------------
+
+The ``rtems.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 ``rtems.timer_reset``,``rtems.timer_fire_after``, and``rtems.timer_fire_when`` directives.
+
+Resetting a Timer
+-----------------
+
+The ``rtems.timer_reset`` directive is used to restore an
+interval timer initiated by a previous invocation of``rtems.timer_fire_after`` or``rtems.timer_server_fire_after`` to
+its original interval length.  If the
+timer has not been used or the last usage of this timer
+was by the ``rtems.timer_fire_when``
+or ``rtems.timer_server_fire_when``
+directive, then an error is returned.  The timer service routine
+is not changed or fired by this directive.
+
+Initiating the Timer Server
+---------------------------
+
+The ``rtems.timer_initiate_server`` directive is used to
+allocate and start the execution of the Timer Server task.  The
+application can specify both the stack size and attributes of the
+Timer Server.  The Timer Server executes at a priority higher than
+any application task and thus the user can expect to be preempted
+as the result of executing the ``rtems.timer_initiate_server``
+directive.
+
+Deleting a Timer
+----------------
+
+The ``rtems.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.
+
+Directives
+==========
+
+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.
+
+TIMER_CREATE - Create a timer
+-----------------------------
+.. index:: create a timer
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Create (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer created successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - invalid timer name
+``RTEMS.TOO_MANY`` - too many timers created
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+TIMER_IDENT - Get ID of a timer
+-------------------------------
+.. index:: obtain the ID of a timer
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Ident (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer identified successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - timer name not found
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+TIMER_CANCEL - Cancel a timer
+-----------------------------
+.. index:: cancel a timer
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Cancel (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer canceled successfully
+``RTEMS.INVALID_ID`` - invalid timer id
+
+**DESCRIPTION:**
+
+This directive cancels the timer id.  This timer will
+be reinitiated by the next invocation of ``rtems.timer_reset``,``rtems.timer_fire_after``, or``rtems.timer_fire_when`` with this id.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+TIMER_DELETE - Delete a timer
+-----------------------------
+.. index:: delete a timer
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer deleted successfully
+``RTEMS.INVALID_ID`` - invalid timer id
+
+**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.
+
+**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.
+
+TIMER_FIRE_AFTER - Fire timer after interval
+--------------------------------------------
+.. index:: fire a timer after an interval
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Fire_After (
+    ID        : in     RTEMS.ID;
+    Ticks     : in     RTEMS.Interval;
+    Routine   : in     RTEMS.Timer_Service_Routine;
+    User_Data : in     RTEMS.Address;
+    Result    :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer initiated successfully
+``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
+``RTEMS.INVALID_ID`` - invalid timer id
+``RTEMS.INVALID_NUMBER`` - invalid interval
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+TIMER_FIRE_WHEN - Fire timer when specified
+-------------------------------------------
+.. index:: fire a timer at wall time
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Fire_When (
+    ID        : in     RTEMS.ID;
+    Wall_Time : in     RTEMS.Time_Of_Day;
+    Routine   : in     RTEMS.Timer_Service_Routine;
+    User_Data : in     RTEMS.Address;
+    Result    :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer initiated successfully
+``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``wall_time`` is NULL
+``RTEMS.INVALID_ID`` - invalid timer id
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+``RTEMS.INVALID_CLOCK`` - invalid time of day
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+TIMER_INITIATE_SERVER - Initiate server for task-based timers
+-------------------------------------------------------------
+.. index:: initiate the Timer Server
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Initiate_Server (
+    Server_Priority : in     RTEMS.Task_Priority;
+    Stack_Size      : in     RTEMS.Unsigned32;
+    Attribute_Set   : in     RTEMS.Attribute;
+    Result          :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - Timer Server initiated successfully
+``RTEMS.TOO_MANY`` - too many tasks created
+
+**DESCRIPTION:**
+
+This directive initiates the Timer Server task.  This task
+is responsible for executing all timers initiated via the``rtems.timer_server_fire_after`` or``rtems.timer_server_fire_when`` directives.
+
+**NOTES:**
+
+This directive could cause the calling task to be preempted.
+
+The Timer Server task is created using the``rtems.task_create`` service and must be accounted
+for when configuring the system.
+
+Even through this directive invokes the ``rtems.task_create``
+and ``rtems.task_start`` directives, it should only fail
+due to resource allocation problems.
+
+TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
+--------------------------------------------------------------
+.. index:: fire task-based a timer after an interval
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Fire_Server_After (
+    ID        : in     RTEMS.ID;
+    Ticks     : in     RTEMS.Interval;
+    Routine   : in     RTEMS.Timer_Service_Routine;
+    User_Data : in     RTEMS.Address;
+    Result    :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer initiated successfully
+``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
+``RTEMS.INVALID_ID`` - invalid timer id
+``RTEMS.INVALID_NUMBER`` - invalid interval
+``RTEMS.INCORRECT_STATE`` - Timer Server not initiated
+
+**DESCRIPTION:**
+
+This directive initiates the timer specified by id and specifies
+that when it fires it will be executed by the Timer Server.
+
+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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
+-------------------------------------------------------------
+.. index:: fire a task-based timer at wall time
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Fire_Server_When (
+    ID        : in     RTEMS.ID;
+    Wall_Time : in     RTEMS.Time_Of_Day;
+    Routine   : in     RTEMS.Timer_Service_Routine;
+    User_Data : in     RTEMS.Address;
+    Result    :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer initiated successfully
+``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``wall_time`` is NULL
+``RTEMS.INVALID_ID`` - invalid timer id
+``RTEMS.NOT_DEFINED`` - system date and time is not set
+``RTEMS.INVALID_CLOCK`` - invalid time of day
+``RTEMS.INCORRECT_STATE`` - Timer Server not initiated
+
+**DESCRIPTION:**
+
+This directive initiates the timer specified by id and specifies
+that when it fires it will be executed by the Timer Server.
+
+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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+TIMER_RESET - Reset an interval timer
+-------------------------------------
+.. index:: reset a timer
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Timer_Reset (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - timer reset successfully
+``RTEMS.INVALID_ID`` - invalid timer id
+``RTEMS.NOT_DEFINED`` - attempted to reset a when or newly created timer
+
+**DESCRIPTION:**
+
+This directive resets the timer associated with id.
+This timer must have been previously initiated with either the``rtems.timer_fire_after`` or``rtems.timer_server_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``rtems.timer_fire_after````rtems.timer_server_fire_after``
+directive used.
+
+**NOTES:**
+
+If the timer has not been used or the last usage of this timer
+was by a ``rtems.timer_fire_when`` or``rtems.timer_server_fire_when``
+directive, then the ``RTEMS.NOT_DEFINED`` error is
+returned.
+
+Restarting a cancelled after timer results in the timer being
+reinitiated with its previous timer service routine and interval.
+
+This directive will not cause the running task to be preempted.
+
+.. COMMENT: COPYRIGHT (c) 1988-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Semaphore Manager
+#################
+
+.. index:: semaphores
+.. index:: binary semaphores
+.. index:: counting semaphores
+.. index:: mutual exclusion
+
+Introduction
+============
+
+The semaphore manager utilizes standard Dijkstra
+counting semaphores to provide synchronization and mutual
+exclusion capabilities.  The directives provided by the
+semaphore manager are:
+
+- ``rtems.semaphore_create`` - Create a semaphore
+
+- ``rtems.semaphore_ident`` - Get ID of a semaphore
+
+- ``rtems.semaphore_delete`` - Delete a semaphore
+
+- ``rtems.semaphore_obtain`` - Acquire a semaphore
+
+- ``rtems.semaphore_release`` - Release a semaphore
+
+- ``rtems.semaphore_flush`` - Unblock all tasks waiting on a semaphore
+
+- ``rtems.semaphore_set_priority`` - Set priority by
+  scheduler for a semaphore
+
+Background
+==========
+
+A semaphore can be viewed as a protected variable
+whose value can be modified only with the``rtems.semaphore_create``,``rtems.semaphore_obtain``, and``rtems.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 ``rtems.semaphore_obtain``
+directive to prevent other tasks from entering the critical section.
+Upon exit from the critical section, the task must issue the``rtems.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 ``rtems.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 ``rtems.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 ``rtems.semaphore_obtain``
+directive when it reaches a synchronization point.  The other task
+performs a corresponding ``rtems.semaphore_release``
+operation when it reaches its synchronization point, thus unblocking
+the pending task.
+
+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``rtems.semaphore_obtain`` must be accompanied with a``rtems.semaphore_release``.  The semaphore will
+only be made available for acquisition by other tasks when the
+outermost ``rtems.semaphore_obtain`` is matched with
+a ``rtems.semaphore_release``.
+
+Simple binary semaphores do not allow nested access and so can be used for task synchronization.
+
+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.
+
+.. _Semaphore-Manager-Priority-Inheritance:
+
+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.
+
+On SMP configurations, in case the task holding the resource and the task that
+blocks attempting to obtain the resource are in different scheduler instances,
+the priority of the holder is raised to the pseudo-interrupt priority (priority
+boosting).  The pseudo-interrupt priority is the highest priority.
+
+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.
+
+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.
+
+.. _Semaphore-Manager-Multiprocessor-Resource-Sharing-Protocol:
+
+Multiprocessor Resource Sharing Protocol
+----------------------------------------
+
+The Multiprocessor Resource Sharing Protocol (MrsP) is defined in *A.
+Burns and A.J.  Wellings, A Schedulability Compatible Multiprocessor Resource
+Sharing Protocol - MrsP, Proceedings of the 25th Euromicro Conference on
+Real-Time Systems (ECRTS 2013), July 2013*.  It is a generalization of the
+Priority Ceiling Protocol to SMP systems.  Each MrsP semaphore uses a ceiling
+priority per scheduler instance.  These ceiling priorities can be specified
+with ``rtems_semaphore_set_priority()``.  A task obtaining or owning a MrsP
+semaphore will execute with the ceiling priority for its scheduler instance as
+specified by the MrsP semaphore object.  Tasks waiting to get ownership of a
+MrsP semaphore will not relinquish the processor voluntarily.  In case the
+owner of a MrsP semaphore gets preempted it can ask all tasks waiting for this
+semaphore to help out and temporarily borrow the right to execute on one of
+their assigned processors.
+
+Building a Semaphore 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:
+
+- ``RTEMS.FIFO`` - tasks wait by FIFO (default)
+
+- ``RTEMS.PRIORITY`` - tasks wait by priority
+
+- ``RTEMS.BINARY_SEMAPHORE`` - restrict values to
+  0 and 1
+
+- ``RTEMS.COUNTING_SEMAPHORE`` - no restriction on values
+  (default)
+
+- ``RTEMS.SIMPLE_BINARY_SEMAPHORE`` - restrict values to
+  0 and 1, do not allow nested access, allow deletion of locked semaphore.
+
+- ``RTEMS.NO_INHERIT_PRIORITY`` - do not use priority
+  inheritance (default)
+
+- ``RTEMS.INHERIT_PRIORITY`` - use priority inheritance
+
+- ``RTEMS.NO_PRIORITY_CEILING`` - do not use priority
+  ceiling (default)
+
+- ``RTEMS.PRIORITY_CEILING`` - use priority ceiling
+
+- ``RTEMS.NO_MULTIPROCESSOR_RESOURCE_SHARING`` - do not use
+  Multiprocessor Resource Sharing Protocol (default)
+
+- ``RTEMS.MULTIPROCESSOR_RESOURCE_SHARING`` - use
+  Multiprocessor Resource Sharing Protocol
+
+- ``RTEMS.LOCAL`` - local semaphore (default)
+
+- ``RTEMS.GLOBAL`` - global semaphore
+
+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``RTEMS.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``rtems.semaphore_create`` directive could be either``RTEMS.PRIORITY`` or ``RTEMS.LOCAL or
+RTEMS.PRIORITY``.  The attribute_set parameter can be set to``RTEMS.PRIORITY`` because ``RTEMS.LOCAL`` is the
+default for all created tasks.  If a similar semaphore were to be known
+globally, then the attribute_set parameter would be``RTEMS.GLOBAL or RTEMS.PRIORITY``.
+
+Some combinatinos of these attributes are invalid.  For example, priority
+ordered blocking discipline must be applied to a binary semaphore in order
+to use either the priority inheritance or priority ceiling functionality.
+The following tree figure illustrates the valid combinations.
+
+.. code:: c
+
+    Not available in ASCII representation
+
+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``rtems.semaphore_obtain`` directive are listed
+in the following table:
+
+- ``RTEMS.WAIT`` - task will wait for semaphore (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+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 ``RTEMS.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``rtems.semaphore_obtain``
+directive should be ``RTEMS.NO_WAIT``.
+
+Operations
+==========
+
+Creating a Semaphore
+--------------------
+
+The ``rtems.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.
+
+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``rtems.semaphore_create`` directive, the
+semaphore ID is stored in a user provided location.  Second,
+the semaphore ID may be obtained later using the``rtems.semaphore_ident`` directive.  The semaphore ID is
+used by other semaphore manager directives to access this
+semaphore.
+
+Acquiring a Semaphore
+---------------------
+
+The ``rtems.semaphore_obtain`` directive is used to acquire the
+specified semaphore.  A simplified version of the``rtems.semaphore_obtain`` directive can be described as follows:
+.. code:: c
+
+    if semaphore's count is greater than zero
+    then decrement semaphore's count
+    else wait for release of semaphore
+    return SUCCESSFUL
+
+When the semaphore cannot be immediately acquired,
+one of the following situations applies:
+
+- By default, the calling task will wait forever to
+  acquire the semaphore.
+
+- Specifying ``RTEMS.NO_WAIT`` forces an immediate return
+  with an error status code.
+
+- Specifying a timeout limits the interval the task will
+  wait before returning with an error status code.
+
+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.
+
+Releasing a Semaphore
+---------------------
+
+The ``rtems.semaphore_release`` directive is used to release
+the specified semaphore.  A simplified version of the``rtems.semaphore_release`` directive can be described as
+follows:
+.. code:: c
+
+    if no tasks are waiting on this semaphore
+    then increment semaphore's count
+    else assign semaphore to a waiting task
+    return SUCCESSFUL
+
+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 ``rtems.semaphore_release``
+will have its priority restored to its normal value.
+
+Deleting a Semaphore
+--------------------
+
+The ``rtems.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.
+
+Directives
+==========
+
+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.
+
+SEMAPHORE_CREATE - Create a semaphore
+-------------------------------------
+.. index:: create a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Semaphore_Create (
+    Name             : in     RTEMS.Name;
+    Count            : in     RTEMS.Unsigned32;
+    Attribute_Set    : in     RTEMS.Attribute;
+    Priority_Ceiling : in     RTEMS.Task_Priority;
+    ID               :    out RTEMS.ID;
+    Result           :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - semaphore created successfully
+``RTEMS.INVALID_NAME`` - invalid semaphore name
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.TOO_MANY`` - too many semaphores created
+``RTEMS.NOT_DEFINED`` - invalid attribute set
+``RTEMS.INVALID_NUMBER`` - invalid starting count for binary semaphore
+``RTEMS.MP_NOT_CONFIGURED`` - multiprocessing not configured
+``RTEMS.TOO_MANY`` - too many global objects
+
+**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.
+
+**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:
+
+- ``RTEMS.FIFO`` - tasks wait by FIFO (default)
+
+- ``RTEMS.PRIORITY`` - tasks wait by priority
+
+- ``RTEMS.BINARY_SEMAPHORE`` - restrict values to
+  0 and 1
+
+- ``RTEMS.COUNTING_SEMAPHORE`` - no restriction on values
+  (default)
+
+- ``RTEMS.SIMPLE_BINARY_SEMAPHORE`` - restrict values to
+  0 and 1, block on nested access, allow deletion of locked semaphore.
+
+- ``RTEMS.NO_INHERIT_PRIORITY`` - do not use priority
+  inheritance (default)
+
+- ``RTEMS.INHERIT_PRIORITY`` - use priority inheritance
+
+- ``RTEMS.NO_PRIORITY_CEILING`` - do not use priority
+  ceiling (default)
+
+- ``RTEMS.PRIORITY_CEILING`` - use priority ceiling
+
+- ``RTEMS.NO_MULTIPROCESSOR_RESOURCE_SHARING`` - do not use
+  Multiprocessor Resource Sharing Protocol (default)
+
+- ``RTEMS.MULTIPROCESSOR_RESOURCE_SHARING`` - use
+  Multiprocessor Resource Sharing Protocol
+
+- ``RTEMS.LOCAL`` - local semaphore (default)
+
+- ``RTEMS.GLOBAL`` - global semaphore
+
+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.
+
+Note that some combinations of attributes are not valid.  See the
+earlier discussion on this.
+
+The total number of global objects, including semaphores, is limited by
+the maximum_global_objects field in the Configuration Table.
+
+It is not allowed to create an initially locked MrsP semaphore and the``RTEMS.INVALID_NUMBER`` status code will be returned on SMP
+configurations in this case.  This prevents lock order reversal problems with
+the allocator mutex.
+
+SEMAPHORE_IDENT - Get ID of a semaphore
+---------------------------------------
+.. index:: get ID of a semaphore
+.. index:: obtain ID of a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Semaphore_Ident (
+    Name   : in     RTEMS.Name;
+    Node   : in     RTEMS.Unsigned32;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - semaphore identified successfully
+``RTEMS.INVALID_NAME`` - semaphore name not found
+``RTEMS.INVALID_NODE`` - invalid node id
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+If node is ``RTEMS.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.
+
+SEMAPHORE_DELETE - Delete a semaphore
+-------------------------------------
+.. index:: delete a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Semaphore_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - semaphore deleted successfully
+``RTEMS.INVALID_ID`` - invalid semaphore id
+``RTEMS.RESOURCE_IN_USE`` - binary semaphore is in use
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote semaphore
+
+**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.
+
+**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 ``RTEMS.GLOBAL`` option.
+
+Proxies, used to represent remote tasks, are
+reclaimed when the semaphore is deleted.
+
+SEMAPHORE_OBTAIN - Acquire a semaphore
+--------------------------------------
+.. index:: obtain a semaphore
+.. index:: lock a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Semaphore_Obtain (
+    ID         : in     RTEMS.ID;
+    Option_Set : in     RTEMS.Option;
+    Timeout    : in     RTEMS.Interval;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - semaphore obtained successfully
+``RTEMS.UNSATISFIED`` - semaphore not available
+``RTEMS.TIMEOUT`` - timed out waiting for semaphore
+``RTEMS.OBJECT_WAS_DELETED`` - semaphore deleted while waiting
+``RTEMS.INVALID_ID`` - invalid semaphore id
+
+**DESCRIPTION:**
+
+This directive acquires the semaphore specified by
+id.  The ``RTEMS.WAIT`` and ``RTEMS.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 ``RTEMS.WAIT`` or``RTEMS.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 ``RTEMS.PRIORITY`` attribute, then the calling task is
+inserted into the queue according to its priority.  However, if the
+semaphore was created with the ``RTEMS.FIFO`` attribute, then
+the calling task is placed at the rear of the wait queue.  If the binary
+semaphore was created with the ``RTEMS.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``RTEMS.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``RTEMS.NO_TIMEOUT``, then the calling task will wait forever.
+If the semaphore is available or the ``RTEMS.NO_WAIT`` option
+component is set, then timeout is ignored.
+
+Deadlock situations are detected for MrsP semaphores and the``RTEMS.UNSATISFIED`` status code will be returned on SMP
+configurations in this case.
+
+**NOTES:**
+
+The following semaphore acquisition option constants
+are defined by RTEMS:
+
+- ``RTEMS.WAIT`` - task will wait for semaphore (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+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 ``RTEMS.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.
+
+A clock tick is required to support the timeout functionality of
+this directive.
+
+It is not allowed to obtain a MrsP semaphore more than once by one task at a
+time (nested access) and the ``RTEMS.UNSATISFIED`` status code will
+be returned on SMP configurations in this case.
+
+SEMAPHORE_RELEASE - Release a semaphore
+---------------------------------------
+.. index:: release a semaphore
+.. index:: unlock a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Semaphore_Release (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - semaphore released successfully
+``RTEMS.INVALID_ID`` - invalid semaphore id
+``RTEMS.NOT_OWNER_OF_RESOURCE`` - calling task does not own semaphore
+``RTEMS.INCORRECT_STATE`` - invalid unlock order
+
+**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.
+
+**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.
+
+The MrsP semaphores must be released in the reversed obtain order, otherwise
+the ``RTEMS.INCORRECT_STATE`` status code will be returned on SMP
+configurations in this case.
+
+SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
+----------------------------------------------------------
+.. index:: flush a semaphore
+.. index:: unblock all tasks waiting on a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Semaphore_Flush (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - semaphore released successfully
+``RTEMS.INVALID_ID`` - invalid semaphore id
+``RTEMS.NOT_DEFINED`` - operation not defined for the protocol of
+the semaphore
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - not supported for remote semaphores
+
+**DESCRIPTION:**
+
+This directive unblocks all tasks waiting on the semaphore specified by
+id.  Since there are tasks blocked on the semaphore, the semaphoreâs
+count is not changed by this directive and thus is zero before and
+after this directive is executed.  Tasks which are unblocked as the
+result of this directive will return from the``rtems.semaphore_obtain`` directive with a
+status code of ``RTEMS.UNSATISFIED`` to indicate
+that the semaphore was not obtained.
+
+This directive may unblock any number of tasks.  Any of the unblocked
+tasks may preempt the running task if the running taskâs preemption mode is
+enabled and an unblocked task has a higher priority than the
+running task.
+
+**NOTES:**
+
+The calling task may be preempted if it causes a
+higher priority task to be made ready for execution.
+
+If the task to be unblocked resides on a different
+node from the semaphore, then the waiting task is
+unblocked, and the proxy used to represent the task is reclaimed.
+
+It is not allowed to flush a MrsP semaphore and the``RTEMS.NOT_DEFINED`` status code will be returned on SMP
+configurations in this case.
+
+SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore
+------------------------------------------------------------------
+.. index:: set priority by scheduler for a semaphore
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ID`` - invalid semaphore or scheduler id
+``RTEMS.INVALID_ADDRESS`` - ``old_priority`` is NULL
+``RTEMS.INVALID_PRIORITY`` - invalid new priority value
+``RTEMS.NOT_DEFINED`` - operation not defined for the protocol of
+the semaphore
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - not supported for remote semaphores
+
+**DESCRIPTION:**
+
+This directive sets the priority value with respect to the specified scheduler
+of a semaphore.
+
+The special priority value ``RTEMS_CURRENT_PRIORITY`` can be used to get the
+current priority value without changing it.
+
+The interpretation of the priority value depends on the protocol of the
+semaphore object.
+
+- The Multiprocessor Resource Sharing Protocol needs a ceiling priority per
+  scheduler instance.  This operation can be used to specify these priority
+  values.
+
+- For the Priority Ceiling Protocol the ceiling priority is used with this
+  operation.
+
+- For other protocols this operation is not defined.
+
+**EXAMPLE:**
+
+.. code:: c
+
+    #include <assert.h>
+    #include <stdlib.h>
+    #include <rtems.h>
+    #define SCHED_A rtems_build_name(' ', ' ', ' ', 'A')
+    #define SCHED_B rtems_build_name(' ', ' ', ' ', 'B')
+    static void Init(rtems_task_argument arg)
+    {
+    rtems_status_code   sc;
+    rtems_id            semaphore_id;
+    rtems_id            scheduler_a_id;
+    rtems_id            scheduler_b_id;
+    rtems_task_priority prio;
+    /* Get the scheduler identifiers \*/
+    sc = rtems_scheduler_ident(SCHED_A, &scheduler_a_id);
+    assert(sc == RTEMS_SUCCESSFUL);
+    sc = rtems_scheduler_ident(SCHED_B, &scheduler_b_id);
+    assert(sc == RTEMS_SUCCESSFUL);
+    /* Create a MrsP semaphore object \*/
+    sc = rtems_semaphore_create(
+    rtems_build_name('M', 'R', 'S', 'P'),
+    1,
+    RTEMS_MULTIPROCESSOR_RESOURCE_SHARING
+    | RTEMS_BINARY_SEMAPHORE,
+    1,
+    &semaphore_id
+    );
+    assert(sc == RTEMS_SUCCESSFUL);
+    /*
+    * The ceiling priority values per scheduler are equal to the value specified
+    * for object creation.
+    \*/
+    prio = RTEMS_CURRENT_PRIORITY;
+    sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio);
+    assert(sc == RTEMS_SUCCESSFUL);
+    assert(prio == 1);
+    /* Check the old value and set a new ceiling priority for scheduler B \*/
+    prio = 2;
+    sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio);
+    assert(sc == RTEMS_SUCCESSFUL);
+    assert(prio == 1);
+    /* Check the ceiling priority values \*/
+    prio = RTEMS_CURRENT_PRIORITY;
+    sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio);
+    assert(sc == RTEMS_SUCCESSFUL);
+    assert(prio == 1);
+    prio = RTEMS_CURRENT_PRIORITY;
+    sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio);
+    assert(sc == RTEMS_SUCCESSFUL);
+    assert(prio == 2);
+    sc = rtems_semaphore_delete(semaphore_id);
+    assert(sc == RTEMS_SUCCESSFUL);
+    exit(0);
+    }
+    #define CONFIGURE_SMP_APPLICATION
+    #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+    #define CONFIGURE_MAXIMUM_TASKS 1
+    #define CONFIGURE_MAXIMUM_SEMAPHORES 1
+    #define CONFIGURE_MAXIMUM_MRSP_SEMAPHORES 1
+    #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 2
+    #define CONFIGURE_SCHEDULER_SIMPLE_SMP
+    #include <rtems/scheduler.h>
+    RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(a);
+    RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(b);
+    #define CONFIGURE_SCHEDULER_CONTROLS \\
+    RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(a, SCHED_A), \\
+    RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(b, SCHED_B)
+    #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \\
+    RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY)
+    #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+    #define CONFIGURE_INIT
+    #include <rtems/confdefs.h>
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Message Manager
+###############
+
+.. index:: messages
+.. index:: message queues
+
+Introduction
+============
+
+The message manager provides communication and
+synchronization capabilities using RTEMS message queues.  The
+directives provided by the message manager are:
+
+- ``rtems.message_queue_create`` - Create a queue
+
+- ``rtems.message_queue_ident`` - Get ID of a queue
+
+- ``rtems.message_queue_delete`` - Delete a queue
+
+- ``rtems.message_queue_send`` - Put message at rear of a queue
+
+- ``rtems.message_queue_urgent`` - Put message at front of a queue
+
+- ``rtems.message_queue_broadcast`` - Broadcast N messages to a queue
+
+- ``rtems.message_queue_receive`` - Receive message from a queue
+
+- ``rtems.message_queue_get_number_pending`` - Get number of messages pending on a queue
+
+- ``rtems.message_queue_flush`` - Flush all messages on a queue
+
+Background
+==========
+
+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.
+
+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 ``rtems.message_queue_send``
+directive.  However, the ``rtems.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.  The message content must be copied in general
+to/from an internal buffer of the message queue or directly to a peer in
+certain cases.  This copy operation is performed with interrupts disabled.  So
+it is advisable to keep the messages as short as possible.
+
+Building a Message Queue Attribute Set
+--------------------------------------
+.. index:: message queue attributes
+
+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:
+
+- ``RTEMS.FIFO`` - tasks wait by FIFO (default)
+
+- ``RTEMS.PRIORITY`` - tasks wait by priority
+
+- ``RTEMS.LOCAL`` - local message queue (default)
+
+- ``RTEMS.GLOBAL`` - global message queue
+
+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 ``RTEMS.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``rtems.message_queue_create`` directive could be either``RTEMS.PRIORITY`` or``RTEMS.LOCAL or RTEMS.PRIORITY``.
+The attribute_set parameter can be set to ``RTEMS.PRIORITY``
+because ``RTEMS.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``RTEMS.GLOBAL or RTEMS.PRIORITY``.
+
+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``rtems.message_queue_receive`` directive are
+listed in the following table:
+
+- ``RTEMS.WAIT`` - task will wait for a message (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+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 ``RTEMS.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 ``rtems.message_queue_receive`` directive should
+be ``RTEMS.NO_WAIT``.
+
+Operations
+==========
+
+Creating a Message Queue
+------------------------
+
+The ``rtems.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.
+
+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 ``rtems.message_queue_create`` directive, the
+queue ID is stored in a user provided location.  Second, the queue
+ID may be obtained later using the ``rtems.message_queue_ident``
+directive.  The queue ID is used by other message manager
+directives to access this message queue.
+
+Receiving a Message
+-------------------
+
+The ``rtems.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:
+
+- By default, the calling task will wait forever for the
+  message to arrive.
+
+- Specifying the ``RTEMS.NO_WAIT`` option forces an immediate return
+  with an error status code.
+
+- Specifying a timeout limits the period the task will
+  wait before returning with an error status.
+
+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.
+
+Sending a Message
+-----------------
+
+Messages can be sent to a queue with the``rtems.message_queue_send`` and``rtems.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,``rtems.message_queue_send`` places the
+message at the rear of the message queue, while``rtems.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.
+
+Broadcasting a Message
+----------------------
+
+The ``rtems.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.
+
+Deleting a Message Queue
+------------------------
+
+The ``rtems.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.
+
+Directives
+==========
+
+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.
+
+MESSAGE_QUEUE_CREATE - Create a queue
+-------------------------------------
+.. index:: create a message queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Create (
+    Name             : in     RTEMS.Name;
+    Count            : in     RTEMS.Unsigned32;
+    Max_Message_Size : in     RTEMS.Unsigned32;
+    Attribute_Set    : in     RTEMS.Attribute;
+    ID               :    out RTEMS.ID;
+    Result           :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - queue created successfully
+``RTEMS.INVALID_NAME`` - invalid queue name
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NUMBER`` - invalid message count
+``RTEMS.INVALID_SIZE`` - invalid message size
+``RTEMS.TOO_MANY`` - too many queues created
+``RTEMS.UNSATISFIED`` - unable to allocate message buffers
+``RTEMS.MP_NOT_CONFIGURED`` - multiprocessing not configured
+``RTEMS.TOO_MANY`` - too many global objects
+
+**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 ``RTEMS.PRIORITY`` in attribute_set causes tasks
+waiting for a message to be serviced according to task priority.
+When ``RTEMS.FIFO`` is specified, waiting tasks are serviced
+in First In-First Out order.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+The following message queue attribute constants are
+defined by RTEMS:
+
+- ``RTEMS.FIFO`` - tasks wait by FIFO (default)
+
+- ``RTEMS.PRIORITY`` - tasks wait by priority
+
+- ``RTEMS.LOCAL`` - local message queue (default)
+
+- ``RTEMS.GLOBAL`` - global message queue
+
+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.
+
+MESSAGE_QUEUE_IDENT - Get ID of a queue
+---------------------------------------
+.. index:: get ID of a message queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Ident (
+    Name   : in     RTEMS.Name;
+    Node   : in     RTEMS.Unsigned32;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - queue identified successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - queue name not found
+``RTEMS.INVALID_NODE`` - invalid node id
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+If node is ``RTEMS.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.
+
+MESSAGE_QUEUE_DELETE - Delete a queue
+-------------------------------------
+.. index:: delete a message queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - queue deleted successfully
+``RTEMS.INVALID_ID`` - invalid queue id
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote queue
+
+**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.
+
+**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.
+
+MESSAGE_QUEUE_SEND - Put message at rear of a queue
+---------------------------------------------------
+.. index:: send message to a queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Send (
+    ID     : in     RTEMS.ID;
+    Buffer : in     RTEMS.Address;
+    Size   : in     RTEMS.Unsigned32;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - message sent successfully
+``RTEMS.INVALID_ID`` - invalid queue id
+``RTEMS.INVALID_SIZE`` - invalid message size
+``RTEMS.INVALID_ADDRESS`` - ``buffer`` is NULL
+``RTEMS.UNSATISFIED`` - out of message buffers
+``RTEMS.TOO_MANY`` - queueâs limit has been reached
+
+**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.
+
+**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.
+
+MESSAGE_QUEUE_URGENT - Put message at front of a queue
+------------------------------------------------------
+.. index:: put message at front of queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Urgent (
+    ID     : in     RTEMS.ID;
+    Buffer : in     RTEMS.Address;
+    Size   : in     RTEMS.Unsigned32;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - message sent successfully
+``RTEMS.INVALID_ID`` - invalid queue id
+``RTEMS.INVALID_SIZE`` - invalid message size
+``RTEMS.INVALID_ADDRESS`` - ``buffer`` is NULL
+``RTEMS.UNSATISFIED`` - out of message buffers
+``RTEMS.TOO_MANY`` - queueâs limit has been reached
+
+**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.
+
+**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.
+
+MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
+---------------------------------------------------------
+.. index:: broadcast message to a queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Broadcast (
+    ID     : in     RTEMS.ID;
+    Buffer : in     RTEMS.Address;
+    Size   : in     RTEMS.Unsigned32;
+    Count  :    out RTEMS.Unsigned32;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - message broadcasted successfully
+``RTEMS.INVALID_ID`` - invalid queue id
+``RTEMS.INVALID_ADDRESS`` - ``buffer`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``count`` is NULL
+``RTEMS.INVALID_SIZE`` - invalid message size
+
+**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.
+
+**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 ``rtems.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.
+
+MESSAGE_QUEUE_RECEIVE - Receive message from a queue
+----------------------------------------------------
+.. index:: receive message from a queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Receive (
+    ID         : in     RTEMS.ID;
+    Buffer     : in     RTEMS.Address;
+    Option_Set : in     RTEMS.Option;
+    Timeout    : in     RTEMS.Interval;
+    Size       :    out RTEMS.Unsigned32;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - message received successfully
+``RTEMS.INVALID_ID`` - invalid queue id
+``RTEMS.INVALID_ADDRESS`` - ``buffer`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``size`` is NULL
+``RTEMS.UNSATISFIED`` - queue is empty
+``RTEMS.TIMEOUT`` - timed out waiting for message
+``RTEMS.OBJECT_WAS_DELETED`` - queue deleted while waiting
+
+**DESCRIPTION:**
+
+This directive receives a message from the message
+queue specified in id.  The ``RTEMS.WAIT`` and ``RTEMS.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.  The buffer has to be big enough to
+receive a message of the maximum length with respect to this message queue.
+
+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 ``RTEMS.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``RTEMS.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``RTEMS.NO_TIMEOUT``, then the calling task will wait forever.
+
+**NOTES:**
+
+The following message receive option constants are
+defined by RTEMS:
+
+- ``RTEMS.WAIT`` - task will wait for a message (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+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 ``RTEMS.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.
+
+A clock tick is required to support the timeout functionality of
+this directive.
+
+MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue
+----------------------------------------------------------------------------
+.. index:: get number of pending messages
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Get_Number_Pending (
+    ID     : in     RTEMS.ID;
+    Count  :    out RTEMS.Unsigned32;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - number of messages pending returned successfully
+``RTEMS.INVALID_ADDRESS`` - ``count`` is NULL
+``RTEMS.INVALID_ID`` - invalid queue id
+
+**DESCRIPTION:**
+
+This directive returns the number of messages pending on this
+message queue in count.  If no messages are present
+on the queue, count is set to zero.
+
+**NOTES:**
+
+Getting the number of pending messages on a global message queue which
+does not reside on the local node will generate a request to the
+remote node to actually obtain the pending message count for
+the specified message queue.
+
+MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
+---------------------------------------------------
+.. index:: flush messages on a queue
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Message_Queue_Flush (
+    ID     : in     RTEMS.ID;
+    Count  :    out RTEMS.Unsigned32;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - message queue flushed successfully
+``RTEMS.INVALID_ADDRESS`` - ``count`` is NULL
+``RTEMS.INVALID_ID`` - invalid queue id
+
+**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.
+
+**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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Event Manager
+#############
+
+.. index:: events
+
+Introduction
+============
+
+The event manager provides a high performance method
+of intertask communication and synchronization.  The directives
+provided by the event manager are:
+
+- ``rtems.event_send`` - Send event set to a task
+
+- ``rtems.event_receive`` - Receive event condition
+
+Background
+==========
+
+Event Sets
+----------
+.. index:: event flag, definition
+.. index:: event set, definition
+.. index:: rtems_event_set
+
+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 data type ``rtems.event_set`` is used to manage
+event sets.
+
+The application developer should remember the following
+key characteristics of event operations when utilizing the event
+manager:
+
+- Events provide a simple synchronization facility.
+
+- Events are aimed at tasks.
+
+- Tasks can wait on more than one event simultaneously.
+
+- Events are independent of one another.
+
+- Events do not hold or transport data.
+
+- Events are not queued.  In other words, if an event is
+  sent more than once to a task before being received, the second and
+  subsequent send operations to that same task have no effect.
+
+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 event set 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``RTEMS.EVENT_ANY`` algorithm states that an event condition
+is satisfied when at least a single requested event is posted.  The``RTEMS.EVENT_ALL`` algorithm states that an event condition
+is satisfied when every requested event is posted.
+
+Building an Event Set or Condition
+----------------------------------
+.. index:: event condition, building
+.. index:: event set, building
+
+An event set or condition is built by a bitwise OR of
+the desired events.  The set of valid events is ``RTEMS.EVENT_0`` through``RTEMS.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``RTEMS.EVENT_6``, ``RTEMS.EVENT_15``, and ``RTEMS.EVENT_31``,
+the event parameter to the ``rtems.event_send``
+directive should be ``RTEMS.EVENT_6 or
+RTEMS.EVENT_15 or RTEMS.EVENT_31``.
+
+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``rtems.event_receive`` directive are listed
+in the following table:
+
+- ``RTEMS.WAIT`` - task will wait for event (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+- ``RTEMS.EVENT_ALL`` - return after all events (default)
+
+- ``RTEMS.EVENT_ANY`` - return after any events
+
+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 ``RTEMS.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``rtems.event_receive`` directive should be either``RTEMS.EVENT_ALL or RTEMS.NO_WAIT``
+or ``RTEMS.NO_WAIT``.  The option parameter can be set to``RTEMS.NO_WAIT`` because ``RTEMS.EVENT_ALL`` is the
+default condition for ``rtems.event_receive``.
+
+Operations
+==========
+
+Sending an Event Set
+--------------------
+
+The ``rtems.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:
+
+- Target Task is Blocked Waiting for Events
+  - - If the waiting taskâs input event condition is
+    satisfied, then the task is made ready for execution.
+  - - 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.
+
+- Target Task is Not Waiting for Events
+  - - The event set is posted and left pending.
+
+Receiving an Event Set
+----------------------
+
+The ``rtems.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:
+
+- By default, the calling task will wait forever for the
+  event condition to be satisfied.
+
+- Specifying the ``RTEMS.NO_WAIT`` option forces an immediate return
+  with an error status code.
+
+- Specifying a timeout limits the period the task will
+  wait before returning with an error status code.
+
+Determining the Pending Event Set
+---------------------------------
+
+A task can determine the pending event set by calling
+the ``rtems.event_receive`` directive with a value of``RTEMS.PENDING_EVENTS`` for the input event condition.
+The pending events are returned to the calling task but the event
+set is left unaltered.
+
+Receiving all Pending Events
+----------------------------
+
+A task can receive all of the currently pending
+events by calling the ``rtems.event_receive``
+directive with a value of ``RTEMS.ALL_EVENTS``
+for the input event condition and``RTEMS.NO_WAIT or RTEMS.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 ``RTEMS.UNSATISFIED`` status code will be returned.
+
+Directives
+==========
+
+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.
+
+EVENT_SEND - Send event set to a task
+-------------------------------------
+.. index:: send event set to a task
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Event_Send (
+    ID       : in     RTEMS.ID;
+    Event_In : in     RTEMS.Event_Set;
+    Result   :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - event set sent successfully
+``RTEMS.INVALID_ID`` - invalid task id
+
+**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.
+
+**NOTES:**
+
+Specifying ``RTEMS.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 ``rtems.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.
+
+EVENT_RECEIVE - Receive event condition
+---------------------------------------
+.. index:: receive event condition
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Event_Receive (
+    Event_In   : in     RTEMS.Event_Set;
+    Option_Set : in     RTEMS.Option;
+    Ticks      : in     RTEMS.Interval;
+    Event_Out  :    out RTEMS.Event_Set;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - event received successfully
+``RTEMS.UNSATISFIED`` - input event not satisfied (``RTEMS.NO_WAIT``)
+``RTEMS.INVALID_ADDRESS`` - ``event_out`` is NULL
+``RTEMS.TIMEOUT`` - timed out waiting for event
+
+**DESCRIPTION:**
+
+This directive attempts to receive the event
+condition specified in event_in.  If event_in is set to``RTEMS.PENDING_EVENTS``, then the current pending events are returned in
+event_out and left pending.  The ``RTEMS.WAIT`` and ``RTEMS.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.``RTEMS.EVENT_ANY`` and ``RTEMS.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 ``RTEMS.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 ``RTEMS.NO_TIMEOUT``, then
+the calling task will wait forever.
+
+**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:
+
+- ``RTEMS.WAIT`` task will wait for event (default)
+
+- ``RTEMS.NO_WAIT`` task should not wait
+
+- ``RTEMS.EVENT_ALL`` return after all events (default)
+
+- ``RTEMS.EVENT_ANY`` return after any events
+
+A clock tick is required to support the functionality of this directive.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Signal Manager
+##############
+
+.. index:: signals
+
+Introduction
+============
+
+The signal manager provides the capabilities required
+for asynchronous communication.  The directives provided by the
+signal manager are:
+
+- ``rtems.signal_catch`` - Establish an ASR
+
+- ``rtems.signal_send`` - Send signal set to a task
+
+Background
+==========
+
+Signal Manager Definitions
+--------------------------
+.. index:: asynchronous signal routine
+.. index:: ASR
+
+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... index:: rtems_signal_set
+
+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.  The data type ``rtems.signal_set``
+is used to manipulate signal sets.
+
+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.
+
+A Comparison of ASRs and ISRs
+-----------------------------
+.. index:: ASR vs. ISR
+.. index:: ISR vs. ASR
+
+The format of an ASR is similar to that of an ISR
+with the following exceptions:
+
+- ISRs are scheduled by the processor hardware.  ASRs are
+  scheduled by RTEMS.
+
+- 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.
+
+- 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.
+
+- 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.
+
+Building a Signal Set
+---------------------
+.. index:: signal set, building
+
+A signal set is built by a bitwise OR of the desired
+signals.  The set of valid signals is ``RTEMS.SIGNAL_0`` through``RTEMS.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``RTEMS.SIGNAL_6``,``RTEMS.SIGNAL_15``, and``RTEMS.SIGNAL_31``.  The signal parameter provided
+to the ``rtems.signal_send`` directive should be``RTEMS.SIGNAL_6 or
+RTEMS.SIGNAL_15 or RTEMS.SIGNAL_31``.
+
+Building an ASR Mode
+--------------------
+.. index:: ASR mode, building
+
+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:
+
+- ``RTEMS.PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and enables preemption
+
+- ``RTEMS.NO_PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and disables preemption
+
+- ``RTEMS.NO_TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and disables timeslicing
+
+- ``RTEMS.TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and enables timeslicing
+
+- ``RTEMS.ASR`` is masked by``RTEMS.ASR_MASK`` and enables ASR processing
+
+- ``RTEMS.NO_ASR`` is masked by``RTEMS.ASR_MASK`` and disables ASR processing
+
+- ``RTEMS.INTERRUPT_LEVEL(0)`` is masked by``RTEMS.INTERRUPT_MASK`` and enables all interrupts
+
+- ``RTEMS.INTERRUPT_LEVEL(n)`` is masked by``RTEMS.INTERRUPT_MASK`` and sets interrupts level n
+
+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 ``rtems.signal_catch``
+to establish an ASR which executes at
+interrupt level three and is non-preemptible.  The mode should
+be set to``RTEMS.INTERRUPT_LEVEL(3) or RTEMS.NO_PREEMPT``
+to indicate the
+desired processor mode and interrupt level.
+
+Operations
+==========
+
+Establishing an ASR
+-------------------
+
+The ``rtems.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 ``rtems.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 ``rtems.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 (``RTEMS.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 ``rtems.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.
+
+Sending a Signal Set
+--------------------
+
+The ``rtems.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``rtems.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.
+
+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
+Ada calling conventions:
+
+.. code:: c
+
+    procedure User_Routine (
+    Signals : in     RTEMS.Signal_Set
+    );
+
+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.
+
+Directives
+==========
+
+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.
+
+SIGNAL_CATCH - Establish an ASR
+-------------------------------
+.. index:: establish an ASR
+.. index:: install an ASR
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Signal_Catch (
+    ASR_Handler : in     RTEMS.ASR_Handler;
+    Mode_Set    : in     RTEMS.Mode;
+    Result      :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - always successful
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+The following task mode constants are defined by RTEMS:
+
+- ``RTEMS.PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and enables preemption
+
+- ``RTEMS.NO_PREEMPT`` is masked by``RTEMS.PREEMPT_MASK`` and disables preemption
+
+- ``RTEMS.NO_TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and disables timeslicing
+
+- ``RTEMS.TIMESLICE`` is masked by``RTEMS.TIMESLICE_MASK`` and enables timeslicing
+
+- ``RTEMS.ASR`` is masked by``RTEMS.ASR_MASK`` and enables ASR processing
+
+- ``RTEMS.NO_ASR`` is masked by``RTEMS.ASR_MASK`` and disables ASR processing
+
+- ``RTEMS.INTERRUPT_LEVEL(0)`` is masked by``RTEMS.INTERRUPT_MASK`` and enables all interrupts
+
+- ``RTEMS.INTERRUPT_LEVEL(n)`` is masked by``RTEMS.INTERRUPT_MASK`` and sets interrupts level n
+
+SIGNAL_SEND - Send signal set to a task
+---------------------------------------
+.. index:: send signal set
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Signal_Send (
+    ID         : in     RTEMS.ID;
+    Signal_Set : in     RTEMS.Signal_Set;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - signal sent successfully
+``RTEMS.INVALID_ID`` - task id invalid
+``RTEMS.INVALID_NUMBER`` - empty signal set
+``RTEMS.NOT_DEFINED`` - ASR invalid
+
+**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.
+
+**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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2010.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Partition Manager
+#################
+
+.. index:: partitions
+
+Introduction
+============
+
+The partition manager provides facilities to
+dynamically allocate memory in fixed-size units.  The directives
+provided by the partition manager are:
+
+- ``rtems.partition_create`` - Create a partition
+
+- ``rtems.partition_ident`` - Get ID of a partition
+
+- ``rtems.partition_delete`` - Delete a partition
+
+- ``rtems.partition_get_buffer`` - Get buffer from a partition
+
+- ``rtems.partition_return_buffer`` - Return buffer to a partition
+
+Background
+==========
+
+Partition Manager Definitions
+-----------------------------
+.. index:: partition, definition
+
+A partition is a physically contiguous memory area
+divided into fixed-size buffers that can be dynamically
+allocated and deallocated... index:: buffers, definition
+
+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 two
+pointers of memory from 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.
+
+Building a Partition Attribute Set
+----------------------------------
+.. index:: partition attribute set, building
+
+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:
+
+- ``RTEMS.LOCAL`` - local partition (default)
+
+- ``RTEMS.GLOBAL`` - global partition
+
+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``RTEMS.DEFAULT_ATTRIBUTES`` should be
+specified on this call.  The attribute_set parameter should be``RTEMS.GLOBAL`` to indicate that the partition
+is to be known globally.
+
+Operations
+==========
+
+Creating a Partition
+--------------------
+
+The ``rtems.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``rtems.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. If successful,the
+unique partition ID is returned to the calling task.
+
+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``rtems.partition_create`` directive, the partition
+ID is stored in a user provided location.  Second, the partition
+ID may be obtained later using the ``rtems.partition_ident``
+directive.  The partition ID is used by other partition manager directives
+to access this partition.
+
+Acquiring a Buffer
+------------------
+
+A buffer can be obtained by calling the``rtems.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.
+
+Releasing a Buffer
+------------------
+
+Buffers are returned to a partitionâs free buffer
+chain with the ``rtems.partition_return_buffer`` directive.  This
+directive returns an error status code if the returned buffer
+was not previously allocated from this partition.
+
+Deleting a Partition
+--------------------
+
+The ``rtems.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.
+
+Directives
+==========
+
+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.
+
+PARTITION_CREATE - Create a partition
+-------------------------------------
+.. index:: create a partition
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Partition_Create (
+    Name             : in     RTEMS.Name;
+    Starting_Address : in     RTEMS.Address;
+    Length           : in     RTEMS.Unsigned32;
+    Buffer_Size      : in     RTEMS.Unsigned32;
+    Attribute_Set    : in     RTEMS.Attribute;
+    ID               :    out RTEMS.ID;
+    Result           :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - partition created successfully
+``RTEMS.INVALID_NAME`` - invalid partition name
+``RTEMS.TOO_MANY`` - too many partitions created
+``RTEMS.INVALID_ADDRESS`` - address not on four byte boundary
+``RTEMS.INVALID_ADDRESS`` - ``starting_address`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_SIZE`` - length or buffer size is 0
+``RTEMS.INVALID_SIZE`` - length is less than the buffer size
+``RTEMS.INVALID_SIZE`` - buffer size not a multiple of 4
+``RTEMS.MP_NOT_CONFIGURED`` - multiprocessing not configured
+``RTEMS.TOO_MANY`` - too many global objects
+
+**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_size`` 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.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+The ``starting_address`` must be properly aligned for the
+target architecture.
+
+The ``buffer_size`` parameter must be a multiple of
+the CPU alignment factor.  Additionally, ``buffer_size``
+must be large enough to hold two pointers on the target
+architecture.  This is required for RTEMS to manage the
+buffers when they are free.
+
+Memory from the partition is not used by RTEMS to
+store the Partition Control Block.
+
+The following partition attribute constants are
+defined by RTEMS:
+
+- ``RTEMS.LOCAL`` - local partition (default)
+
+- ``RTEMS.GLOBAL`` - global partition
+
+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.
+
+PARTITION_IDENT - Get ID of a partition
+---------------------------------------
+.. index:: get ID of a partition
+.. index:: obtain ID of a partition
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Partition_Ident (
+    Name   : in     RTEMS.Name;
+    Node   : in     RTEMS.Unsigned32;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - partition identified successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - partition name not found
+``RTEMS.INVALID_NODE`` - invalid node id
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+If node is ``RTEMS.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.
+
+PARTITION_DELETE - Delete a partition
+-------------------------------------
+.. index:: delete a partition
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Partition_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - partition deleted successfully
+``RTEMS.INVALID_ID`` - invalid partition id
+``RTEMS.RESOURCE_IN_USE`` - buffers still in use
+``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote partition
+
+**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.
+
+**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 ``RTEMS.GLOBAL`` option.
+
+PARTITION_GET_BUFFER - Get buffer from a partition
+--------------------------------------------------
+.. index:: get buffer from partition
+.. index:: obtain buffer from partition
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Partition_Get_Buffer (
+    ID     : in     RTEMS.ID;
+    Buffer :    out RTEMS.Address;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - buffer obtained successfully
+``RTEMS.INVALID_ADDRESS`` - ``buffer`` is NULL
+``RTEMS.INVALID_ID`` - invalid partition id
+``RTEMS.UNSATISFIED`` - all buffers are allocated
+
+**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.
+
+**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.
+
+PARTITION_RETURN_BUFFER - Return buffer to a partition
+------------------------------------------------------
+.. index:: return buffer to partitition
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Partition_Return_Buffer (
+    ID     : in     RTEMS.ID;
+    Buffer : in     RTEMS.Address;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - buffer returned successfully
+``RTEMS.INVALID_ADDRESS`` - ``buffer`` is NULL
+``RTEMS.INVALID_ID`` - invalid partition id
+``RTEMS.INVALID_ADDRESS`` - buffer address not in partition
+
+**DESCRIPTION:**
+
+This directive returns the buffer specified by buffer
+to the partition specified by id.
+
+**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.
+
+Returning a buffer multiple times is an error.  It will corrupt the internal
+state of the partition.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Region Manager
+##############
+
+.. index:: regions
+
+Introduction
+============
+
+The region manager provides facilities to dynamically
+allocate memory in variable sized units.  The directives
+provided by the region manager are:
+
+- ``rtems.region_create`` - Create a region
+
+- ``rtems.region_ident`` - Get ID of a region
+
+- ``rtems.region_delete`` - Delete a region
+
+- ``rtems.region_extend`` - Add memory to a region
+
+- ``rtems.region_get_segment`` - Get segment from a region
+
+- ``rtems.region_return_segment`` - Return segment to a region
+
+- ``rtems.region_get_segment_size`` - Obtain size of a segment
+
+- ``rtems.region_resize_segment`` - Change size of a segment
+
+Background
+==========
+
+Region Manager Definitions
+--------------------------
+.. index:: region, definition
+.. index:: segment, definition
+
+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.
+
+Building an Attribute Set
+-------------------------
+.. index:: region attribute set, building
+
+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:
+
+- ``RTEMS.FIFO`` - tasks wait by FIFO (default)
+
+- ``RTEMS.PRIORITY`` - tasks wait by priority
+
+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``RTEMS.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``rtems.region_create``
+directive should be ``RTEMS.PRIORITY``.
+
+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``rtems.region_get_segment`` directive are
+listed in the following table:
+
+- ``RTEMS.WAIT`` - task will wait for segment (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+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``RTEMS.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``rtems.region_get_segment`` directive should
+be ``RTEMS.NO_WAIT``.
+
+Operations
+==========
+
+Creating a Region
+-----------------
+
+The ``rtems.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.
+
+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``rtems.region_create`` directive,
+the region ID is stored in a user
+provided location.  Second, the region ID may be obtained later
+using the ``rtems.region_ident`` directive.
+The region ID is used by other region manager directives to
+access this region.
+
+Adding Memory to a Region
+-------------------------
+
+The ``rtems.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.
+
+Acquiring a Segment
+-------------------
+
+The ``rtems.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:
+
+- By default, the calling task will wait forever to acquire the segment.
+
+- Specifying the ``RTEMS.NO_WAIT`` option forces
+  an immediate return with an error status code.
+
+- Specifying a timeout limits the interval the task will
+  wait before returning with an error status code.
+
+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.
+
+Releasing a Segment
+-------------------
+
+When a segment is returned to a region by the``rtems.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.
+
+Obtaining the Size of a Segment
+-------------------------------
+
+The ``rtems.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.
+
+Changing the Size of a Segment
+------------------------------
+
+The ``rtems.region_resize_segment`` directive is used
+to change the size in bytes of the specified segment.  The size may be
+increased or decreased.  When increasing the size of a segment, it is
+possible that the request cannot be satisfied.  This directive provides
+functionality similar to the ``realloc()`` function in the Standard
+C Library.
+
+Deleting a Region
+-----------------
+
+A region can be removed from the system and returned
+to RTEMS with the ``rtems.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.
+
+Directives
+==========
+
+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.
+
+REGION_CREATE - Create a region
+-------------------------------
+.. index:: create a region
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Create (
+    Name             : in     RTEMS.Name;
+    Starting_Address : in     RTEMS.Address;
+    Length           : in     RTEMS.Unsigned32;
+    Page_Size        : in     RTEMS.Unsigned32;
+    Attribute_Set    : in     RTEMS.Attribute;
+    ID               :    out RTEMS.ID;
+    Result           :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - region created successfully
+``RTEMS.INVALID_NAME`` - invalid region name
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``starting_address`` is NULL
+``RTEMS.INVALID_ADDRESS`` - address not on four byte boundary
+``RTEMS.TOO_MANY`` - too many regions created
+``RTEMS.INVALID_SIZE`` - invalid page size
+
+**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 ``RTEMS.PRIORITY`` in attribute_set causes tasks
+waiting for a segment to be serviced according to task priority.
+Specifying ``RTEMS.FIFO`` in attribute_set or selecting``RTEMS.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 eight.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+The following region attribute constants are defined
+by RTEMS:
+
+- ``RTEMS.FIFO`` - tasks wait by FIFO (default)
+
+- ``RTEMS.PRIORITY`` - tasks wait by priority
+
+REGION_IDENT - Get ID of a region
+---------------------------------
+.. index:: get ID of a region
+.. index:: obtain ID of a region
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Ident (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - region identified successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - region name not found
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+REGION_DELETE - Delete a region
+-------------------------------
+.. index:: delete a region
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - region deleted successfully
+``RTEMS.INVALID_ID`` - invalid region id
+``RTEMS.RESOURCE_IN_USE`` - segments still in use
+
+**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.
+
+**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.
+
+REGION_EXTEND - Add memory to a region
+--------------------------------------
+.. index:: add memory to a region
+.. index:: region, add memory
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Extend (
+    ID               : in     RTEMS.ID;
+    Starting_Address : in     RTEMS.Address;
+    Length           : in     RTEMS.Unsigned32;
+    Result           :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - region extended successfully
+``RTEMS.INVALID_ADDRESS`` - ``starting_address`` is NULL
+``RTEMS.INVALID_ID`` - invalid region id
+``RTEMS.INVALID_ADDRESS`` - invalid address of area to add
+
+**DESCRIPTION:**
+
+This directive adds the memory which starts at
+starting_address for length bytes to the region specified by id.
+
+**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.
+
+REGION_GET_SEGMENT - Get segment from a region
+----------------------------------------------
+.. index:: get segment from region
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Get_Segment (
+    ID         : in     RTEMS.ID;
+    Size       : in     RTEMS.Unsigned32;
+    Option_Set : in     RTEMS.Option;
+    Timeout    : in     RTEMS.Interval;
+    Segment    :    out RTEMS.Address;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - segment obtained successfully
+``RTEMS.INVALID_ADDRESS`` - ``segment`` is NULL
+``RTEMS.INVALID_ID`` - invalid region id
+``RTEMS.INVALID_SIZE`` - request is for zero bytes or exceeds
+the size of maximum segment which is possible for this region
+``RTEMS.UNSATISFIED`` - segment of requested size not available
+``RTEMS.TIMEOUT`` - timed out waiting for segment
+``RTEMS.OBJECT_WAS_DELETED`` - region deleted while waiting
+
+**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 ``RTEMS.WAIT``
+and ``RTEMS.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``RTEMS.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 ``RTEMS.PRIORITY`` option, then the calling
+task is inserted into the
+wait queue according to its priority.  However, if the region
+was created with the ``RTEMS.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 ``RTEMS.NO_TIMEOUT``, then the
+calling task will wait forever.
+
+**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:
+
+- ``RTEMS.WAIT`` - task will wait for segment (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+A clock tick is required to support the timeout functionality of
+this directive.
+
+REGION_RETURN_SEGMENT - Return segment to a region
+--------------------------------------------------
+.. index:: return segment to region
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Return_Segment (
+    ID      : in     RTEMS.ID;
+    Segment : in     RTEMS.Address;
+    Result  :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - segment returned successfully
+``RTEMS.INVALID_ADDRESS`` - ``segment`` is NULL
+``RTEMS.INVALID_ID`` - invalid region id
+``RTEMS.INVALID_ADDRESS`` - segment address not in region
+
+**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.
+
+**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:
+
+- a waiting task has a higher priority than the calling task
+
+- the size of the segment required by the waiting task
+  is less than or equal to the size of the segment returned.
+
+REGION_GET_SEGMENT_SIZE - Obtain size of a segment
+--------------------------------------------------
+.. index:: get size of segment
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Get_Segment_Size (
+    ID         : in     RTEMS.ID;
+    Segment    : in     RTEMS.Address;
+    Size       :    out RTEMS.Unsigned32;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - segment obtained successfully
+``RTEMS.INVALID_ADDRESS`` - ``segment`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``size`` is NULL
+``RTEMS.INVALID_ID`` - invalid region id
+``RTEMS.INVALID_ADDRESS`` - segment address not in region
+
+**DESCRIPTION:**
+
+This directive obtains the size in bytes of the specified segment.
+
+**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.
+
+REGION_RESIZE_SEGMENT - Change size of a segment
+------------------------------------------------
+.. index:: resize segment
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Region_Resize_Segment (
+    ID         : in     RTEMS.ID;
+    Segment    : in     RTEMS.Address;
+    Size       : in     RTEMS.Unsigned32;
+    Old_Size   :    out RTEMS.Unsigned32;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - segment obtained successfully
+``RTEMS.INVALID_ADDRESS`` - ``segment`` is NULL
+``RTEMS.INVALID_ADDRESS`` - ``old_size`` is NULL
+``RTEMS.INVALID_ID`` - invalid region id
+``RTEMS.INVALID_ADDRESS`` - segment address not in region``RTEMS.UNSATISFIED`` - unable to make segment larger
+
+**DESCRIPTION:**
+
+This directive is used to increase or decrease the size of
+a segment.  When increasing the size of a segment, it
+is possible that there is not memory available contiguous
+to the segment.  In this case, the request is unsatisfied.
+
+**NOTES:**
+
+If an attempt to increase the size of a segment fails, then
+the application may want to allocate a new segment of the desired
+size, copy the contents of the original segment to the new, larger
+segment and then return the original segment.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Dual-Ported Memory Manager
+##########################
+
+.. index:: ports
+.. index:: dual ported memory
+
+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:
+
+- ``rtems.port_create`` - Create a port
+
+- ``rtems.port_ident`` - Get ID of a port
+
+- ``rtems.port_delete`` - Delete a port
+
+- ``rtems.port_external_to_internal`` - Convert external to internal address
+
+- ``rtems.port_internal_to_external`` - Convert internal to external address
+
+Background
+==========
+.. index:: dual ported memory, definition
+.. index:: external addresses, definition
+.. index:: internal addresses, definition
+
+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.
+
+Operations
+==========
+
+Creating a Port
+---------------
+
+The ``rtems.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.
+
+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``rtems.port_create`` directive, the task
+ID is stored in a user provided location.  Second, the port ID
+may be obtained later using the``rtems.port_ident`` directive.  The port
+ID is used by other dual-ported memory manager directives to
+access this port.
+
+Converting an Address
+---------------------
+
+The ``rtems.port_external_to_internal`` directive is used to
+convert an address from external to internal representation for
+the specified port.
+The ``rtems.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.
+
+Deleting a DPMA Port
+--------------------
+
+A port can be removed from the system and returned to
+RTEMS with the ``rtems.port_delete`` directive.  When a port is deleted,
+its control block is returned to the DPCB free list.
+
+Directives
+==========
+
+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.
+
+PORT_CREATE - Create a port
+---------------------------
+.. index:: create a port
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Port_Create (
+    Name           : in     RTEMS.Name;
+    Internal_Start : in     RTEMS.Address;
+    External_Start : in     RTEMS.Address;
+    Length         : in     RTEMS.Unsigned32;
+    ID             :    out RTEMS.ID;
+    Result         :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - port created successfully
+``RTEMS.INVALID_NAME`` - invalid port name
+``RTEMS.INVALID_ADDRESS`` - address not on four byte boundary
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.TOO_MANY`` - too many DP memory areas created
+
+**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.
+
+**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.
+
+PORT_IDENT - Get ID of a port
+-----------------------------
+.. index:: get ID of a port
+.. index:: obtain ID of a port
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Port_Ident (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - port identified successfully
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - port name not found
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+PORT_DELETE - Delete a port
+---------------------------
+.. index:: delete a port
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Port_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - port deleted successfully
+``RTEMS.INVALID_ID`` - invalid port id
+
+**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.
+
+**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.
+
+PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
+----------------------------------------------------------------
+.. index:: convert external to internal address
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Port_External_To_Internal (
+    ID       : in     RTEMS.ID;
+    External : in     RTEMS.Address;
+    Internal :    out RTEMS.Address;
+    Result   :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.INVALID_ADDRESS`` - ``internal`` is NULL
+``RTEMS.SUCCESSFUL`` - successful conversion
+
+**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.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the calling task to be
+preempted.
+
+PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
+----------------------------------------------------------------
+.. index:: convert internal to external address
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Port_Internal_To_External (
+    ID       : in     RTEMS.ID;
+    Internal : in     RTEMS.Address;
+    External :    out RTEMS.Address;
+    Result   :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.INVALID_ADDRESS`` - ``external`` is NULL
+``RTEMS.SUCCESSFUL`` - successful conversion
+
+**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.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the calling task to be
+preempted.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+I/O Manager
+###########
+
+.. index:: device drivers
+.. index:: IO Manager
+
+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:
+
+- ``rtems.io_initialize`` - Initialize a device driver
+
+- ``rtems.io_register_driver`` - Register a device driver
+
+- ``rtems.io_unregister_driver`` - Unregister a device driver
+
+- ``rtems.io_register_name`` - Register a device name
+
+- ``rtems.io_lookup_name`` - Look up a device name
+
+- ``rtems.io_open`` - Open a device
+
+- ``rtems.io_close`` - Close a device
+
+- ``rtems.io_read`` - Read from a device
+
+- ``rtems.io_write`` - Write to a device
+
+- ``rtems.io_control`` - Special device services
+
+Background
+==========
+
+Device Driver Table
+-------------------
+.. index:: 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 that is to be initialised by
+RTEMS during initialization.  Each device driver may contain the
+following entry points:
+
+- Initialization
+
+- Open
+
+- Close
+
+- Read
+
+- Write
+
+- Control
+
+If the device driver does not support a particular
+entry point, then that entry in the Configuration Table should
+be NULL.  RTEMS will return``RTEMS.SUCCESSFUL`` as the executiveâs and
+zero (0) as the device driverâs return code for these device
+driver entry points.
+
+Applications can register and unregister drivers with the RTEMS I/O
+manager avoiding the need to have all drivers statically defined and
+linked into this table.
+
+The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures
+the number of driver slots available to the application.
+
+Major and Minor Device Numbers
+------------------------------
+.. index:: major device number
+.. index:: minor device number
+
+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... index:: rtems_device_major_number
+.. index:: rtems_device_minor_number
+
+The data types ``rtems.device_major_number`` and``rtems.device_minor_number`` are used to
+manipulate device major and minor numbers, respectively.
+
+Device Names
+------------
+.. index:: 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.
+
+Device Driver Environment
+-------------------------
+
+Application developers, as well as device driver
+developers, must be aware of the following regarding the RTEMS
+I/O Manager:
+
+- A device driver routine executes in the context of the
+  invoking task.  Thus if the driver blocks, the invoking task
+  blocks.
+
+- The device driver is free to change the modes of the
+  invoking task, although the driver should restore them to their
+  original values.
+
+- Device drivers may be invoked from ISRs.
+
+- Only local device drivers are accessible through the I/O
+  manager.
+
+- A device driver routine may invoke all other RTEMS
+  directives, including I/O directives, on both local and global
+  objects.
+
+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.
+
+Runtime Driver Registration
+---------------------------
+.. index:: runtime driver registration
+
+Board support package and application developers can select wether a
+device driver is statically entered into the default device table or
+registered at runtime.
+
+Dynamic registration helps applications where:
+
+# The BSP and kernel libraries are common to a range of applications
+  for a specific target platform. An application may be built upon a
+  common library with all drivers. The application selects and registers
+  the drivers. Uniform driver name lookup protects the application.
+
+# The type and range of drivers may vary as the application probes a
+  bus during initialization.
+
+# Support for hot swap bus system such as Compact PCI.
+
+# Support for runtime loadable driver modules.
+
+Device Driver Interface
+-----------------------
+.. index:: 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:
+
+.. code:: c
+
+    function IO_Entry (
+    Major          : in     RTEMS.Device_Major_Number;
+    Minor          : in     RTEMS.Device_Major_Number;
+    Argument_Block : in     RTEMS.Address
+    ) return RTEMS.Status_Code;
+
+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.
+
+Device Driver Initialization
+----------------------------
+
+RTEMS automatically initializes all device drivers
+when multitasking is initiated via the``rtems.initialize_executive``
+directive.  RTEMS initializes the device drivers by invoking
+each device driver initialization entry point with the following
+parameters:
+
+major
+    the major device number for this device driver.
+
+minor
+    zero.
+
+argument_block
+    will point to  the Configuration 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.
+
+Operations
+==========
+
+Register and Lookup Name
+------------------------
+
+The ``rtems.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 ``rtems.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.
+
+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``rtems.io_initialize``,``rtems.io_open``,``rtems.io_close``,``rtems.io_read``,``rtems.io_write``, and``rtems.io_control``
+and the underlying device driver entry points.
+
+Directives
+==========
+
+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.
+
+IO_REGISTER_DRIVER - Register a device driver
+---------------------------------------------
+.. index:: register a device driver
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    No Ada implementation.
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully registered
+``RTEMS.INVALID_ADDRESS`` - invalid registered major pointer
+``RTEMS.INVALID_ADDRESS`` - invalid driver table
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+``RTEMS.TOO_MANY`` - no available major device table slot
+``RTEMS.RESOURCE_IN_USE`` - major device number entry in use
+
+**DESCRIPTION:**
+
+This directive attempts to add a new device driver to the Device Driver
+Table. The user can specify a specific major device number via the
+directiveâs ``major`` parameter, or let the registration routine find
+the next available major device number by specifing a major number of``0``. The selected major device number is returned via the``registered_major`` directive parameter. The directive automatically
+allocation major device numbers from the highest value down.
+
+This directive automatically invokes the IO_INITIALIZE directive if
+the driver address table has an initialization and open entry.
+
+The directive returns RTEMS.TOO_MANY if Device Driver Table is
+full, and RTEMS.RESOURCE_IN_USE if a specific major device
+number is requested and it is already in use.
+
+**NOTES:**
+
+The Device Driver Table size is specified in the Configuration Table
+condiguration. This needs to be set to maximum size the application
+requires.
+
+IO_UNREGISTER_DRIVER - Unregister a device driver
+-------------------------------------------------
+.. index:: unregister a device driver
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    No Ada implementation.
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully registered
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**DESCRIPTION:**
+
+This directive removes a device driver from the Device Driver Table.
+
+**NOTES:**
+
+Currently no specific checks are made and the driver is not closed.
+
+IO_INITIALIZE - Initialize a device driver
+------------------------------------------
+.. index:: initialize a device driver
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Initialize (
+    Major        : in     RTEMS.Device_Major_Number;
+    Minor        : in     RTEMS.Device_Minor_Number;
+    Argument     : in     RTEMS.Address;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**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.
+
+**NOTES:**
+
+This directive may or may not cause the calling task
+to be preempted.  This is dependent on the device driver being
+initialized.
+
+IO_REGISTER_NAME - Register a device
+------------------------------------
+.. index:: register device
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Register_Name (
+    Name   : in     String;
+    Major  : in     RTEMS.Device_Major_Number;
+    Minor  : in     RTEMS.Device_Minor_Number;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.TOO_MANY`` - too many devices registered
+
+**DESCRIPTION:**
+
+This directive associates name with the specified
+major/minor number pair.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+IO_LOOKUP_NAME - Lookup a device
+--------------------------------
+.. index:: lookup device major and minor number
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Lookup_Name (
+    Name         : in     String;
+    Device_Info  :    out RTEMS.Driver_Name_t_Pointer;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.UNSATISFIED`` - name not registered
+
+**DESCRIPTION:**
+
+This directive returns the major/minor number pair
+associated with the given device name in ``device_info``.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+IO_OPEN - Open a device
+-----------------------
+.. index:: open a devive
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Open (
+    Major        : in     RTEMS.Device_Major_Number;
+    Minor        : in     RTEMS.Device_Minor_Number;
+    Argument     : in     RTEMS.Address;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**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.
+
+**NOTES:**
+
+This directive may or may not cause the calling task
+to be preempted.  This is dependent on the device driver being
+invoked.
+
+IO_CLOSE - Close a device
+-------------------------
+.. index:: close a device
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Close (
+    Major        : in     RTEMS.Device_Major_Number;
+    Minor        : in     RTEMS.Device_Minor_Number;
+    Argument     : in     RTEMS.Address;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**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.
+
+**NOTES:**
+
+This directive may or may not cause the calling task
+to be preempted.  This is dependent on the device driver being
+invoked.
+
+IO_READ - Read from a device
+----------------------------
+.. index:: read from a device
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Read (
+    Major        : in     RTEMS.Device_Major_Number;
+    Minor        : in     RTEMS.Device_Minor_Number;
+    Argument     : in     RTEMS.Address;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**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.
+
+**NOTES:**
+
+This directive may or may not cause the calling task
+to be preempted.  This is dependent on the device driver being
+invoked.
+
+IO_WRITE - Write to a device
+----------------------------
+.. index:: write to a device
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Write (
+    Major        : in     RTEMS.Device_Major_Number;
+    Minor        : in     RTEMS.Device_Minor_Number;
+    Argument     : in     RTEMS.Address;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**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.
+
+**NOTES:**
+
+This directive may or may not cause the calling task
+to be preempted.  This is dependent on the device driver being
+invoked.
+
+IO_CONTROL - Special device services
+------------------------------------
+.. index:: special device services
+.. index:: IO Control
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure IO_Control (
+    Major        : in     RTEMS.Device_Major_Number;
+    Minor        : in     RTEMS.Device_Minor_Number;
+    Argument     : in     RTEMS.Address;
+    Result       :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successfully initialized
+``RTEMS.INVALID_NUMBER`` - invalid major device number
+
+**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.
+
+**NOTES:**
+
+This directive may or may not cause the calling task
+to be preempted.  This is dependent on the device driver being
+invoked.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Fatal Error Manager
+###################
+
+.. index:: fatal errors
+
+Introduction
+============
+
+The fatal error manager processes all fatal or irrecoverable errors and other
+sources of system termination (for example after exit()).  The directives
+provided by the fatal error manager are:
+
+- ``rtems.fatal_error_occurred`` - Invoke the fatal error handler
+
+- ``rtems.fatal`` - Invoke the fatal error handler with error source
+
+Background
+==========
+.. index:: fatal error detection
+.. index:: fatal error processing
+.. index:: fatal error user extension
+
+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:
+
+- the executive (RTEMS)
+
+- user system code
+
+- user application code
+
+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 static 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 Applications Supplement document for
+a specific target processor.
+
+Operations
+==========
+
+.. _Fatal-Error-Manager-Announcing-a-Fatal-Error:
+
+Announcing a Fatal Error
+------------------------
+.. index:: _Internal_errors_What_happened
+
+The ``rtems.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``rtems.fatal_error_occurred``
+directive stores useful information in the
+variable ``_Internal_errors_What_happened``.  This record
+contains three pieces of information:
+
+- the source of the error (API or executive core),
+
+- whether the error was generated internally by the
+  executive, and a
+
+- a numeric code to indicate the error type.
+
+The error type indicator is dependent on the source
+of the error and whether or not the error was internally
+generated by the executive.  If the error was generated
+from an API, then the error code will be of that APIâs
+error or status codes.  The status codes for the RTEMS
+API are in cpukit/rtems/include/rtems/rtems/status.h.  Those
+for the POSIX API can be found in <errno.h>.
+
+The ``rtems.fatal_error_occurred`` 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``rtems.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.
+
+Directives
+==========
+
+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.
+
+FATAL_ERROR_OCCURRED - Invoke the fatal error handler
+-----------------------------------------------------
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Fatal_Error_Occurred (
+    The_Error : in     RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**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.
+
+**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.
+
+FATAL - Invoke the fatal error handler with error source
+--------------------------------------------------------
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive invokes the internal error handler with is internal set to
+false.  See also ``rtems.fatal_error_occurred``.
+
+EXCEPTION_FRAME_PRINT - Prints the exception frame
+--------------------------------------------------
+.. index:: exception frame
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES**
+
+NONE
+
+**DESCRIPTION:**
+
+Prints the exception frame via printk().
+
+FATAL_SOURCE_TEXT - Returns a text for a fatal source
+-----------------------------------------------------
+.. index:: fatal error
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES**
+
+The fatal source text or "?" in case the passed fatal source is invalid.
+
+**DESCRIPTION:**
+
+Returns a text for a fatal source.  The text for fatal source is the enumerator
+constant.
+
+INTERNAL_ERROR_TEXT - Returns a text for an internal error code
+---------------------------------------------------------------
+.. index:: fatal error
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES**
+
+The error code text or "?" in case the passed error code is invalid.
+
+**DESCRIPTION:**
+
+Returns a text for an internal error code.  The text for each internal error
+code is the enumerator constant.
+
+.. COMMENT: COPYRIGHT (c) 1988-2011.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Scheduling Concepts
+###################
+
+.. index:: scheduling
+.. index:: task scheduling
+
+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.
+
+Scheduling Algorithms
+=====================
+
+.. index:: scheduling algorithms
+
+RTEMS provides a plugin framework which allows it to support
+multiple scheduling algorithms. RTEMS now includes multiple
+scheduling algorithms in the SuperCore and the user can select which
+of these they wish to use in their application.  In addition,
+the user can implement their own scheduling algorithm and
+configure RTEMS to use it.
+
+Supporting multiple scheduling algorithms gives the end user the
+option to select the algorithm which is most appropriate to their use
+case. Most real-time operating systems schedule tasks using a priority
+based algorithm, possibly with preemption control.  The classic
+RTEMS scheduling algorithm which was the only algorithm available
+in RTEMS 4.10 and earlier, is a priority based scheduling algorithm.
+This scheduling algoritm is suitable for single core (e.g. non-SMP)
+systems and is now known as the *Deterministic Priority Scheduler*.
+Unless the user configures another scheduling algorithm, RTEMS will use
+this on single core systems.
+
+Priority Scheduling
+-------------------
+.. index:: priority scheduling
+
+When using priority based scheduling, RTEMS 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.
+
+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:
+
+- ```` *Priority based scheduling algorithms will always select the
+  highest priority task that is ready to run when allocating the processor
+  to a task.*
+
+Priority scheduling is the most commonly used scheduling algorithm.
+It should be used by applications in which multiple tasks contend for
+CPU time or other resources and there is a need to ensure certain tasks
+are given priority over other tasks.
+
+There are a few common methods of accomplishing the mechanics of this
+algorithm.  These ways involve a list or chain of tasks in the ready state.
+
+- The least efficient 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.
+
+- A more efficient 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.
+
+- Another mechanism is to maintain a list of FIFOs per priority.
+  When a task is readied, it is placed on the rear of the FIFO for its
+  priority.  This method is often used with a bitmap to assist in locating
+  which FIFOs have ready tasks on them.
+
+RTEMS currently includes multiple priority based scheduling algorithms
+as well as other algorithms which incorporate deadline.  Each algorithm
+is discussed in the following sections.
+
+Deterministic Priority Scheduler
+--------------------------------
+
+This is the scheduler implementation which has always been in RTEMS.
+After the 4.10 release series, it was factored into pluggable scheduler
+selection.  It schedules tasks using a priority based algorithm which
+takes into account preemption.  It is implemented using an array of FIFOs
+with a FIFO per priority.  It maintains a bitmap which is used to track
+which priorities have ready tasks.
+
+This algorithm is deterministic (e.g. predictable and fixed) in execution
+time.  This comes at the cost of using slightly over three (3) kilobytes
+of RAM on a system configured to support 256 priority levels.
+
+This scheduler is only aware of a single core.
+
+Simple Priority Scheduler
+-------------------------
+
+This scheduler implementation has the same behaviour as the Deterministic
+Priority Scheduler but uses only one linked list to manage all ready
+tasks.  When a task is readied, a linear search of that linked list is
+performed to determine where to insert the newly readied task.
+
+This algorithm uses much less RAM than the Deterministic Priority
+Scheduler but is *O(n)* where *n* is the number of ready tasks.
+In a small system with a small number of tasks, this will not be a
+performance issue.  Reducing RAM consumption is often critical in small
+systems which are incapable of supporting a large number of tasks.
+
+This scheduler is only aware of a single core.
+
+Simple SMP Priority Scheduler
+-----------------------------
+
+This scheduler is based upon the Simple Priority Scheduler and is designed
+to have the same behaviour on a single core system.  But this scheduler
+is capable of scheduling threads across multiple cores in an SMP system.
+When given a choice of replacing one of two threads at equal priority
+on different cores, this algorithm favors replacing threads which are
+preemptible and have executed the longest.
+
+This algorithm is non-deterministic. When scheduling, it must consider
+which tasks are to be executed on each core while avoiding superfluous
+task migrations.
+
+Earliest Deadline First Scheduler
+---------------------------------
+.. index:: earliest deadline first scheduling
+
+This is an alternative scheduler in RTEMS for single core applications.
+The primary EDF advantage is high total CPU utilization (theoretically
+up to 100%). It assumes that tasks have priorities equal to deadlines.
+
+This EDF is initially preemptive, however, individual tasks may be declared
+not-preemptive. Deadlines are declared using only Rate Monotonic manager which
+goal is to handle periodic behavior. Period is always equal to deadline. All
+ready tasks reside in a single ready queue implemented using a red-black tree.
+
+This implementation of EDF schedules two different types of task
+priority types while each task may switch between the two types within
+its execution. If a task does have a deadline declared using the Rate
+Monotonic manager, the task is deadline-driven and its priority is equal
+to deadline.  On the contrary if a task does not have any deadline or
+the deadline is cancelled using the Rate Monotonic manager, the task is
+considered a background task with priority equal to that assigned
+upon initialization in the same manner as for priority scheduler. Each
+background task is of a lower importance than each deadline-driven one
+and is scheduled when no deadline-driven task and no higher priority
+background task is ready to run.
+
+Every deadline-driven scheduling algorithm requires means for tasks
+to claim a deadline.  The Rate Monotonic Manager is responsible for
+handling periodic execution. In RTEMS periods are equal to deadlines,
+thus if a task announces a period, it has to be finished until the
+end of this period. The call of ``rtems_rate_monotonic_period``
+passes the scheduler the length of oncoming deadline. Moreover, the``rtems_rate_monotonic_cancel`` and ``rtems_rate_monotonic_delete``
+calls clear the deadlines assigned to the task.
+
+Constant Bandwidth Server Scheduling (CBS)
+------------------------------------------
+.. index:: constant bandwidth server scheduling
+
+This is an alternative scheduler in RTEMS for single core applications.
+The CBS is a budget aware extension of EDF scheduler. The main goal of this
+scheduler is to ensure temporal isolation of tasks meaning that a taskâs
+execution in terms of meeting deadlines must not be influenced by other
+tasks as if they were run on multiple independent processors.
+
+Each task can be assigned a server (current implementation supports only
+one task per server). The server is characterized by period (deadline)
+and computation time (budget). The ratio budget/period yields bandwidth,
+which is the fraction of CPU to be reserved by the scheduler for each
+subsequent period.
+
+The CBS is equipped with a set of rules applied to tasks attached to servers
+ensuring that deadline miss because of another task cannot occur.
+In case a task breaks one of the rules, its priority is pulled to background
+until the end of its period and then restored again. The rules are:
+
+- Task cannot exceed its registered budget,
+
+- Task cannot be
+  unblocked when a ratio between remaining budget and remaining deadline
+  is higher than declared bandwidth.
+
+The CBS provides an extensive API. Unlike EDF, the``rtems_rate_monotonic_period`` does not declare a deadline because
+it is carried out using CBS API. This call only announces next period.
+
+Scheduling Modification Mechanisms
+==================================
+
+.. index:: scheduling mechanisms
+
+RTEMS provides four mechanisms which allow the user to alter the task
+scheduling decisions:
+
+- user-selectable task priority level
+
+- task preemption control
+
+- task timeslicing control
+
+- manual round-robin selection
+
+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.
+
+Task Priority and Scheduling
+----------------------------
+.. index:: task priority
+
+The most significant task scheduling modification mechanism 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 supports
+up to 255 priority levels.  Level 255 is the lowest priority and level
+1 is the highest.
+
+Preemption
+----------.. index:: preemption
+
+Another way the user can alter the basic scheduling algorithm is by
+manipulating the preemption mode flag (``RTEMS.PREEMPT_MASK``)
+of individual tasks.  If preemption is disabled for a task
+(``RTEMS.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.
+
+Timeslicing
+-----------.. index:: timeslicing
+.. index:: round robin scheduling
+
+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 (``RTEMS.TIMESLICE_MASK``).  If timeslicing is
+enabled for a task (``RTEMS.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.
+
+Manual Round-Robin
+------------------.. index:: 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``rtems.task_wake_after`` directive with a time interval
+of ``RTEMS.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.
+
+Dispatching Tasks
+=================.. index:: dispatching
+
+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``RTEMS.FLOATING_POINT`` attribute require additional
+operations during a context switch.  These additional operations
+are necessary to save and restore the floating point context of``RTEMS.FLOATING_POINT`` tasks.  To avoid unnecessary save
+and restore operations, the state of the numeric coprocessor is only
+saved when a ``RTEMS.FLOATING_POINT`` task is dispatched
+and that task was not the last task to utilize the coprocessor.
+
+Task State Transitions
+======================.. index:: 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.
+
+A task occupies the non-existent state before
+a ``rtems.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 ``rtems.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 ``rtems.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 ``rtems.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.
+
+.. code:: c
+
+    +-------------------------------------------------------------+
+    |                         Non-existent                        |
+    |  +-------------------------------------------------------+  |
+    |  |                                                       |  |
+    |  |                                                       |  |
+    |  |      Creating        +---------+     Deleting         |  |
+    |  | -------------------> | Dormant | -------------------> |  |
+    |  |                      +---------+                      |  |
+    |  |                           |                           |  |
+    |  |                  Starting |                           |  |
+    |  |                           |                           |  |
+    |  |                           V          Deleting         |  |
+    |  |             +-------> +-------+ ------------------->  |  |
+    |  |  Yielding  /   +----- | Ready | ------+               |  |
+    |  |           /   /       +-------+ <--+   \\              |  |
+    |  |          /   /                      \\   \\ Blocking    |  |
+    |  |         /   / Dispatching   Readying \\   \\            |  |
+    |  |        /   V                          \\   V           |  |
+    |  |      +-----------+    Blocking     +---------+        |  |
+    |  |      | Executing | --------------> | Blocked |        |  |
+    |  |      +-----------+                 +---------+        |  |
+    |  |                                                       |  |
+    |  |                                                       |  |
+    |  +-------------------------------------------------------+  |
+    |                         Non-existent                        |
+    +-------------------------------------------------------------+
+
+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 ``rtems.task_suspend`` directive.
+A task enters the blocked state due to any of the following conditions:
+
+- A task issues a ``rtems.task_suspend`` directive
+  which blocks either itself or another task in the system.
+
+- The running task issues a ``rtems.barrier_wait``
+  directive.
+
+- The running task issues a ``rtems.message_queue_receive``
+  directive with the wait option and the message queue is empty.
+
+- The running task issues an ``rtems.event_receive``
+  directive with the wait option and the currently pending events do not
+  satisfy the request.
+
+- The running task issues a ``rtems.semaphore_obtain``
+  directive with the wait option and the requested semaphore is unavailable.
+
+- The running task issues a ``rtems.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.
+
+- The running task issues a ``rtems.task_wake_when``
+  directive which blocks the task until the requested date and time arrives.
+
+- The running task issues a ``rtems.rate_monotonic_period``
+  directive and must wait for the specified rate monotonic period
+  to conclude.
+
+- The running task issues a ``rtems.region_get_segment``
+  directive with the wait option and there is not an available segment large
+  enough to satisfy the taskâs request.
+
+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:
+
+- A running task issues a ``rtems.task_resume``
+  directive for a task that is suspended and the task is not blocked
+  waiting on any resource.
+
+- A running task issues a ``rtems.message_queue_send``,``rtems.message_queue_broadcast``, or a``rtems.message_queue_urgent`` directive
+  which posts a message to the queue on which the blocked task is
+  waiting.
+
+- A running task issues an ``rtems.event_send``
+  directive which sends an event condition to a task which is blocked
+  waiting on that event condition.
+
+- A running task issues a ``rtems.semaphore_release``
+  directive which releases the semaphore on which the blocked task is
+  waiting.
+
+- A timeout interval expires for a task which was blocked
+  by a call to the ``rtems.task_wake_after`` directive.
+
+- A timeout period expires for a task which blocked by a
+  call to the ``rtems.task_wake_when`` directive.
+
+- A running task issues a ``rtems.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.
+
+- A rate monotonic period expires for a task which blocked
+  by a call to the ``rtems.rate_monotonic_period`` directive.
+
+- A timeout interval expires for a task which was blocked
+  waiting on a message, event, semaphore, or segment with a
+  timeout specified.
+
+- A running task issues a directive which deletes a
+  message queue, a semaphore, or a region on which the blocked
+  task is waiting.
+
+- A running task issues a ``rtems.task_restart``
+  directive for the blocked task.
+
+- 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:
+
+- The task is the highest priority ready task in the
+  system.
+
+- 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.
+
+- 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.
+
+- The running task lowers its own priority and another
+  task is of higher priority as a result.
+
+- The running task raises the priority of a task above its
+  own and the running task is in preemption mode.
+
+.. COMMENT: COPYRIGHT (c) 1988-2013.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: Open Issues
+
+.. COMMENT: - nicen up the tables
+
+.. COMMENT: - use math mode to print formulas
+
+Rate Monotonic Manager
+######################
+
+.. index:: rate mononitonic tasks
+.. index:: periodic tasks
+
+Introduction
+============
+
+The rate monotonic manager provides facilities to implement tasks which execute
+in a periodic fashion.  Critically, it also gathers information about the
+execution of those periods and can provide important statistics to the
+user which can be used to analyze and tune the application.  The directives
+provided by the rate monotonic manager are:
+
+- ``rtems.rate_monotonic_create`` - Create a rate monotonic period
+
+- ``rtems.rate_monotonic_ident`` - Get ID of a period
+
+- ``rtems.rate_monotonic_cancel`` - Cancel a period
+
+- ``rtems.rate_monotonic_delete`` - Delete a rate monotonic period
+
+- ``rtems.rate_monotonic_period`` - Conclude current/Start next period
+
+- ``rtems.rate_monotonic_get_status`` - Obtain status from a period
+
+- ``rtems.rate_monotonic_get_statistics`` - Obtain statistics from a period
+
+- ``rtems.rate_monotonic_reset_statistics`` - Reset statistics for a period
+
+- ``rtems.rate_monotonic_reset_all_statistics`` - Reset statistics for all periods
+
+- ``rtems.rate_monotonic_report_statistics`` - Print period statistics report
+
+Background
+==========
+
+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 ensure 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.
+
+Rate Monotonic Manager Required Support
+---------------------------------------
+
+A clock tick is required to support the functionality provided by this manager.
+
+Period Statistics
+-----------------
+
+This manager maintains a set of statistics on each period object.  These
+statistics are reset implictly at period creation time and may be reset or
+obtained at any time by the application.  The following is a list of the
+information kept:
+
+- ``owner``
+  is the id of the thread that owns this period.
+
+- ``count``
+  is the total number of periods executed.
+
+- ``missed_count``
+  is the number of periods that were missed.
+
+- ``min_cpu_time``
+  is the minimum amount of CPU execution time consumed
+  on any execution of the periodic loop.
+
+- ``max_cpu_time``
+  is the maximum amount of CPU execution time consumed
+  on any execution of the periodic loop.
+
+- ``total_cpu_time``
+  is the total amount of CPU execution time consumed
+  by executions of the periodic loop.
+
+- ``min_wall_time``
+  is the minimum amount of wall time that passed
+  on any execution of the periodic loop.
+
+- ``max_wall_time``
+  is the maximum amount of wall time that passed
+  on any execution of the periodic loop.
+
+- ``total_wall_time``
+  is the total amount of wall time that passed
+  during executions of the periodic loop.
+
+Each period is divided into two consecutive phases.  The period starts with the
+active phase of the task and is followed by the inactive phase of the task.  In
+the inactive phase the task is blocked and waits for the start of the next
+period.  The inactive phase is skipped in case of a period miss.  The wall time
+includes the time during the active phase of the task on which the task is not
+executing on a processor.  The task is either blocked (for example it waits for
+a resource) or a higher priority tasks executes, thus preventing it from
+executing.  In case the wall time exceeds the period time, then this is a
+period miss.  The gap between the wall time and the period time is the margin
+between a period miss or success.
+
+The period statistics information is inexpensive to maintain
+and can provide very useful insights into the execution
+characteristics of a periodic task loop.  But it is just information.
+The period statistics reported must be analyzed by the user in terms
+of what the applications is.  For example, in an application where
+priorities are assigned by the Rate Monotonic Algorithm, it would
+be very undesirable for high priority (i.e. frequency) tasks to
+miss their period.  Similarly, in nearly any application, if a
+task were supposed to execute its periodic loop every 10 milliseconds
+and it averaged 11 milliseconds, then application requirements
+are not being met.
+
+The information reported can be used to determine the "hot spots"
+in the application.  Given a periodâs id, the user can determine
+the length of that period.  From that information and the CPU usage,
+the user can calculate the percentage of CPU time consumed by that
+periodic task.  For example, a task executing for 20 milliseconds
+every 200 milliseconds is consuming 10 percent of the processorâs
+execution time.  This is usually enough to make it a good candidate
+for optimization.
+
+However, execution time alone is not enough to gauge the value of
+optimizing a particular task.  It is more important to optimize
+a task executing 2 millisecond every 10 milliseconds (20 percent
+of the CPU) than one executing 10 milliseconds every 100 (10 percent
+of the CPU).  As a general rule of thumb, the higher frequency at
+which a task executes, the more important it is to optimize that
+task.
+
+Rate Monotonic Manager Definitions
+----------------------------------
+.. index:: periodic task, definition
+
+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... index:: aperiodic task, definition
+
+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... index:: sporadic task, definition
+
+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
+ensures a minimum time period between successive activations,
+but the missile must be launched by a hard deadline.
+
+Rate Monotonic Scheduling Algorithm
+-----------------------------------
+.. index:: Rate Monotonic Scheduling Algorithm, definition
+.. index:: RMS Algorithm, definition
+
+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:
+
+- ```` *RMS is an optimal static priority algorithm for
+  scheduling independent, preemptible, periodic tasks
+  on a single processor.*
+
+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, then 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:
+.. code:: c
+
+    +--------------------+---------------------+---------------------+
+    |        Task        |       Period        |      Priority       |
+    |                    |  (in milliseconds)  |                     |
+    +--------------------+---------------------+---------------------+
+    |         1          |         100         |         Low         |
+    +--------------------+---------------------+---------------------+
+    |         2          |          50         |       Medium        |
+    +--------------------+---------------------+---------------------+
+    |         3          |          50         |       Medium        |
+    +--------------------+---------------------+---------------------+
+    |         4          |          25         |        High         |
+    +--------------------+---------------------+---------------------+
+
+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.
+
+Schedulability Analysis
+-----------------------
+
+.. index:: RMS schedulability analysis
+
+RMS allows application designers to ensure 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.
+
+Assumptions
+~~~~~~~~~~~
+
+The schedulability analysis rules for RMS were
+developed based on the following assumptions:
+
+- The requests for all tasks for which hard deadlines
+  exist are periodic, with a constant interval between requests.
+
+- Each task must complete before the next request for it
+  occurs.
+
+- The tasks are independent in that a task does not depend
+  on the initiation or completion of requests for other tasks.
+
+- The execution time for each task without preemption or
+  interruption is constant and does not vary.
+
+- Any non-periodic tasks in the system are special.  These
+  tasks displace periodic tasks while executing and do not have
+  hard, critical deadlines.
+
+Once the basic schedulability analysis is understood,
+some of the above assumptions can be relaxed and the
+side-effects accounted for.
+
+Processor Utilization Rule
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. index:: RMS 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:
+.. code:: c
+
+    Utilization = 0
+    for index = 1 to maximum_tasks
+    Utilization = Utilization + (Time(index)/Period(index))
+
+To ensure schedulability even under transient
+overload, the processor utilization must adhere to the following
+rule:
+.. code:: c
+
+    Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1)
+
+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.
+
+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:
+.. code:: c
+
+    +------------+----------+--------+-----------+-------------+
+    |    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     |
+    +------------+----------+--------+-----------+-------------+
+
+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.
+
+First Deadline Rule
+~~~~~~~~~~~~~~~~~~~
+.. index:: RMS 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 ensure.  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 ensures that all tasks begin to
+compete for execution time at the same instant â when the user
+initialization task deletes itself.
+
+First Deadline Rule Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The First Deadline Rule can ensure 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:
+.. code:: c
+
+    +------------+----------+--------+-----------+-------------+
+    |    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     |
+    +------------+----------+--------+-----------+-------------+
+
+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.
+.. code:: c
+
+    +----------+------+------+------+----------------------+---------------+
+    | 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       |
+    +----------+------+------+------+----------------------+---------------+
+
+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.
+
+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.
+
+Further Reading
+~~~~~~~~~~~~~~~
+
+For more information on Rate Monotonic Scheduling and
+its schedulability analysis, the reader is referred to the
+following:
+
+- ```` *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
+  Multiprogramming in a Hard Real Time Environment." *Journal of
+  the Association of Computing Machinery*. January 1973. pp. 46-61.*
+
+- ```` *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
+  Scheduling Algorithm: Exact Characterization and Average Case
+  Behavior."  *IEEE Real-Time Systems Symposium*. 1989. pp. 166-171.*
+
+- ```` *Lui Sha and John Goodenough. "Real-Time Scheduling
+  Theory and Ada."  *IEEE Computer*. April 1990. pp. 53-62.*
+
+- ```` *Alan Burns. "Scheduling hard real-time systems: a
+  review."  *Software Engineering Journal*. May 1991. pp. 116-128.*
+
+Operations
+==========
+
+Creating a Rate Monotonic Period
+--------------------------------
+
+The ``rtems.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.
+
+Manipulating a Period
+---------------------
+
+The ``rtems.rate_monotonic_period`` directive is used to
+establish and maintain periodic execution utilizing a previously
+created rate monotonic period.   Once initiated by the``rtems.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:
+
+- 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.
+
+- 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.
+
+- If the rate monotonic period has expired before the task
+  invokes the ``rtems.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.
+
+Obtaining the Status of a Period
+--------------------------------
+
+If the ``rtems.rate_monotonic_period`` directive is invoked
+with a period of ``RTEMS.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``rtems.rate_monotonic_period``
+directive:
+
+- ``RTEMS.SUCCESSFUL`` - period is running
+
+- ``RTEMS.TIMEOUT`` - period has expired
+
+- ``RTEMS.NOT_DEFINED`` - period has never been initiated
+
+Obtaining the status of a rate monotonic period does
+not alter the state or length of that period.
+
+Canceling a Period
+------------------
+
+The ``rtems.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 ``rtems.rate_monotonic_period`` directive.
+
+Deleting a Rate Monotonic Period
+--------------------------------
+
+The ``rtems.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.
+
+Examples
+--------
+
+The following sections illustrate common uses of rate
+monotonic periods to construct periodic tasks.
+
+Simple Periodic Task
+--------------------
+
+This example consists of a single periodic task
+which, after initialization, executes every 100 clock ticks.
+.. code:: c
+
+    rtems_task Periodic_task(rtems_task_argument arg)
+    {
+    rtems_name        name;
+    rtems_id          period;
+    rtems_status_code status;
+    name = rtems_build_name( 'P', 'E', 'R', 'D' );
+    status = rtems_rate_monotonic_create( name, &period );
+    if ( status != RTEMS_STATUS_SUCCESSFUL ) {
+    printf( "rtems_monotonic_create failed with status of %d.\\n", rc );
+    exit( 1 );
+    }
+    while ( 1 ) {
+    if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT )
+    break;
+    /* Perform some periodic actions \*/
+    }
+    /* missed period so delete period and SELF \*/
+    status = rtems_rate_monotonic_delete( period );
+    if ( status != RTEMS_STATUS_SUCCESSFUL ) {
+    printf( "rtems_rate_monotonic_delete failed with status of %d.\\n", status );
+    exit( 1 );
+    }
+    status = rtems_task_delete( SELF );    /* should not return \*/
+    printf( "rtems_task_delete returned with status of %d.\\n", status );
+    exit( 1 );
+    }
+
+The above task creates a rate monotonic period as
+part of its initialization.  The first time the loop is
+executed, the ``rtems.rate_monotonic_period``
+directive will initiate the period for 100 ticks and return
+immediately.  Subsequent invocations of the``rtems.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 ``rtems.rate_monotonic_period``
+directive will return the ``RTEMS.TIMEOUT`` status.
+If the above task misses its deadline, it will delete the rate
+monotonic period and itself.
+
+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.
+.. code:: c
+
+    rtems_task Periodic_task(rtems_task_argument arg)
+    {
+    rtems_name        name_1, name_2;
+    rtems_id          period_1, period_2;
+    rtems_status_code status;
+    name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
+    name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
+    (void ) rtems_rate_monotonic_create( name_1, &period_1 );
+    (void ) rtems_rate_monotonic_create( name_2, &period_2 );
+    while ( 1 ) {
+    if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
+    break;
+    if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
+    break;
+    /*
+    *  Perform first set of actions between clock
+    *  ticks 0 and 39 of every 100 ticks.
+    \*/
+    if ( rtems_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 ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
+    break;
+    (void) rtems_rate_monotonic_cancel( period_2 );
+    }
+    /* missed period so delete period and SELF \*/
+    (void ) rtems_rate_monotonic_delete( period_1 );
+    (void ) rtems_rate_monotonic_delete( period_2 );
+    (void ) task_delete( SELF );
+    }
+
+The above task creates two rate monotonic periods as
+part of its initialization.  The first time the loop is
+executed, the ``rtems.rate_monotonic_period``
+directive will initiate the period_1 period for 100 ticks
+and return immediately.  Subsequent invocations of the``rtems.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``rtems.rate_monotonic_cancel( period_2 )``
+call is performed to ensure 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 ``rtems.rate_monotonic_period( period_2, 40 )``
+call is executed, except for the initial one, a directive status
+of ``RTEMS.TIMEOUT`` is returned.  It is important to
+note that every time this call is made, the period_2 period will be
+initiated immediately and the task will not block.
+
+If, for any reason, the task misses any deadline, the``rtems.rate_monotonic_period`` directive will
+return the ``RTEMS.TIMEOUT``
+directive status.  If the above task misses its deadline, it
+will delete the rate monotonic periods and itself.
+
+Directives
+==========
+
+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.
+
+RATE_MONOTONIC_CREATE - Create a rate monotonic period
+------------------------------------------------------
+.. index:: create a period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Create (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - rate monotonic period created successfully
+``RTEMS.INVALID_NAME`` - invalid period name
+``RTEMS.TOO_MANY`` - too many periods created
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+RATE_MONOTONIC_IDENT - Get ID of a period
+-----------------------------------------
+.. index:: get ID of a period
+.. index:: obtain ID of a period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Ident (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period identified successfully
+``RTEMS.INVALID_NAME`` - period name not found
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+RATE_MONOTONIC_CANCEL - Cancel a period
+---------------------------------------
+.. index:: cancel a period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Cancel (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period canceled successfully
+``RTEMS.INVALID_ID`` - invalid rate monotonic period id
+``RTEMS.NOT_OWNER_OF_RESOURCE`` - rate monotonic period not created by calling task
+
+**DESCRIPTION:**
+
+This directive cancels the rate monotonic period id.
+This period will be reinitiated by the next invocation of``rtems.rate_monotonic_period`` with id.
+
+**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.
+
+RATE_MONOTONIC_DELETE - Delete a rate monotonic period
+------------------------------------------------------
+.. index:: delete a period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period deleted successfully
+``RTEMS.INVALID_ID`` - invalid rate monotonic period id
+
+**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.
+
+**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.
+
+RATE_MONOTONIC_PERIOD - Conclude current/Start next period
+----------------------------------------------------------
+.. index:: conclude current period
+.. index:: start current period
+.. index:: period initiation
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Period (
+    ID      : in     RTEMS.ID;
+    Length  : in     RTEMS.Interval;
+    Result  :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period initiated successfully
+``RTEMS.INVALID_ID`` - invalid rate monotonic period id
+``RTEMS.NOT_OWNER_OF_RESOURCE`` - period not created by calling task
+``RTEMS.NOT_DEFINED`` - period has never been initiated (only
+possible when period is set to PERIOD_STATUS)
+``RTEMS.TIMEOUT`` - period has expired
+
+**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 ``RTEMS.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.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+RATE_MONOTONIC_GET_STATUS - Obtain status from a period
+-------------------------------------------------------
+.. index:: get status of period
+.. index:: obtain status of period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Get_Status (
+    ID      : in     RTEMS.ID;
+    Status  :    out RTEMS.Rate_Monotonic_Period_Status;
+    Result  :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period initiated successfully
+``RTEMS.INVALID_ID`` - invalid rate monotonic period id
+``RTEMS.INVALID_ADDRESS`` - invalid address of status
+
+**DESCRIPTION:**
+
+This directive returns status information associated with
+the rate monotonic period id in the following data record:
+
+.. code:: c
+
+    type Rate_Monotonic_Period_Status is
+    begin
+    Owner                      : RTEMS.ID;
+    State                      : RTEMS.Rate_Monotonic_Period_States;
+    Since_Last_Period          : RTEMS.Unsigned32;
+    Executed_Since_Last_Period : RTEMS.Unsigned32;
+    end record;
+
+.. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
+
+A configure time option can be used to select whether the time information is
+given in ticks or seconds and nanoseconds.  The default is seconds and
+nanoseconds.  If the periodâs state is ``RATE_MONOTONIC_INACTIVE``, both
+time values will be set to 0.  Otherwise, both time values will contain
+time information since the last invocation of the``rtems.rate_monotonic_period`` directive.  More
+specifically, the (ticks_)since_last_period value contains the elapsed time
+which has occurred since the last invocation of the``rtems.rate_monotonic_period`` directive and the
+(ticks_)executed_since_last_period contains how much processor time the
+owning task has consumed since the invocation of the``rtems.rate_monotonic_period`` directive.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
+---------------------------------------------------------------
+.. index:: get statistics of period
+.. index:: obtain statistics of period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period initiated successfully
+``RTEMS.INVALID_ID`` - invalid rate monotonic period id
+``RTEMS.INVALID_ADDRESS`` - invalid address of statistics
+
+**DESCRIPTION:**
+
+This directive returns statistics information associated with
+the rate monotonic period id in the following data record:
+
+.. code:: c
+
+    NOT SUPPORTED FROM Ada BINDING
+
+This directive returns the current statistics information for
+the period instance assocaited with ``id``.  The information
+returned is indicated by the structure above.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
+---------------------------------------------------------------
+.. index:: reset statistics of period
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Reset_Statistics (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - period initiated successfully
+``RTEMS.INVALID_ID`` - invalid rate monotonic period id
+
+**DESCRIPTION:**
+
+This directive resets the statistics information associated with
+this rate monotonic period instance.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
+----------------------------------------------------------------------
+.. index:: reset statistics of all periods
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Reset_All_Statistics;
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive resets the statistics information associated with
+all rate monotonic period instances.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
+-----------------------------------------------------------------
+.. index:: print period statistics report
+.. index:: period statistics report
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Rate_Monotonic_Report_Statistics;
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive prints a report on all active periods which have
+executed at least one period. The following is an example of the
+output generated by this directive.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+.. COMMENT: COPYRIGHT (c) 1988-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Barrier Manager
+###############
+
+.. index:: barrier
+
+Introduction
+============
+
+The barrier manager provides a unique synchronization
+capability which can be used to have a set of tasks block
+and be unblocked as a set.  The directives provided by the
+barrier manager are:
+
+- ``rtems.barrier_create`` - Create a barrier
+
+- ``rtems.barrier_ident`` - Get ID of a barrier
+
+- ``rtems.barrier_delete`` - Delete a barrier
+
+- ``rtems.barrier_wait`` - Wait at a barrier
+
+- ``rtems.barrier_release`` - Release a barrier
+
+Background
+==========
+
+A barrier can be viewed as a gate at which tasks wait until
+the gate is opened.  This has many analogies in the real world.
+Horses and other farm animals may approach a closed gate and
+gather in front of it, waiting for someone to open the gate so
+they may proceed.  Similarly, cticket holders gather at the gates
+of arenas before concerts or sporting events waiting for the
+arena personnel to open the gates so they may enter.
+
+Barriers are useful during application initialization.  Each
+application task can perform its local initialization before
+waiting for the application as a whole to be initialized.  Once
+all tasks have completed their independent initializations,
+the "application ready" barrier can be released.
+
+Automatic Versus Manual Barriers
+--------------------------------
+
+Just as with a real-world gate, barriers may be configured to
+be manually opened or automatically opened.  All tasks
+calling the ``rtems.barrier_wait`` directive
+will block until a controlling task invokes the``rtems.barrier_release`` directive.
+
+Automatic barriers are created with a limit to the number of
+tasks which may simultaneously block at the barrier.  Once
+this limit is reached, all of the tasks are released.  For
+example, if the automatic limit is ten tasks, then the first
+nine tasks calling the ``rtems.barrier_wait`` directive
+will block.  When the tenth task calls the``rtems.barrier_wait`` directive, the nine
+blocked tasks will be released and the tenth task returns
+to the caller without blocking.
+
+Building a Barrier 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 barrier attributes:
+
+- ``RTEMS.BARRIER_AUTOMATIC_RELEASE`` - automatically
+  release the barrier when the configured number of tasks are blocked
+
+- ``RTEMS.BARRIER_MANUAL_RELEASE`` - only release
+  the barrier when the application invokes the``rtems.barrier_release`` directive.  (default)
+
+*NOTE*: Barriers only support FIFO blocking order because all
+waiting tasks are released as a set.  Thus the released tasks
+will all become ready to execute at the same time and compete
+for the processor based upon their priority.
+
+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``RTEMS.DEFAULT_ATTRIBUTES`` should be
+specified on this call.
+
+This example demonstrates the attribute_set parameter needed to create a
+barrier with the automatic release policy.  The``attribute_set`` parameter passed to the``rtems.barrier_create`` directive will be``RTEMS.BARRIER_AUTOMATIC_RELEASE``.  In this case, the
+user must also specify the *maximum_waiters* parameter.
+
+Operations
+==========
+
+Creating a Barrier
+------------------
+
+The ``rtems.barrier_create`` directive creates
+a barrier with a user-specified name and the desired attributes.
+RTEMS allocates a Barrier Control Block (BCB) from the BCB free list.
+This data structure is used by RTEMS to manage the newly created
+barrier.  Also, a unique barrier ID is generated and returned to
+the calling task.
+
+Obtaining Barrier IDs
+---------------------
+
+When a barrier is created, RTEMS generates a unique
+barrier ID and assigns it to the created barrier until it is
+deleted.  The barrier ID may be obtained by either of two
+methods.  First, as the result of an invocation of the``rtems.barrier_create`` directive, the
+barrier ID is stored in a user provided location.  Second,
+the barrier ID may be obtained later using the``rtems.barrier_ident`` directive.  The barrier ID is
+used by other barrier manager directives to access this
+barrier.
+
+Waiting at a Barrier
+--------------------
+
+The ``rtems.barrier_wait`` directive is used to wait at
+the specified barrier.  Since a barrier is, by definition, never immediately,
+the task may wait forever for the barrier to be released or it may
+specify a timeout.  Specifying a timeout limits the interval the task will
+wait before returning with an error status code.
+
+If the barrier is configured as automatic and there are already
+one less then the maximum number of waiters, then the call will
+unblock all tasks waiting at the barrier and the caller will
+return immediately.
+
+When the task does wait to acquire the barrier, then it
+is placed in the barrierâs task wait queue in FIFO order.
+All tasks waiting on a barrier are returned an error
+code when the barrier is deleted.
+
+Releasing a Barrier
+-------------------
+
+The ``rtems.barrier_release`` directive is used to release
+the specified barrier.  When the ``rtems.barrier_release``
+is invoked, all tasks waiting at the barrier are immediately made ready
+to execute and begin to compete for the processor to execute.
+
+Deleting a Barrier
+------------------
+
+The ``rtems.barrier_delete`` directive removes a barrier
+from the system and frees its control block.  A barrier can be
+deleted by any local task that knows the barrierâs ID.  As a
+result of this directive, all tasks blocked waiting for the
+barrier to be released, will be readied and returned a status code which
+indicates that the barrier was deleted.  Any subsequent
+references to the barrierâs name and ID are invalid.
+
+Directives
+==========
+
+This section details the barrier 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.
+
+BARRIER_CREATE - Create a barrier
+---------------------------------
+.. index:: create a barrier
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Barrier_Create (
+    Name            : in     RTEMS.Name;
+    Attribute_Set   : in     RTEMS.Attribute;
+    Maximum_Waiters : in     RTEMS.Unsigned32;
+    ID              :    out RTEMS.ID;
+    Result          :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - barrier created successfully
+``RTEMS.INVALID_NAME`` - invalid barrier name
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.TOO_MANY`` - too many barriers createdÂ 
+
+**DESCRIPTION:**
+
+This directive creates a barrier which resides on
+the local node. The created barrier has the user-defined name
+specified in ``name`` and the initial count specified in ``count``.  For
+control and maintenance of the barrier, RTEMS allocates and
+initializes a BCB.  The RTEMS-assigned barrier id is returned
+in ``id``.  This barrier id is used with other barrier related
+directives to access the barrier.
+
+``RTEMS.BARRIER_MANUAL_RELEASE`` - only release
+
+Specifying ``RTEMS.BARRIER_AUTOMATIC_RELEASE`` in``attribute_set`` causes tasks calling the``rtems.barrier_wait`` directive to block until
+there are ``maximum_waiters - 1`` tasks waiting at the barrier.
+When the ``maximum_waiters`` task invokes the``rtems.barrier_wait`` directive, the previous``maximum_waiters - 1`` tasks are automatically released
+and the caller returns.
+
+In contrast, when the ``RTEMS.BARRIER_MANUAL_RELEASE``
+attribute is specified, there is no limit on the number of
+tasks that will block at the barrier. Only when the``rtems.barrier_release`` directive is invoked,
+are the tasks waiting at the barrier unblocked.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+The following barrier attribute constants are defined by RTEMS:
+
+- ``RTEMS.BARRIER_AUTOMATIC_RELEASE`` - automatically
+  release the barrier when the configured number of tasks are blocked
+
+- ``RTEMS.BARRIER_MANUAL_RELEASE`` - only release
+  the barrier when the application invokes the``rtems.barrier_release`` directive.  (default)
+
+BARRIER_IDENT - Get ID of a barrier
+-----------------------------------
+.. index:: get ID of a barrier
+.. index:: obtain ID of a barrier
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Barrier_Ident (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - barrier identified successfully
+``RTEMS.INVALID_NAME`` - barrier name not found
+``RTEMS.INVALID_NODE`` - invalid node id
+
+**DESCRIPTION:**
+
+This directive obtains the barrier id associated
+with the barrier name.  If the barrier name is not unique,
+then the barrier id will match one of the barriers with that
+name.  However, this barrier id is not guaranteed to
+correspond to the desired barrier.  The barrier id is used
+by other barrier related directives to access the barrier.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+BARRIER_DELETE - Delete a barrier
+---------------------------------
+.. index:: delete a barrier
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Barrier_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - barrier deleted successfully
+``RTEMS.INVALID_ID`` - invalid barrier idÂ 
+
+**DESCRIPTION:**
+
+This directive deletes the barrier specified by ``id``.
+All tasks blocked waiting for the barrier to be released will be
+readied and returned a status code which indicates that the
+barrier was deleted.  The BCB for this barrier is reclaimed
+by RTEMS.
+
+**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 barrier.  The calling task will NOT be
+preempted if all of the tasks that are waiting on the barrier
+are remote tasks.
+
+The calling task does not have to be the task that
+created the barrier.  Any local task that knows the barrier
+id can delete the barrier.
+
+.. COMMENT: Barrier Obtain
+
+BARRIER_OBTAIN - Acquire a barrier
+----------------------------------
+.. index:: obtain a barrier
+.. index:: lock a barrier
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Barrier_Wait (
+    ID         : in     RTEMS.ID;
+    Timeout    : in     RTEMS.Interval;
+    Result     :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - barrier released and task unblocked
+``RTEMS.UNSATISFIED`` - barrier not available
+``RTEMS.TIMEOUT`` - timed out waiting for barrier
+``RTEMS.OBJECT_WAS_DELETED`` - barrier deleted while waiting
+``RTEMS.INVALID_ID`` - invalid barrier id
+
+**DESCRIPTION:**
+
+This directive acquires the barrier specified by
+id.  The ``RTEMS.WAIT`` and ``RTEMS.NO_WAIT``
+components of the options parameter indicate whether the calling task
+wants to wait for the barrier to become available or return immediately
+if the barrier is not currently available.  With either``RTEMS.WAIT`` or ``RTEMS.NO_WAIT``,
+if the current barrier count is positive, then it is
+decremented by one and the barrier is successfully acquired by
+returning immediately with a successful return code.
+
+Conceptually, the calling task should always be thought
+of as blocking when it makes this call and being unblocked when
+the barrier is released.  If the barrier is configured for
+manual release, this rule of thumb will always be valid.
+If the barrier is configured for automatic release, all callers
+will block except for the one which is the Nth task which trips
+the automatic release condition.
+
+The timeout parameter specifies the maximum interval the calling task is
+willing to be blocked waiting for the barrier.  If it is set to``RTEMS.NO_TIMEOUT``, then the calling task will wait forever.
+If the barrier is available or the ``RTEMS.NO_WAIT`` option
+component is set, then timeout is ignored.
+
+**NOTES:**
+
+The following barrier acquisition option constants are defined by RTEMS:
+
+- ``RTEMS.WAIT`` - task will wait for barrier (default)
+
+- ``RTEMS.NO_WAIT`` - task should not wait
+
+A clock tick is required to support the timeout functionality of
+this directive.
+
+.. COMMENT: Release Barrier
+
+BARRIER_RELEASE - Release a barrier
+-----------------------------------
+.. index:: wait at a barrier
+.. index:: release a barrier
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Barrier_Release (
+    ID       : in     RTEMS.ID;
+    Released :    out RTEMS.Unsigned32;
+    Result   :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - barrier released successfully
+``RTEMS.INVALID_ID`` - invalid barrier id
+
+**DESCRIPTION:**
+
+This directive releases the barrier specified by id.
+All tasks waiting at the barrier will be unblocked.
+If the running taskâs preemption mode is enabled and one of
+the unblocked tasks has a higher priority than the running task.
+
+**NOTES:**
+
+The calling task may be preempted if it causes a
+higher priority task to be made ready for execution.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Board Support Packages
+######################
+
+.. index:: Board Support Packages
+.. index:: BSPs
+
+Introduction
+============
+.. index:: BSP, definition
+
+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.
+
+Reset and Initialization
+========================
+
+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 BSP and some of the application initialization is
+intertwined in the RTEMS initialization sequence controlled by
+the shared function ``boot_card()``.
+
+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 context switch to the first task,
+the Interrupt Vector Table MUST be set before this directive is invoked
+to ensure correct interrupt vectoring.  The processorâs Interrupt Vector
+Table must be accessible by RTEMS as it will be modified by the when
+installing user Interrupt Service Routines (ISRs) 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 any RTEMS initialization routines has the
+following requirements:
+
+- Must not make any blocking RTEMS directive calls.
+
+- If the processor supports multiple privilege levels, must leave
+  the processor in the most privileged, or supervisory, state.
+
+- Must allocate a stack of sufficient size to execute the initialization
+  and shutdown of the system.  This stack area will NOT be used by any task
+  once the system is initialized.  This stack is often reserved via the
+  linker script or in the assembly language start up file.
+
+- Must initialize the stack pointer for the initialization process to
+  that allocated.
+
+- Must initialize the processorâs Interrupt Vector Table.
+
+- Must disable all maskable interrupts.
+
+- If the processor supports a separate interrupt stack, must allocate
+  the interrupt stack and initialize the interrupt stack pointer.
+
+At the end of the initialization sequence, RTEMS does not return to the
+BSP initialization code, but instead context switches to the highest
+priority task to begin application execution.  This task is typically
+a User Initialization Task which is responsible for performing both
+local and global application initialization which is dependent on RTEMS
+facilities.  It is also responsible for initializing any higher level
+RTEMS services the application uses such as networking and blocking
+device drivers.
+
+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:
+
+- Processorâs interrupt stack frame
+
+- Processorâs subroutine call stack frame
+
+- RTEMS system calls
+
+- Registers saved on stack
+
+- Application subroutine calls
+
+The size of the interrupt stack must be greater than or equal to the
+confugured minimum stack size.
+
+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 on some
+architectures is supplied and initialized by the reset and initialization
+code of the userâs Board Support Package.  Whether allocated and
+initialized by the BSP or RTEMS, since all ISRs use this stack, the
+stack size must take into account the worst case stack usage by any
+combination of nested ISRs.
+
+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.
+
+Device Drivers
+==============
+
+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.
+
+Clock Tick Device Driver
+------------------------
+
+Most RTEMS applications will include a clock tick
+device driver which invokes the ``rtems.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 ``rtems.clock_tick`` on the
+configured ``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.
+
+User Extensions
+===============
+
+RTEMS allows the application developer to augment
+selected features by invoking user-supplied extension routines
+when the following system events occur:
+
+- Task creation
+
+- Task initiation
+
+- Task reinitiation
+
+- Task deletion
+
+- Task context switch
+
+- Post task context switch
+
+- Task begin
+
+- Task exits
+
+- Fatal error detection
+
+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:ref:`User Extensions Manager <User-Extensions-Manager>` chapter.
+
+Multiprocessor Communications Interface (MPCI)
+==============================================
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. _User-Extensions-Manager:
+
+User Extensions Manager
+#######################
+
+.. index:: user extensions
+
+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:
+
+- ``rtems.extension_create`` - Create an extension set
+
+- ``rtems.extension_ident`` - Get ID of an extension set
+
+- ``rtems.extension_delete`` - Delete an extension set
+
+Background
+==========
+
+User extension routines are invoked when the
+following system events occur:
+
+- Task creation
+
+- Task initiation
+
+- Task reinitiation
+
+- Task deletion
+
+- Task context switch
+
+- Post task context switch
+
+- Task begin
+
+- Task exits
+
+- Fatal error detection
+
+These extensions are invoked as a function with
+arguments that are appropriate to the system event.
+
+Extension Sets
+--------------
+.. index:: extension set
+
+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 record:.. index:: rtems_extensions_table
+
+.. code:: c
+
+    type Extensions_Table is
+    record
+    Task_Create      : RTEMS.Task_Create_Extension;
+    Task_Start       : RTEMS.Task_Start_Extension;
+    Task_Restart     : RTEMS.Task_Restart_Extension;
+    Task_Delete      : RTEMS.Task_Delete_Extension;
+    Task_Switch      : RTEMS.Task_Switch_Extension;
+    Task_Post_Switch : RTEMS.Task_Post_Switch_Extension;
+    Task_Begin       : RTEMS.Task_Begin_Extension;
+    Task_Exitted     : RTEMS.Task_Exitted_Extension;
+    Fatal            : RTEMS.Fatal_Error_Extension;
+    end record;
+
+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 ``rtems.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. The user extension entry points
+are copied into an internal RTEMS structure. This means the user
+does not need to keep the table after creating it, and changing the
+handler entry points dynamically in a table once created has no
+effect. Creating a table local to a function can save space in
+space limited applications.
+
+Extension switches do not effect the context switch overhead if
+no switch handler is installed.
+
+TCB Extension Area
+------------------
+.. index:: 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.
+
+The TCB extension is an array of pointers in the TCB. The
+index into the table can be obtained from the extension id
+returned when the extension is created:.. index:: rtems extensions table index
+
+.. code:: c
+
+    There is currently no example for Ada.
+
+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.
+
+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 Ada
+subprogram 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.
+
+TASK_CREATE Extension
+~~~~~~~~~~~~~~~~~~~~~
+
+The TASK_CREATE extension directly corresponds to the``rtems.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:.. index:: rtems_task_create_extension
+.. index:: rtems_extension
+
+.. code:: c
+
+    function User_Task_Create (
+    Current_Task : in     RTEMS.TCB_Pointer;
+    New_Task     : in     RTEMS.TCB_Pointer
+    ) returns Boolean;
+
+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 ``rtems.task_create``
+directive after ``new_task`` has been
+completely initialized, but before it is placed on a ready TCB
+chain.
+
+The user extension is expected to return the boolean
+value ``true`` if it successfully executed and``false`` otherwise.  A task create user extension
+will frequently attempt to allocate resources.  If this
+allocation fails, then the extension should return``false`` and the entire task create operation
+will fail.
+
+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:.. index:: rtems_task_start_extension
+
+.. code:: c
+
+    procedure User_Task_Start (
+    Current_Task : in     RTEMS.TCB_Pointer;
+    Started_Task : in     RTEMS.TCB_Pointer
+    );
+
+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.
+
+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:.. index:: rtems_task_restart_extension
+
+.. code:: c
+
+    procedure User_Task_Restart (
+    Current_Task   : in     RTEMS.TCB_Pointer;
+    Restarted_Task : in     RTEMS.TCB_Pointer
+    );
+
+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.
+
+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:.. index:: rtems_task_delete_extension
+
+.. code:: c
+
+    procedure User_Task_Delete (
+    Current_Task : in     RTEMS.TCB_Pointer;
+    Deleted_Task : in     RTEMS.TCB_Pointer
+    );
+
+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).
+
+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:.. index:: rtems_task_switch_extension
+
+.. code:: c
+
+    procedure User_Task_Switch (
+    Current_Task : in     RTEMS.TCB_Pointer;
+    Heir_Task    : in     RTEMS.TCB_Pointer
+    );
+
+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.
+
+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:.. index:: rtems_task_begin_extension
+
+.. code:: c
+
+    procedure User_Task_Begin (
+    Current_Task : in     RTEMS.TCB_Pointer
+    );
+
+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.
+
+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:.. index:: rtems_task_exitted_extension
+
+.. code:: c
+
+    procedure User_Task_Exitted (
+    Current_Task : in     RTEMS.TCB_Pointer
+    );
+
+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 ``RTEMS.TASK_EXITTED`` directive status.
+
+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:.. index:: rtems_fatal_extension
+
+.. code:: c
+
+    procedure User_Fatal_Error (
+    Error : in     RTEMS.Unsigned32
+    );
+
+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.
+
+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:
+
+- Task creation
+
+- Task initiation
+
+- Task reinitiation
+
+- Task deletion
+
+- Task context switch
+
+- Post task context switch
+
+- Task begins to execute
+
+At the following system events, the extensions are
+invoked in reverse order:
+
+- Task deletion
+
+- Fatal error detection
+
+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.
+
+Operations
+==========
+
+Creating an Extension Set
+-------------------------
+
+The ``rtems.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.
+
+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 ``rtems.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 ``rtems.extension_ident``
+directive.  The extension set ID is used by other directives
+to manipulate this extension set.
+
+Deleting an Extension Set
+-------------------------
+
+The ``rtems.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.
+
+Directives
+==========
+
+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.
+
+EXTENSION_CREATE - Create a extension set
+-----------------------------------------
+.. index:: create an extension set
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Extension_Create (
+    Name   : in     RTEMS.Name;
+    Table  : in     RTEMS.Extensions_Table_Pointer;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - extension set created successfully
+``RTEMS.INVALID_NAME`` - invalid extension set name
+``RTEMS.TOO_MANY`` - too many extension sets created
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the calling task to be
+preempted.
+
+EXTENSION_IDENT - Get ID of a extension set
+-------------------------------------------
+.. index:: get ID of an extension set
+.. index:: obtain ID of an extension set
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Extension_Ident (
+    Name   : in     RTEMS.Name;
+    ID     :    out RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - extension set identified successfully
+``RTEMS.INVALID_NAME`` - extension set name not found
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+EXTENSION_DELETE - Delete a extension set
+-----------------------------------------
+.. index:: delete an extension set
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Extension_Delete (
+    ID     : in     RTEMS.ID;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - extension set deleted successfully
+``RTEMS.INVALID_ID`` - invalid extension set id
+
+**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.
+
+**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.
+
+**NOTES:**
+
+This directive will not cause the running task to be
+preempted.
+
+.. COMMENT: COPYRIGHT (c) 1988-2015.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+.. COMMENT: TODO:
+
+.. COMMENT: + Ensure all macros are documented.
+
+.. COMMENT: + Verify which structures may actually be defined by a user
+
+.. COMMENT: + Add Go configuration.
+
+.. COMMENT: Questions:
+
+.. COMMENT: + Should there be examples of defining your own
+
+.. COMMENT: Device Driver Table, Init task table, etc.?
+
+.. _Configuring-a-System:
+
+Configuring a System
+####################
+
+.. COMMENT: === Introduction ===
+
+Introduction
+============
+
+RTEMS must be configured for an application.  This configuration
+encompasses a variety of information including the length of each clock
+tick, the maximum number of each information RTEMS object that can
+be created, the application initialization tasks, the task scheduling
+algorithm to be used, and the device drivers in the application.
+
+Although this information is contained in data structures that are used
+by RTEMS at system initialization time, the data structures themselves
+should only rarely to be generated by hand. RTEMS provides a set of
+macros system which provides a simple standard mechanism to automate
+the generation of these structures.
+
+System configuration is ALWAYS done from C.  When developing
+an Ada application, the user is responsible for creating at
+least one C file which contains the Ada run-time initialization
+and the RTEMS System Configuration.  There is no Ada binding
+for RTEMS System Configuration information.  Thus all examples
+and data structures shown in this chapter are in C... index:: confdefs.h
+.. index:: confdefs.h
+.. index:: <rtems/confdefs.h>
+.. index:: <rtems/confdefs.h>
+
+The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the
+automatic generation of system configuration. It is based on the idea
+of setting macros which define configuration parameters of interest to
+the application and defaulting or calculating all others. This variety
+of macros can automatically produce all of the configuration data
+required for an RTEMS application.
+
+Trivia: ``confdefs`` is shorthand for a *Configuration Defaults*.
+
+As a general rule, application developers only specify values
+for the configuration parameters of interest to them. They define what
+resources or features they require. In most cases, when a parameter is
+not specified, it defaults to zero (0) instances, a standards compliant
+value, or disabled as appropriate. For example, by default there will be
+256 task priority levels but this can be lowered by the application. This
+number of priority levels is required to be compliant with the RTEID/ORKID
+standards upon which the Classic API is based. There are similar cases
+where the default is selected to be compliant with with the POSIX standard.
+
+For each configuration parameter in the configuration tables, the macro
+corresponding to that field is discussed. The RTEMS Maintainers
+expect that all systems can be easily configured using the``<rtems/confdefs.h>`` mechanism and that using this mechanism will
+avoid internal RTEMS configuration changes impacting applications.
+
+.. COMMENT: === Philosophy ===
+
+Default Value Selection Philosophy
+==================================
+
+The user should be aware that the defaults are intentionally set as
+low as possible.  By default, no application resources are configured.
+The ``<rtems/confdefs.h>`` file ensures that at least one application
+task or thread is configured and that at least one of the initialization
+task/thread tables is configured.
+
+.. COMMENT: === Sizing the RTEMS Workspace ===
+
+.. _Configuring-a-System-Sizing-the-RTEMS-Workspace:
+
+Sizing the RTEMS Workspace
+==========================
+
+The RTEMS 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 Workspace.
+
+The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS
+Workspace automatically.  It assumes that all tasks are floating point and
+that all will be allocated the minimum stack space.  This calculation
+includes the amount of memory that will be allocated for internal use
+by RTEMS. The automatic calculation may underestimate the workspace
+size truly needed by the application, in which case one can use the``CONFIGURE_MEMORY_OVERHEAD`` macro to add a value to the estimate. See:ref:`Configuring a System Specify Memory Overhead <Configuring-a-System-Specify-Memory-Overhead>` for more details.
+
+The memory area for the RTEMS Workspace is determined by the BSP.  In case the
+RTEMS Workspace is too large for the available memory, then a fatal run-time
+error occurs and the system terminates.
+
+The file ``<rtems/confdefs.h>`` will calculate the value of the``work_space_size`` parameter of the Configuration Table. There
+are many parameters the application developer can specify to
+help ``<rtems/confdefs.h>`` in its calculations.  Correctly
+specifying the application requirements via parameters such as``CONFIGURE_EXTRA_TASK_STACKS`` and ``CONFIGURE_MAXIMUM_TASKS``
+is critical for production software.
+
+For each class of objects, the allocation can operate in one of two ways.
+The default way has an ceiling on the maximum number of object instances
+which can concurrently exist in the system. Memory for all instances of
+that object class is reserved at system initialization.  The second
+way allocates memory for an initial number of objects and increases the
+current allocation by a fixed increment when required. Both ways allocate
+space from inside the RTEMS Workspace.
+
+See :ref:`Configuring a System Unlimited Objects <Configuring-a-System-Unlimited-Objects>` for more details about
+the second way, which allows for dynamic allocation of objects and
+therefore does not provide determinism.  This mode is useful mostly for
+when the number of objects cannot be determined ahead of time or when
+porting software for which you do not know the object requirements.
+
+The space needed for stacks and for RTEMS objects will vary from
+one version of RTEMS and from one target processor to another.
+Therefore it is safest to use ``<rtems/confdefs.h>`` and specify
+your applicationâs requirements in terms of the numbers of objects and
+multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as is possible. The
+automatic estimates of space required will in general change when:
+
+- a configuration parameter is changed,
+
+- task or interrupt stack sizes change,
+
+- the floating point attribute of a task changes,
+
+- task floating point attribute is altered,
+
+- RTEMS is upgraded, or
+
+- the target processor is changed.
+
+Failure to provide enough space in the RTEMS Workspace may result in fatal
+run-time errors terminating the system.
+
+.. COMMENT: === Potential Issues ===
+
+Potential Issues with RTEMS Workspace Size Estimation
+=====================================================
+
+The ``<rtems/confdefs.h>`` file estimates the amount of memory
+required for the RTEMS Workspace.  This estimate is only as accurate
+as the information given to ``<rtems/confdefs.h>`` and may be either
+too high or too low for a variety of reasons.  Some of the reasons that``<rtems/confdefs.h>`` may reserve too much memory for RTEMS are:
+
+- All tasks/threads are assumed to be floating point.
+
+Conversely, there are many more reasons that the resource estimate could be
+too low:
+
+- Task/thread stacks greater than minimum size must be
+  accounted for explicitly by developer.
+
+- Memory for messages is not included.
+
+- Device driver requirements are not included.
+
+- Network stack requirements are not included.
+
+- Requirements for add-on libraries are not included.
+
+In general, ``<rtems/confdefs.h>`` is very accurate when given enough
+information.  However, it is quite easy to use a library and forget to
+account for its resources.
+
+.. COMMENT: === Format to be followed for making changes in this file ===
+
+Format to be followed for making changes in this file
+=====================================================
+
+- MACRO NAME
+  Should be alphanumeric. Can have â_â (underscore).
+
+- DATA TYPE
+  Please refer to all existing formats.
+
+- RANGE:
+  The range depends on the Data Type of the macro.
+  - â If the data type is of type task priority, then its value should
+    be an integer in the range of 1 to 255.
+  - â If the data type is an integer, then it can have numbers, characters
+    (in case the value is defined using another macro) and arithmetic operations
+    (+, -, \*, /).
+  - â If the data type is a function pointer the first character
+    should be an alphabet or an underscore. The rest of the string
+    can be alphanumeric.
+  - â If the data type is RTEMS Attributes or RTEMS Mode then
+    the string should be alphanumeric.
+  - â If the data type is RTEMS NAME then the value should be
+    an integer>=0 or RTEMS_BUILD_NAME( âUâ, âIâ, â1â, â â )
+
+- DEFAULT VALUE
+  The default value should be in the following formats-
+  Please note that the â.â (full stop) is necessary.
+  - â In case the value is not defined then:
+    This is not defined by default.
+  - â If we know the default value then:
+    The default value is XXX.
+  - â If the default value is BSP Specific then:
+    This option is BSP specific.
+
+- DESCRIPTION
+  The description of the macro. (No specific format)
+
+- NOTES
+  Any further notes. (No specific format)
+
+.. COMMENT: === Configuration Example ===
+
+Configuration Example
+=====================
+
+In the following example, the configuration information for a system
+with a single message queue, four (4) tasks, and a timeslice of
+fifty (50) milliseconds is as follows:
+.. code:: c
+
+    #include <bsp.h>
+    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+    #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+    #define CONFIGURE_MICROSECONDS_PER_TICK   1000 /* 1 millisecond \*/
+    #define CONFIGURE_TICKS_PER_TIMESLICE       50 /* 50 milliseconds \*/
+    #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+    #define CONFIGURE_MAXIMUM_TASKS 4
+    #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1
+    #define CONFIGURE_MESSAGE_BUFFER_MEMORY \\
+    CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE))
+    #define CONFIGURE_INIT
+    #include <rtems/confdefs.h>
+
+In this example, only a few configuration parameters are specified. The
+impact of these are as follows:
+
+- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE``
+  but did not specify any additional parameters. This results in a
+  configuration of an application which will begin execution of a single
+  initialization task named ``Init`` which is non-preemptible and at
+  priority one (1).
+
+- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``,
+  this application is configured to have a clock tick device
+  driver. Without a clock tick device driver, RTEMS has no way to know
+  that time is passing and will be unable to support delays and wall
+  time. Further configuration details about time are
+  provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a
+  clock tick to occur each millisecond, and that the length of a timeslice
+  would be fifty (50) milliseconds.
+
+- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
+  the application will include a console device driver. Although the
+  console device driver may support a combination of multiple serial
+  ports and display and keyboard combinations, it is only required to
+  provide a single device named ``/dev/console``. This device will
+  be used for Standard Input, Output and Error I/O Streams. Thus when``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is specified, implicitly
+  three (3) file descriptors are reserved for the Standard I/O Streams and
+  those file descriptors are associated with ``/dev/console`` during
+  initialization. All console devices are expected to support the POSIX*termios* interface.
+
+- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS``
+  that the application requires a maximum of four (4)
+  simultaneously existing Classic API tasks. Similarly, by specifying``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, there may be a maximum of only
+  one (1) concurrently existent Classic API message queues.
+
+- The most surprising configuration parameter in this example is the
+  use of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is
+  allocated from the RTEMS Workspace and must be accounted for. In this
+  example, the single message queue will have up to twenty (20) messages
+  of type ``struct USER_MESSAGE``.
+
+- The ``CONFIGURE_INIT`` constant must be defined in order to
+  make ``<rtems/confdefs.h>`` instantiate the configuration data
+  structures.  This can only be defined in one source file per
+  application that includes ``<rtems/confdefs.h>`` or the symbol
+  table will be instantiated multiple times and linking errors
+  produced.
+
+This example illustrates that parameters have default values. Among
+other things, the application implicitly used the following defaults:
+
+- All unspecified types of communications and synchronization objects
+  in the Classic and POSIX Threads API have maximums of zero (0).
+
+- The filesystem will be the default filesystem which is the In-Memory File
+  System (IMFS).
+
+- The application will have the default number of priority levels.
+
+- The minimum task stack size will be that recommended by RTEMS for
+  the target architecture.
+
+.. COMMENT: === Unlimited Objects ===
+
+.. _Configuring-a-System-Unlimited-Objects:
+
+Unlimited Objects
+-----------------
+
+In real-time embedded systems the RAM is normally a limited, critical
+resource and dynamic allocation is avoided as much as possible to
+ensure predictable, deterministic execution times. For such cases, see:ref:`Configuring a System Sizing the RTEMS Workspace <Configuring-a-System-Sizing-the-RTEMS-Workspace>` for an overview
+of how to tune the size of the workspace.  Frequently when users are
+porting software to RTEMS the precise resource requirements of the
+software is unknown. In these situations users do not need to control
+the size of the workspace very tightly because they just want to get
+the new software to run; later they can tune the workspace size as needed.
+
+The following API-independent object classes can be configured in
+unlimited mode:
+
+- POSIX Keys
+
+- POSIX Key Value Pairs
+
+The following object classes in the Classic API can be configured in
+unlimited mode:
+
+- Tasks
+
+- Timers
+
+- Semaphores
+
+- Message Queues
+
+- Periods
+
+- Barriers
+
+- Partitions
+
+- Regions
+
+- Ports
+
+Additionally, the following object classes from the POSIX API can be
+configured in unlimited mode:
+
+- Threads
+
+- Mutexes
+
+- Condition Variables
+
+- Timers
+
+- Message Queues
+
+- Message Queue Descriptors
+
+- Semaphores
+
+- Barriers
+
+- Read/Write Locks
+
+- Spinlocks
+
+The following object classes can *not* be configured in unlimited mode:
+
+- Drivers
+
+- File Descriptors
+
+- User Extensions
+
+- POSIX Queued Signals
+
+Due to the memory requirements of unlimited objects it is strongly recommended
+to use them only in combination with the unified work areas. See:ref:`Configuring a System Separate or Unified Work Areas <Configuring-a-System-Separate-or-Unified-Work-Areas>` for more information
+on unified work areas.
+
+The following example demonstrates how the two simple configuration defines for
+unlimited objects and unified works areas can replace many seperate
+configuration defines for supported object classes:
+.. code:: c
+
+    #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+    #define CONFIGURE_UNIFIED_WORK_AREAS
+    #define CONFIGURE_UNLIMITED_OBJECTS
+    #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+    #define CONFIGURE_INIT
+    #include <rtems/confdefs.h>
+
+Users are cautioned that using unlimited objects is not recommended for
+production software unless the dynamic growth is absolutely required. It
+is generally considered a safer embedded systems programming practice to
+know the system limits rather than experience an out of memory error
+at an arbitrary and largely unpredictable time in the field.
+
+.. COMMENT: === Per Object Class Unlimited Object Instances ===
+
+Per Object Class Unlimited Object Instances
+-------------------------------------------
+.. index:: rtems_resource_unlimited
+
+When the number of objects is not known ahead of time, RTEMS provides an
+auto-extending mode that can be enabled individually for each object
+type by using the macro ``rtems_resource_unlimited``. This takes a value
+as a parameter, and is used to set the object maximum number field in
+an API Configuration table. The value is an allocation unit size. When
+RTEMS is required to grow the object table it is grown by this
+size. The kernel will return the object memory back to the RTEMS Workspace
+when an object is destroyed. The kernel will only return an allocated
+block of objects to the RTEMS Workspace if at least half the allocation
+size of free objects remain allocated. RTEMS always keeps one
+allocation block of objects allocated. Here is an example of using``rtems_resource_unlimited``:
+.. code:: c
+
+    #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
+
+.. index:: rtems_resource_is_unlimited
+.. index:: rtems_resource_maximum_per_allocation
+
+Object maximum specifications can be evaluated with the``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` macros.
+
+.. COMMENT: === Unlimited Object Instances ===
+
+Unlimited Object Instances
+--------------------------
+
+To ease the burden of developers who are porting new software RTEMS
+also provides the capability to make all object classes listed above
+operate in unlimited mode in a simple manner. The application developer
+is only responsible for enabling unlimited objects and specifying the
+allocation size.
+
+.. COMMENT: === CONFIGURE_UNLIMITED_OBJECTS ===
+
+Enable Unlimited Object Instances
+---------------------------------
+.. index:: CONFIGURE_UNLIMITED_OBJECTS
+
+*CONSTANT:*
+    ``CONFIGURE_UNLIMITED_OBJECTS``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited``
+mode for Classic API and POSIX API objects that do not already have a
+specific maximum limit defined.
+
+**NOTES:**
+
+When using unlimited objects, it is common practice to also specify``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single
+pool of memory for both RTEMS and application memory allocations.
+
+.. COMMENT: === CONFIGURE_UNLIMITED_ALLOCATION_SIZE ===
+
+Specify Unlimited Objects Allocation Size
+-----------------------------------------
+
+*CONSTANT:*
+    ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, the
+    default value is eight (8).
+
+**DESCRIPTION:**
+
+``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an
+allocation size to use for ``rtems_resource_unlimited`` when using``CONFIGURE_UNLIMITED_OBJECTS``.
+
+**NOTES:**
+
+By allowing users to declare all resources as being unlimited
+the user can avoid identifying and limiting the resources used.``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the allocation
+sizes for different objects; users who want that much control can define
+the ``rtems_resource_unlimited`` macros themselves.
+.. code:: c
+
+    #define CONFIGURE_UNLIMITED_OBJECTS
+    #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
+
+.. COMMENT: === Classic API Configuration ===
+
+Classic API Configuration
+=========================
+
+This section defines the Classic API related system configuration
+parameters supported by ``<rtems/confdefs.h>``.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_TASKS ===
+
+Specify Maximum Classic API Tasks
+---------------------------------
+.. index:: CONFIGURE_MAXIMUM_TASKS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_TASKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API
+Tasks that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+The calculations for the required memory in the RTEMS Workspace
+for tasks assume that each task has a minimum stack size and
+has floating point support enabled.  The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack
+requirements *ABOVE* the minimum size required.  See:ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
+
+The maximum number of POSIX threads is specified by``CONFIGURE_MAXIMUM_POSIX_THREADS``.
+
+.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS.
+
+A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate
+the assumption that all tasks have floating point enabled. This would
+require the addition of a new configuration parameter to specify the
+number of tasks which enable floating point support.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_TIMERS ===
+
+Specify Maximum Classic API Timers
+----------------------------------
+.. index:: CONFIGURE_MAXIMUM_TIMERS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_TIMERS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API
+Timers that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_SEMAPHORES ===
+
+Specify Maximum Classic API Semaphores
+--------------------------------------
+.. index:: CONFIGURE_MAXIMUM_SEMAPHORES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_SEMAPHORES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic
+API Semaphores that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES ===
+
+Specify Maximum Classic API Semaphores usable with MrsP
+-------------------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the
+maximum number of Classic API Semaphores using the Multiprocessor Resource
+Sharing Protocol (MrsP) that can be concurrently active.
+
+**NOTES:**
+
+This configuration option is only used on SMP configurations.  On uni-processor
+configurations the Priority Ceiling Protocol is used for MrsP semaphores and
+thus no extra memory is necessary.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_MESSAGE_QUEUES ===
+
+Specify Maximum Classic API Message Queues
+------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic
+API Message Queues that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_BARRIERS ===
+
+Specify Maximum Classic API Barriers
+------------------------------------
+.. index:: CONFIGURE_MAXIMUM_BARRIERS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_BARRIERS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic
+API Barriers that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_PERIODS ===
+
+Specify Maximum Classic API Periods
+-----------------------------------
+.. index:: CONFIGURE_MAXIMUM_PERIODS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_PERIODS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic
+API Periods that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_PARTITIONS ===
+
+Specify Maximum Classic API Partitions
+--------------------------------------
+.. index:: CONFIGURE_MAXIMUM_PARTITIONS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_PARTITIONS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic
+API Partitions that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_REGIONS ===
+
+Specify Maximum Classic API Regions
+-----------------------------------
+.. index:: CONFIGURE_MAXIMUM_REGIONS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_REGIONS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic
+API Regions that can be concurrently active.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_PORTS ===
+
+Specify Maximum Classic API Ports
+---------------------------------
+.. index:: CONFIGURE_MAXIMUM_PORTS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_PORTS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic
+API Ports that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_USER_EXTENSIONS ===
+
+Specify Maximum Classic API User Extensions
+-------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_USER_EXTENSIONS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic
+API User Extensions that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === Classic API Initialization Task Configuration ===
+
+Classic API Initialization Tasks Table Configuration
+====================================================
+
+The ``<rtems/confdefs.h>`` configuration system can automatically
+generate an Initialization Tasks Table named``Initialization_tasks`` with a single entry.  The following
+parameters control the generation of that table.
+
+.. COMMENT: === CONFIGURE_RTEMS_INIT_TASKS_TABLE ===
+
+Instantiate Classic API Initialization Task Table
+-------------------------------------------------
+.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes
+to use a Classic RTEMS API Initialization Task Table. The table built by``<rtems/confdefs.h>`` specifies the parameters for a single task. This
+is sufficient for applications which initialization the system from a
+single task.
+
+By default, this field is not defined as the user MUST select their own
+API for initialization tasks.
+
+**NOTES:**
+
+The application may choose to use the initialization tasks or threads
+table from another API.
+
+A compile time error will be generated if the user does not configure
+any initialization tasks or threads.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_ENTRY_POINT ===
+
+Specifying Classic API Initialization Task Entry Point
+------------------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_ENTRY_POINT``
+
+*DATA TYPE:*
+    Task entry function pointer (``rtems_task_entry``).
+
+*RANGE:*
+    Valid task entry function pointer.
+
+*DEFAULT VALUE:*
+    The default value is ``Init``.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function
+name) of the single initialization task defined by the Classic API
+Initialization Tasks Table.
+
+**NOTES:**
+
+The user must implement the function ``Init`` or the function name provided
+in this configuration parameter.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_NAME ===
+
+Specifying Classic API Initialization Task Name
+-----------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_NAME
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_NAME``
+
+*DATA TYPE:*
+    RTEMS Name (``rtems_name``).
+
+*RANGE:*
+    Any value.
+
+*DEFAULT VALUE:*
+    The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization
+task defined by the Classic API Initialization Tasks Table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_STACK_SIZE ===
+
+Specifying Classic API Initialization Task Stack Size
+-----------------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_STACK_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is RTEMS_MINIMUM_STACK_SIZE.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single
+initialization task defined by the Classic API Initialization Tasks Table.
+
+**NOTES:**
+
+If the stack size specified is greater than the configured minimum,
+it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
+See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_PRIORITY ===
+
+Specifying Classic API Initialization Task Priority
+---------------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_PRIORITY
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_PRIORITY``
+
+*DATA TYPE:*
+    RTEMS Task Priority (``rtems_task_priority``).
+
+*RANGE:*
+    One (1) to CONFIGURE_MAXIMUM_PRIORITY.
+
+*DEFAULT VALUE:*
+    The default value is 1, which is the highest priority in the
+    Classic API.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single
+initialization task defined by the Classic API Initialization Tasks Table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_ATTRIBUTES ===
+
+Specifying Classic API Initialization Task Attributes
+-----------------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_ATTRIBUTES``
+
+*DATA TYPE:*
+    RTEMS Attributes (``rtems_attribute``).
+
+*RANGE:*
+    Valid task attribute sets.
+
+*DEFAULT VALUE:*
+    The default value is ``RTEMS_DEFAULT_ATTRIBUTES``.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single
+initialization task defined by the Classic API Initialization Tasks Table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_INITIAL_MODES ===
+
+Specifying Classic API Initialization Task Modes
+------------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_INITIAL_MODES``
+
+*DATA TYPE:*
+    RTEMS Mode (``rtems_mode``).
+
+*RANGE:*
+    Valid task mode sets.
+
+*DEFAULT VALUE:*
+    The default value is ``RTEMS_NO_PREEMPT``.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of
+the single initialization task defined by the Classic API Initialization
+Tasks Table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_INIT_TASK_ARGUMENTS ===
+
+Specifying Classic API Initialization Task Arguments
+----------------------------------------------------
+.. index:: CONFIGURE_INIT_TASK_ARGUMENTS
+
+*CONSTANT:*
+    ``CONFIGURE_INIT_TASK_ARGUMENTS``
+
+*DATA TYPE:*
+    RTEMS Task Argument (``rtems_task_argument``).
+
+*RANGE:*
+    Complete range of the type.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single
+initialization task defined by the Classic API Initialization Tasks Table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_HAS_OWN_INIT_TASK_TABLE ===
+
+Not Using Generated Initialization Tasks Table
+----------------------------------------------
+.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes
+to define their own Classic API Initialization Tasks Table.  This table
+should be named ``Initialization_tasks``.
+
+**NOTES:**
+
+This is a seldom used configuration parameter. The most likely use case
+is when an application desires to have more than one initialization task.
+
+.. COMMENT: === POSIX API Configuration ===
+
+POSIX API Configuration
+=======================
+
+The parameters in this section are used to configure resources
+for the RTEMS POSIX API.  They are only relevant if the POSIX API
+is enabled at configure time using the ``--enable-posix`` option.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_THREADS ===
+
+Specify Maximum POSIX API Threads
+---------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_THREADS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API
+Threads that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+This calculations for the required memory in the RTEMS Workspace
+for threads assume that each thread has a minimum stack size and
+has floating point support enabled.  The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack
+requirements *ABOVE* the minimum size required.
+See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
+
+The maximum number of Classic API Tasks is specified by``CONFIGURE_MAXIMUM_TASKS``.
+
+All POSIX threads have floating point enabled.
+
+.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_TASKS.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MUTEXES ===
+
+Specify Maximum POSIX API Mutexes
+---------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_MUTEXES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` is the maximum number of POSIX
+API Mutexes that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES ===
+
+Specify Maximum POSIX API Condition Variables
+---------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` is the maximum number
+of POSIX API Condition Variables that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_KEYS ===
+
+Specify Maximum POSIX API Keys
+------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_KEYS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX
+API Keys that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: XXX - Key pairs
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_TIMERS ===
+
+Specify Maximum POSIX API Timers
+--------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_TIMERS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX
+API Timers that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS ===
+
+Specify Maximum POSIX API Queued Signals
+----------------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX
+API Queued Signals that can be concurrently active.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES ===
+
+Specify Maximum POSIX API Message Queues
+----------------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX
+API Message Queues that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: XXX - memory for buffers note
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS ===
+
+Specify Maximum POSIX API Message Queue Descriptors
+---------------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGES_QUEUES``
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` is the maximum
+number of POSIX API Message Queue Descriptors that can be concurrently
+active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` should be
+greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ===
+
+Specify Maximum POSIX API Semaphores
+------------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX
+API Semaphores that can be concurrently active.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_BARRIERS ===
+
+Specify Maximum POSIX API Barriers
+----------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_BARRIERS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` is the maximum number of POSIX
+API Barriers that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SPINLOCKS ===
+
+Specify Maximum POSIX API Spinlocks
+-----------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` is the maximum number of POSIX
+API Spinlocks that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_RWLOCKS ===
+
+Specify Maximum POSIX API Read/Write Locks
+------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_POSIX_RWLOCKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` is the maximum number of POSIX
+API Read/Write Locks that can be concurrently active.
+
+**NOTES:**
+
+This object class can be configured in unlimited allocation mode.
+
+.. COMMENT: === POSIX Initialization Threads Table Configuration ===
+
+POSIX Initialization Threads Table Configuration
+================================================
+
+The ``<rtems/confdefs.h>`` configuration system can automatically
+generate a POSIX Initialization Threads Table named``POSIX_Initialization_threads`` with a single entry.  The following
+parameters control the generation of that table.
+
+.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_TABLE ===
+
+Instantiate POSIX API Initialization Thread Table
+-------------------------------------------------
+.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE
+
+*CONSTANT:*
+    .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This field is not defined by default, as the user MUST select their own
+    API for initialization tasks.
+
+**DESCRIPTION:**
+
+``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes
+to use a POSIX API Initialization Threads Table.  The table built
+by ``<rtems/confdefs.h>`` specifies the parameters for a single
+thread. This is sufficient for applications which initialization the
+system from a
+single task.
+
+By default, this field is not defined as the user MUST select their own
+API for initialization tasks.
+
+**NOTES:**
+
+The application may choose to use the initialization tasks or threads
+table from another API.
+
+A compile time error will be generated if the user does not configure
+any initialization tasks or threads.
+
+.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT ===
+
+Specifying POSIX API Initialization Thread Entry Point
+------------------------------------------------------
+.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
+
+*CONSTANT:*
+    ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT``
+
+*DATA TYPE:*
+    POSIX thread function pointer (``void \*(*entry_point)(void \*)``).
+
+*RANGE:*
+    Undefined or a valid POSIX thread function pointer.
+
+*DEFAULT VALUE:*
+    The default value is ``POSIX_Init``.
+
+**DESCRIPTION:**
+
+``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point
+(a.k.a. function name) of the single initialization thread defined by
+the POSIX API Initialization Threads Table.
+
+**NOTES:**
+
+The user must implement the function ``POSIX_Init`` or the function name
+provided in this configuration parameter.
+
+.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE ===
+
+Specifying POSIX API Initialization Thread Stack Size
+-----------------------------------------------------
+.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 2 * RTEMS_MINIMUM_STACK_SIZE.
+
+**DESCRIPTION:**
+
+``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the
+single initialization thread defined by the POSIX API Initialization
+Threads Table.
+
+**NOTES:**
+
+If the stack size specified is greater than the configured minimum,
+it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
+See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
+
+.. COMMENT: === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE ===
+
+Not Using Generated POSIX Initialization Threads Table
+------------------------------------------------------
+.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the
+user wishes to define their own POSIX API Initialization Threads Table.
+This table should be named ``POSIX_Initialization_threads``.
+
+**NOTES:**
+
+This is a seldom used configuration parameter. The most likely use case
+is when an application desires to have more than one initialization task.
+
+.. COMMENT: === Basic System Information ===
+
+Basic System Information
+========================
+
+This section defines the general system configuration parameters supported by``<rtems/confdefs.h>``.
+
+.. COMMENT: === CONFIGURE_UNIFIED_WORK_AREAS ===
+
+.. _Configuring-a-System-Separate-or-Unified-Work-Areas:
+
+Separate or Unified Work Areas
+------------------------------
+.. index:: CONFIGURE_UNIFIED_WORK_AREAS
+.. index:: unified work areas
+.. index:: separate work areas
+.. index:: RTEMS Workspace
+.. index:: C Program Heap
+
+*CONSTANT:*
+    ``CONFIGURE_UNIFIED_WORK_AREAS``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default, which specifies that the C Program Heap
+    and the RTEMS Workspace will be separate.
+
+**DESCRIPTION:**
+
+When defined, the C Program Heap and the RTEMS Workspace will be one pool
+of memory.
+
+When not defined, there will be separate memory pools for the RTEMS
+Workspace and C Program Heap.
+
+**NOTES:**
+
+Having separate pools does have some advantages in the event a task blows
+a stack or writes outside its memory area. However, in low memory systems
+the overhead of the two pools plus the potential for unused memory in
+either pool is very undesirable.
+
+In high memory environments, this is desirable when you want to use the
+RTEMS "unlimited" objects option.  You will be able to create objects
+until you run out of all available memory rather then just until you
+run out of RTEMS Workspace.
+
+.. COMMENT: === CONFIGURE_MICROSECONDS_PER_TICK ===
+
+Length of Each Clock Tick
+-------------------------
+.. index:: CONFIGURE_MICROSECONDS_PER_TICK
+.. index:: tick quantum
+
+*CONSTANT:*
+    ``CONFIGURE_MICROSECONDS_PER_TICK``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    This is not defined by default. When not defined,
+    the clock tick quantum is configured to be 10,000
+    microseconds which is ten (10) milliseconds.
+
+**DESCRIPTION:**
+
+This constant is  used to specify the length of time between clock ticks.
+
+When the clock tick quantum value is too low, the system will spend so
+much time processing clock ticks that it does not have processing time
+available to perform application work. In this case, the system will
+become unresponsive.
+
+The lowest practical time quantum varies widely based upon the speed
+of the target hardware and the architectural overhead associated with
+interrupts. In general terms, you do not want to configure it lower than
+is needed for the application.
+
+The clock tick quantum should be selected such that it all blocking and
+delay times in the application are evenly divisible by it. Otherwise,
+rounding errors will be introduced which may negatively impact the
+application.
+
+**NOTES:**
+
+This configuration parameter has no impact if the Clock Tick Device
+driver is not configured.
+
+There may be BSP specific limits on the resolution or maximum value of
+a clock tick quantum.
+
+.. COMMENT: === CONFIGURE_TICKS_PER_TIMESLICE ===
+
+Specifying Timeslicing Quantum
+------------------------------
+.. index:: CONFIGURE_TICKS_PER_TIMESLICE
+.. index:: ticks per timeslice
+
+*CONSTANT:*
+    ``CONFIGURE_TICKS_PER_TIMESLICE``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 50.
+
+**DESCRIPTION:**
+
+This configuration parameter specifies the length of the timeslice
+quantum in ticks for each task.
+
+**NOTES:**
+
+This configuration parameter has no impact if the Clock Tick Device
+driver is not configured.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_PRIORITY ===
+
+Specifying the Number of Thread Priority Levels
+-----------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_PRIORITY
+.. index:: maximum priority
+.. index:: number of priority levels
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_PRIORITY``
+
+*DATA TYPE:*
+    Unsigned integer (``uint8_t``).
+
+*RANGE:*
+    Valid values for this configuration parameter must be one (1) less than
+    than a power of two (2) between 4 and 256 inclusively.  In other words,
+    valid values are 3, 7, 31, 63, 127, and 255.
+
+*DEFAULT VALUE:*
+    The default value is 255, because RTEMS must support 256 priority levels to be
+    compliant with various standards. These priorities range from zero (0) to 255.
+
+**DESCRIPTION:**
+
+This configuration parameter specified the maximum numeric priority
+of any task in the system and one less that the number of priority levels
+in the system.
+
+Reducing the number of priorities in the system reduces the amount of
+memory allocated from the RTEMS Workspace.
+
+**NOTES:**
+
+The numerically greatest priority is the logically lowest priority in
+the system and will thus be used by the IDLE task.
+
+Priority zero (0) is reserved for internal use by RTEMS and is not
+available to applications.
+
+With some schedulers, reducing the number of priorities can reduce the
+amount of memory used by the scheduler. For example, the Deterministic
+Priority Scheduler (DPS) used by default uses three pointers of storage
+per priority level. Reducing the number of priorities from 256 levels
+to sixteen (16) can reduce memory usage by about three (3) kilobytes.
+
+.. COMMENT: === CONFIGURE_MINIMUM_TASK_STACK_SIZE ===
+
+Specifying the Minimum Task Size
+--------------------------------
+.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE
+.. index:: minimum task stack size
+
+*CONSTANT:*
+    ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    This is not defined by default, which sets the executive to the recommended
+    minimum stack size for this processor.
+
+**DESCRIPTION:**
+
+The configuration parameter is set to the number of bytes the application
+wants the minimum stack size to be for every task or thread in the system.
+
+Adjusting this parameter should be done with caution. Examining the actual
+usage using the Stack Checker Usage Reporting facility is recommended.
+
+**NOTES:**
+
+This parameter can be used to lower the minimum from that
+recommended. This can be used in low memory systems to reduce memory
+consumption for stacks. However, this must be done with caution as it
+could increase the possibility of a blown task stack.
+
+This parameter can be used to increase the minimum from that
+recommended. This can be used in higher memory systems to reduce the
+risk of stack overflow without performing analysis on actual consumption.
+
+.. COMMENT: === CONFIGURE_INTERRUPT_STACK_SIZE ===
+
+Configuring the Size of the Interrupt Stack
+-------------------------------------------
+.. index:: CONFIGURE_INTERRUPT_STACK_SIZE
+.. index:: interrupt stack size
+
+*CONSTANT:*
+    ``CONFIGURE_INTERRUPT_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is CONFIGURE_MINIMUM_TASK_STACK_SIZE, which is the minimum
+    interrupt stack size.
+
+**DESCRIPTION:**
+
+``CONFIGURE_INTERRUPT_STACK_SIZE`` is set to the size of the
+interrupt stack.  The interrupt stack size is often set by the BSP but
+since this memory may be allocated from the RTEMS Workspace, it must be
+accounted for.
+
+**NOTES:**
+
+In some BSPs, changing this constant does NOT change the
+size of the interrupt stack, only the amount of memory
+reserved for it.
+
+Patches which result in this constant only being used in memory
+calculations when the interrupt stack is intended to be allocated
+from the RTEMS Workspace would be welcomed by the RTEMS Project.
+
+.. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS ===
+
+.. _Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum:
+
+Reserve Task/Thread Stack Memory Above Minimum
+----------------------------------------------
+.. index:: CONFIGURE_EXTRA_TASK_STACKS
+.. index:: memory for task tasks
+
+*CONSTANT:*
+    ``CONFIGURE_EXTRA_TASK_STACKS``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+This configuration parameter is set to the number of bytes the
+applications wishes to add to the task stack requirements calculated
+by ``<rtems/confdefs.h>``.
+
+**NOTES:**
+
+This parameter is very important.  If the application creates tasks with
+stacks larger then the minimum, then that memory is NOT accounted for
+by ``<rtems/confdefs.h>``.
+
+.. COMMENT: === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY ===
+
+Automatically Zeroing the RTEMS Workspace and C Program Heap
+------------------------------------------------------------
+.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
+.. index:: clear C Program Heap
+.. index:: clear RTEMS Workspace
+.. index:: zero C Program Heap
+.. index:: zero RTEMS Workspace
+
+*CONSTANT:*
+    ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default, unless overridden by the BSP.
+    The default is *NOT* to zero out the RTEMS Workspace or C Program Heap.
+
+**DESCRIPTION:**
+
+This macro indicates whether RTEMS should zero the RTEMS Workspace and
+C Program Heap as part of its initialization.  If defined, the memory
+regions are zeroed.  Otherwise, they are not.
+
+**NOTES:**
+
+Zeroing memory can add significantly to system boot time. It is not
+necessary for RTEMS but is often assumed by support libraries.
+
+.. COMMENT: === CONFIGURE_STACK_CHECKER_ENABLED ===
+
+Enable The Task Stack Usage Checker
+-----------------------------------
+.. index:: CONFIGURE_STACK_CHECKER_ENABLED
+
+*CONSTANT:*
+    ``CONFIGURE_STACK_CHECKER_ENABLED``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default, and thus stack checking is disabled.
+
+**DESCRIPTION:**
+
+This configuration parameter is defined when the application wishes to
+enable run-time stack bounds checking.
+
+**NOTES:**
+
+In 4.9 and older, this configuration parameter was named``STACK_CHECKER_ON``.
+
+This increases the time required to create tasks as well as adding
+overhead to each context switch.
+
+.. COMMENT: === CONFIGURE_INITIAL_EXTENSIONS ===
+
+Specify Application Specific User Extensions
+--------------------------------------------
+.. index:: CONFIGURE_INITIAL_EXTENSIONS
+
+*CONSTANT:*
+    ``CONFIGURE_INITIAL_EXTENSIONS``
+
+*DATA TYPE:*
+    List of user extension initializers (``rtems_extensions_table``).
+
+*RANGE:*
+    Undefined or a list of one or more user extensions.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application,
+then this application specific set of initial extensions will be placed
+in the initial extension table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === Custom Stack Allocator ===
+
+Configuring Custom Task Stack Allocation
+========================================
+
+RTEMS allows the application or BSP to define its own allocation and
+deallocation methods for task stacks. This can be used to place task
+stacks in special areas of memory or to utilize a Memory Management Unit
+so that stack overflows are detected in hardware.
+
+.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR_INIT ===
+
+Custom Task Stack Allocator Initialization
+------------------------------------------
+.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT
+
+*CONSTANT:*
+    ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+
+*DATA TYPE:*
+    Function pointer.
+
+*RANGE:*
+    Undefined, NULL or valid function pointer.
+
+*DEFAULT VALUE:*
+    The default value is NULL, which indicates that
+    task stacks will be allocated from the RTEMS Workspace.
+
+**DESCRIPTION:**
+
+``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization
+method for an application or BSP specific task stack allocation
+implementation.
+
+**NOTES:**
+
+A correctly configured system must configure the following to be consistent:
+
+- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+
+- ``CONFIGURE_TASK_STACK_ALLOCATOR``
+
+- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+
+.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR ===
+
+Custom Task Stack Allocator
+---------------------------
+.. index:: CONFIGURE_TASK_STACK_ALLOCATOR
+
+.. index:: task stack allocator
+
+*CONSTANT:*
+    ``CONFIGURE_TASK_STACK_ALLOCATOR``
+
+*DATA TYPE:*
+    Function pointer.
+
+*RANGE:*
+    Undefined or valid function pointer.
+
+*DEFAULT VALUE:*
+    The default value is ``_Workspace_Allocate``, which indicates
+    that task stacks will be allocated from the RTEMS Workspace.
+
+**DESCRIPTION:**
+
+``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided
+routine to allocate task stacks.
+
+**NOTES:**
+
+A correctly configured system must configure the following to be consistent:
+
+- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+
+- ``CONFIGURE_TASK_STACK_ALLOCATOR``
+
+- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+
+.. COMMENT: === CONFIGURE_TASK_STACK_DEALLOCATOR ===
+
+Custom Task Stack Deallocator
+-----------------------------
+.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR
+.. index:: task stack deallocator
+
+*CONSTANT:*
+    ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+
+*DATA TYPE:*
+    Function pointer.
+
+*RANGE:*
+    Undefined or valid function pointer.
+
+*DEFAULT VALUE:*
+    The default value is ``_Workspace_Free``, which indicates that
+    task stacks will be allocated from the RTEMS Workspace.
+
+**DESCRIPTION:**
+
+``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided
+routine to free task stacks.
+
+**NOTES:**
+
+A correctly configured system must configure the following to be consistent:
+
+- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+
+- ``CONFIGURE_TASK_STACK_ALLOCATOR``
+
+- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+
+.. COMMENT: === Classic API Message Buffers ===
+
+Configuring Memory for Classic API Message Buffers
+==================================================
+
+This section describes the configuration parameters related to specifying
+the amount of memory reserved for Classic API Message Buffers.
+
+.. COMMENT: === CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE ===
+
+Calculate Memory for a Single Classic Message API Message Queue
+---------------------------------------------------------------
+.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE
+.. index:: memory for a single message queueâs buffers
+
+*CONSTANT:*
+    ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is None.
+
+**DESCRIPTION:**
+
+This is a helper macro which is used to assist in computing the total
+amount of memory required for message buffers.  Each message queue will
+have its own configuration with maximum message size and maximum number
+of pending messages.
+
+The interface for this macro is as follows:
+.. code:: c
+
+    CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)
+
+Where ``max_messages`` is the maximum number of pending messages
+and ``size_per`` is the size in bytes of the user message.
+
+**NOTES:**
+
+This macro is only used in support of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``.
+
+.. COMMENT: === CONFIGURE_MESSAGE_BUFFER_MEMORY ===
+
+Reserve Memory for All Classic Message API Message Queues
+---------------------------------------------------------
+.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY
+.. index:: configure message queue buffer memory
+
+*CONSTANT:*
+    ``CONFIGURE_MESSAGE_BUFFER_MEMORY``
+
+*DATA TYPE:*
+    integer summation macro
+
+*RANGE:*
+    undefined (zero) or calculation resulting in a positive integer
+
+*DEFAULT VALUE:*
+    This is not defined by default, and zero (0) memory is reserved.
+
+**DESCRIPTION:**
+
+This macro is set to the number of bytes the application requires to be
+reserved for pending Classic API Message Queue buffers.
+
+**NOTES:**
+
+The following illustrates how the help macro``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE`` can be used to assist in
+calculating the message buffer memory required.  In this example, there
+are two message queues used in this application.  The first message
+queue has maximum of 24 pending messages with the message structure
+defined by the type ``one_message_type``.  The other message queue
+has maximum of 500 pending messages with the message structure defined
+by the type ``other_message_type``.
+.. code:: c
+
+    #define CONFIGURE_MESSAGE_BUFFER_MEMORY \\
+    (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \\
+    24, sizeof(one_message_type) + \\
+    CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \\
+    500, sizeof(other_message_type) \\
+    )
+
+.. COMMENT: === Seldom Used Configuration Parameters ===
+
+Seldom Used Configuration Parameters
+====================================
+
+This section describes configuration parameters supported by``<rtems/confdefs.h>`` which are seldom used by applications. These
+parameters tend to be oriented to debugging system configurations
+and providing work-arounds when the memory estimated by``<rtems/confdefs.h>`` is incorrect.
+
+.. COMMENT: === CONFIGURE_MEMORY_OVERHEAD ===
+
+.. _Configuring-a-System-Specify-Memory-Overhead:
+
+Specify Memory Overhead
+-----------------------
+.. index:: CONFIGURE_MEMORY_OVERHEAD
+
+*CONSTANT:*
+    ``CONFIGURE_MEMORY_OVERHEAD``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+Thie parameter is set to the number of kilobytes the application wishes
+to add to the requirements calculated by ``<rtems/confdefs.h>``.
+
+**NOTES:**
+
+This configuration parameter should only be used when it is suspected that
+a bug in ``<rtems/confdefs.h>`` has resulted in an underestimation.
+Typically the memory allocation will be too low when an application does
+not account for all message queue buffers or task stacks.
+
+.. COMMENT: === CONFIGURE_HAS_OWN_CONFIGURATION_TABLE ===
+
+Do Not Generate Configuration Information
+-----------------------------------------
+.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_HAS_OWN_CONFIGURATION_TABLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+This configuration parameter should only be defined if the application
+is providing their own complete set of configuration tables.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === C Library Support Configuration ===
+
+C Library Support Configuration
+===============================
+
+This section defines the file system and IO library
+related configuration parameters supported by``<rtems/confdefs.h>``.
+
+.. COMMENT: === CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS ===
+
+Specify Maximum Number of File Descriptors
+------------------------------------------
+.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS
+.. index:: maximum file descriptors
+
+*CONSTANT:*
+    ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    If ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined, then the
+    default value is 3, otherwise the default value is 0.
+    Three file descriptors allows RTEMS to support standard input, output, and
+    error I/O streams on ``/dev/console``.
+
+**DESCRIPTION:**
+
+This configuration parameter is set to the maximum number of file like objects
+that can be concurrently open.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_TERMIOS_DISABLED ===
+
+Disable POSIX Termios Support
+-----------------------------
+.. index:: CONFIGURE_TERMIOS_DISABLED
+
+*CONSTANT:*
+    ``CONFIGURE_TERMIOS_DISABLED``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default, and resources are reserved for the
+    termios functionality.
+
+**DESCRIPTION:**
+
+This configuration parameter is defined if the software implementing
+POSIX termios functionality is not going to be used by this application.
+
+**NOTES:**
+
+The termios support library should not be included in an application
+executable unless it is directly referenced by the application or a
+device driver.
+
+.. COMMENT: === CONFIGURE_NUMBER_OF_TERMIOS_PORTS ===
+
+Specify Maximum Termios Ports
+-----------------------------
+.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS
+
+*CONSTANT:*
+    ``CONFIGURE_NUMBER_OF_TERMIOS_PORTS``
+
+*DATA TYPE:*
+    Unsigned integer.
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 1, so a console port can be used.
+
+**DESCRIPTION:**
+
+This configuration parameter is set to the number of ports using the
+termios functionality.  Each concurrently active termios port requires
+resources.
+
+**NOTES:**
+
+If the application will be using serial ports
+including, but not limited to, the Console Device
+(e.g. ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``), then it is
+highly likely that this configuration parameter should NOT be is defined.
+
+.. COMMENT: === File System Configuration Parameters ===
+
+File System Configuration Parameters
+====================================
+
+This section defines File System related configuration parameters.
+
+.. COMMENT: === CONFIGURE_HAS_OWN_MOUNT_TABLE ===
+
+Providing Application Specific Mount Table
+------------------------------------------
+.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_HAS_OWN_MOUNT_TABLE``
+
+*DATA TYPE:*
+    Undefined or an array of type ``rtems_filesystem_mount_table_t``.
+
+*RANGE:*
+    Undefined or an array of type ``rtems_filesystem_mount_table_t``.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+This configuration parameter is defined when the application
+provides their own filesystem mount table.  The mount table is an
+array of ``rtems_filesystem_mount_table_t`` entries pointed
+to by the global variable ``rtems_filesystem_mount_table``.
+The number of entries in this table is in an integer variable named``rtems_filesystem_mount_table_t``.
+
+.. COMMENT: XXX - is the variable name for the count right?
+
+**NOTES:**
+
+None.
+
+.. COMMENT: XXX - Please provide an example
+
+.. COMMENT: === CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM ===
+
+Configure devFS as Root File System
+-----------------------------------
+.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
+
+*CONSTANT:*
+    ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default. If no other root file system
+    configuration parameters are specified, the IMFS will be used as the
+    root file system.
+
+**DESCRIPTION:**
+
+This configuration parameter is defined if the application wishes to
+use the device-only filesytem as the root file system.
+
+**NOTES:**
+
+The device-only filesystem supports only device nodes and is smaller in
+executable code size than the full IMFS and miniIMFS.
+
+The devFS is comparable in functionality to the pseudo-filesystem name
+space provided before RTEMS release 4.5.0.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_DEVICES ===
+
+Specifying Maximum Devices for devFS
+------------------------------------
+.. index:: CONFIGURE_MAXIMUM_DEVICES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_DEVICES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    If ``BSP_MAXIMUM_DEVICES`` is defined, then the
+    default value is ``BSP_MAXIMUM_DEVICES``, otherwise the default value is 4.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_DEVICES`` is defined to the number of
+individual devices that may be registered in the device file system (devFS).
+
+**NOTES:**
+
+This option is specific to the device file system (devFS) and should not be
+confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option.  This parameter only
+impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified.
+
+.. COMMENT: === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM ===
+
+Disable File System Support
+---------------------------
+.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default. If no other root file system
+    configuration parameters are specified, the IMFS will be used as the
+    root file system.
+
+**DESCRIPTION:**
+
+This configuration parameter is defined if the application dose not
+intend to use any kind of filesystem support. This include the device
+infrastructure necessary to support ``printf()``.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM ===
+
+Use a Root IMFS with a Minimalistic Feature Set
+-----------------------------------------------
+.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM
+
+*CONSTANT:*
+    ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the following configuration
+options will be defined as well
+
+- ``CONFIGURE_IMFS_DISABLE_CHMOD``,
+
+- ``CONFIGURE_IMFS_DISABLE_CHOWN``,
+
+- ``CONFIGURE_IMFS_DISABLE_UTIME``,
+
+- ``CONFIGURE_IMFS_DISABLE_LINK``,
+
+- ``CONFIGURE_IMFS_DISABLE_SYMLINK``,
+
+- ``CONFIGURE_IMFS_DISABLE_READLINK``,
+
+- ``CONFIGURE_IMFS_DISABLE_RENAME``, and
+
+- ``CONFIGURE_IMFS_DISABLE_UNMOUNT``.
+
+.. COMMENT: === CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK ===
+
+Specify Block Size for IMFS
+---------------------------
+.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Valid values for this configuration parameter are a power of two (2)
+    between 16 and 512 inclusive.  In other words, valid values are 16,
+    32, 64, 128, 256,and 512.
+
+*DEFAULT VALUE:*
+    The default IMFS block size is 128 bytes.
+
+**DESCRIPTION:**
+
+This configuration parameter specifies the block size for in-memory files
+managed by the IMFS. The configured block size has two impacts. The first
+is the average amount of unused memory in the last block of each file. For
+example, when the block size is 512, on average one-half of the last block
+of each file will remain unused and the memory is wasted. In contrast,
+when the block size is 16, the average unused memory per file is only
+8 bytes. However, it requires more allocations for the same size file
+and thus more overhead per block for the dynamic memory management.
+
+Second, the block size has an impact on the maximum size file that can
+be stored in the IMFS. With smaller block size, the maximum file size
+is correspondingly smaller. The following shows the maximum file size
+possible based on the configured block size:
+
+- when the block size is 16 bytes, the maximum file size is 1,328
+  bytes.
+
+- when the block size is 32 bytes, the maximum file size is 18,656
+  bytes.
+
+- when the block size is 64 bytes, the maximum file size is 279,488
+  bytes.
+
+- when the block size is 128 bytes, the maximum file size is
+  4,329,344 bytes.
+
+- when the block size is 256 bytes, the maximum file size is
+  68,173,568 bytes.
+
+- when the block size is 512 bytes, the maximum file size is
+  1,082,195,456 bytes.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHOWN ===
+
+Disable Change Owner Support of Root IMFS
+-----------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_CHOWN
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_CHOWN``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to change the
+owner is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHMOD ===
+
+Disable Change Mode Support of Root IMFS
+----------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_CHMOD
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_CHMOD``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to change the
+mode is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_UTIME ===
+
+Disable Change Times Support of Root IMFS
+-----------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_UTIME
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_UTIME``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to change times
+is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_LINK ===
+
+Disable Create Hard Link Support of Root IMFS
+---------------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_LINK
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_LINK``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to create hard
+links is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_SYMLINK ===
+
+Disable Create Symbolic Link Support of Root IMFS
+-------------------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_SYMLINK``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to create
+symbolic links is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_READLINK ===
+
+Disable Read Symbolic Link Support of Root IMFS
+-----------------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_READLINK
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_READLINK``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to read symbolic
+links is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_RENAME ===
+
+Disable Rename Support of Root IMFS
+-----------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_RENAME
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_RENAME``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to rename nodes
+is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_READDIR ===
+
+Disable Directory Read Support of Root IMFS
+-------------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_READDIR
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_READDIR``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to read a
+directory is disabled in the root IMFS.  It is still possible to open nodes in
+a directory.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_MOUNT ===
+
+Disable Mount Support of Root IMFS
+----------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_MOUNT
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_MOUNT``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to mount other
+file systems is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_UNMOUNT ===
+
+Disable Unmount Support of Root IMFS
+------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_UNMOUNT``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to unmount file
+systems is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD ===
+
+Disable Make Nodes Support of Root IMFS
+---------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_MKNOD
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_MKNOD``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to make
+directories, devices, regular files and FIFOs is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD_FILE ===
+
+Disable Make Files Support of Root IMFS
+---------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to make regular
+files is disabled in the root IMFS.
+
+.. COMMENT: === CONFIGURE_IMFS_DISABLE_RMNOD ===
+
+Disable Remove Nodes Support of Root IMFS
+-----------------------------------------
+.. index:: CONFIGURE_IMFS_DISABLE_RMNOD
+
+*CONSTANT:*
+    ``CONFIGURE_IMFS_DISABLE_RMNOD``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+In case this configuration option is defined, then the support to remove nodes
+is disabled in the root IMFS.
+
+.. COMMENT: === Block Device Cache Configuration ===
+
+Block Device Cache Configuration
+================================
+
+This section defines Block Device Cache (bdbuf) related configuration
+parameters.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ===
+
+Enable Block Device Cache
+-------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+Provides a Block Device Cache configuration.
+
+**NOTES:**
+
+Each option of the Block Device Cache configuration can be explicitly set by
+the user with the configuration options below.  The Block Device Cache is used
+for example by the RFS and DOSFS file systems.
+
+.. COMMENT: === CONFIGURE_BDBUF_CACHE_MEMORY_SIZE ===
+
+Size of the Cache Memory
+------------------------
+.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 32768 bytes.
+
+**DESCRIPTION:**
+
+Size of the cache memory in bytes.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MIN_SIZE ===
+
+Minimum Size of a Buffer
+------------------------
+.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 512 bytes.
+
+**DESCRIPTION:**
+
+Defines the minimum size of a buffer in bytes.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MAX_SIZE ===
+
+Maximum Size of a Buffer
+------------------------
+.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    It must be positive and an integral multiple of the buffer minimum size.
+
+*DEFAULT VALUE:*
+    The default value is 4096 bytes.
+
+**DESCRIPTION:**
+
+Defines the maximum size of a buffer in bytes.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SWAPOUT_SWAP_PERIOD ===
+
+Swapout Task Swap Period
+------------------------
+.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD
+
+*CONSTANT:*
+    ``CONFIGURE_SWAPOUT_SWAP_PERIOD``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 250 milliseconds.
+
+**DESCRIPTION:**
+
+Defines the swapout task swap period in milliseconds.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SWAPOUT_BLOCK_HOLD ===
+
+Swapout Task Maximum Block Hold Time
+------------------------------------
+.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD
+
+*CONSTANT:*
+    ``CONFIGURE_SWAPOUT_BLOCK_HOLD``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 1000 milliseconds.
+
+**DESCRIPTION:**
+
+Defines the swapout task maximum block hold time in milliseconds.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SWAPOUT_TASK_PRIORITY ===
+
+Swapout Task Priority
+---------------------
+.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY
+
+*CONSTANT:*
+    ``CONFIGURE_SWAPOUT_TASK_PRIORITY``
+
+*DATA TYPE:*
+    Task priority (``rtems_task_priority``).
+
+*RANGE:*
+    Valid task priority.
+
+*DEFAULT VALUE:*
+    The default value is 15.
+
+**DESCRIPTION:**
+
+Defines the swapout task priority.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS ===
+
+Maximum Blocks per Read-Ahead Request
+-------------------------------------
+.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+Defines the maximum blocks per read-ahead request.
+
+**NOTES:**
+
+A value of 0 disables the read-ahead task (default).  The read-ahead task will
+issue speculative read transfers if a sequential access pattern is detected.
+This can improve the performance on some systems.
+
+.. COMMENT: === CONFIGURE_BDBUF_MAX_WRITE_BLOCKS ===
+
+Maximum Blocks per Write Request
+--------------------------------
+.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 16.
+
+**DESCRIPTION:**
+
+Defines the maximum blocks per write request.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_BDBUF_TASK_STACK_SIZE ===
+
+Task Stack Size of the Block Device Cache Tasks
+-----------------------------------------------
+.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_TASK_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is RTEMS_MINIMUM_STACK_SIZE.
+
+**DESCRIPTION:**
+
+Defines the task stack size of the Block Device Cache tasks in bytes.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ===
+
+Read-Ahead Task Priority
+------------------------
+.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY
+
+*CONSTANT:*
+    ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY``
+
+*DATA TYPE:*
+    Task priority (``rtems_task_priority``).
+
+*RANGE:*
+    Valid task priority.
+
+*DEFAULT VALUE:*
+    The default value is 15.
+
+**DESCRIPTION:**
+
+Defines the read-ahead task priority.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASKS ===
+
+Swapout Worker Task Count
+-------------------------
+.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS
+
+*CONSTANT:*
+    ``CONFIGURE_SWAPOUT_WORKER_TASKS``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+Defines the swapout worker task count.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY ===
+
+Swapout Worker Task Priority
+----------------------------
+.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY
+
+*CONSTANT:*
+    ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY``
+
+*DATA TYPE:*
+    Task priority (``rtems_task_priority``).
+
+*RANGE:*
+    Valid task priority.
+
+*DEFAULT VALUE:*
+    The default value is 15.
+
+**DESCRIPTION:**
+
+Defines the swapout worker task priority.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === BSP Specific Settings ===
+
+BSP Specific Settings
+=====================
+
+This section describes BSP specific configuration settings used by``<rtems/confdefs.h>``.  The BSP specific configuration settings are
+defined in ``<bsp.h>``.
+
+.. COMMENT: === Disable BSP Settings ===
+
+Disable BSP Configuration Settings
+----------------------------------
+.. index:: CONFIGURE_DISABLE_BSP_SETTINGS
+
+*CONSTANT:*
+    ``CONFIGURE_DISABLE_BSP_SETTINGS``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+All BSP specific configuration settings can be disabled by the application
+with the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK ===
+
+Specify BSP Supports sbrk()
+---------------------------
+.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+
+*CONSTANT:*
+    ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+This configuration parameter is defined by a BSP to indicate that it
+does not allocate all available memory to the C Program Heap used by
+the Malloc Family of routines.
+
+If defined, when ``malloc()`` is unable to allocate memory, it will
+call the BSP supplied ``sbrk()`` to obtain more memory.
+
+**NOTES:**
+
+This parameter should not be defined by the application. Only the BSP
+knows how it allocates memory to the C Program Heap.
+
+.. COMMENT: === BSP_IDLE_TASK_BODY ===
+
+Specify BSP Specific Idle Task
+------------------------------
+.. index:: BSP_IDLE_TASK_BODY
+
+*CONSTANT:*
+    ``BSP_IDLE_TASK_BODY``
+
+*DATA TYPE:*
+    Function pointer.
+
+*RANGE:*
+    Undefined or valid function pointer.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application,
+then this BSP specific idle task body will be used.
+
+**NOTES:**
+
+As it has knowledge of the specific CPU model, system controller logic,
+and peripheral buses, a BSP specific IDLE task may be capable of turning
+components off to save power during extended periods of no task activity
+
+.. COMMENT: === BSP_IDLE_TASK_STACK_SIZE ===
+
+Specify BSP Suggested Value for IDLE Task Stack Size
+----------------------------------------------------
+.. index:: BSP_IDLE_TASK_STACK_SIZE
+
+*CONSTANT:*
+    ``BSP_IDLE_TASK_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application,
+then this BSP suggested idle task stack size will be used.
+
+**NOTES:**
+
+The order of precedence for configuring the IDLE task stack size is:
+
+- RTEMS default minimum stack size.
+
+- If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``.
+
+- If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``.
+
+- If defined, then the application specified``CONFIGURE_IDLE_TASK_SIZE``.
+
+.. COMMENT: XXX - add cross references to other related values.
+
+.. COMMENT: === BSP_INITIAL_EXTENSION ===
+
+Specify BSP Specific User Extensions
+------------------------------------
+.. index:: BSP_INITIAL_EXTENSION
+
+*CONSTANT:*
+    ``BSP_INITIAL_EXTENSION``
+
+*DATA TYPE:*
+    List of user extension initializers (``rtems_extensions_table``).
+
+*RANGE:*
+    Undefined or a list of user extension initializers.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP
+specific initial extension will be placed as the last entry in the initial
+extension table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === BSP_INTERRUPT_STACK_SIZE ===
+
+Specifying BSP Specific Interrupt Stack Size
+--------------------------------------------
+.. index:: BSP_INTERRUPT_STACK_SIZE
+
+*CONSTANT:*
+    ``BSP_INTERRUPT_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application,
+then this BSP specific interrupt stack size will be used.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === BSP_MAXIMUM_DEVICES ===
+
+Specifying BSP Specific Maximum Devices
+---------------------------------------
+.. index:: BSP_MAXIMUM_DEVICES
+
+*CONSTANT:*
+    ``BSP_MAXIMUM_DEVICES``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application,
+then this BSP specific maximum device count will be used.
+
+**NOTES:**
+
+This option is specific to the device file system (devFS) and should not be
+confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option.  This parameter only
+impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified.
+
+.. COMMENT: === BSP_ZERO_WORKSPACE_AUTOMATICALLY ===
+
+BSP Recommends RTEMS Workspace be Cleared
+-----------------------------------------
+.. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY
+
+*CONSTANT:*
+    ``BSP_ZERO_WORKSPACE_AUTOMATICALLY``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+If ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined by the BSP and``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` is not defined by the
+application, then the workspace will be zeroed automatically.
+
+**NOTES:**
+
+Zeroing memory can add significantly to system boot time. It is not
+necessary for RTEMS but is often assumed by support libraries.
+
+.. COMMENT: === CONFIGURE_BSP_PREREQUISITE_DRIVERS ===
+
+Specify BSP Prerequisite Drivers
+--------------------------------
+.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS
+
+*CONSTANT:*
+    ``CONFIGURE_BSP_PREREQUISITE_DRIVERS``
+
+*DATA TYPE:*
+    List of device driver initializers (``rtems_driver_address_table``).
+
+*RANGE:*
+    Undefined or array of device drivers.
+
+*DEFAULT VALUE:*
+    This option is BSP specific.
+
+**DESCRIPTION:**
+
+``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device
+drivers it needs to include in the Device Driver Table.  This should be
+defined to the set of device driver entries that will be placed in the
+table at the *FRONT* of the Device Driver Table and initialized before
+any other drivers *INCLUDING* any application prerequisite drivers.
+
+**NOTES:**
+
+``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs
+to configure common infrastructure such as bus controllers or probe
+for devices.
+
+.. COMMENT: === Idle Task Configuration ===
+
+Idle Task Configuration
+=======================
+
+This section defines the IDLE task related configuration parameters
+supported by ``<rtems/confdefs.h>``.
+
+.. COMMENT: === CONFIGURE_IDLE_TASK_BODY ===
+
+Specify Application Specific Idle Task Body
+-------------------------------------------
+.. index:: CONFIGURE_IDLE_TASK_BODY
+
+*CONSTANT:*
+    ``CONFIGURE_IDLE_TASK_BODY``
+
+*DATA TYPE:*
+    Function pointer.
+
+*RANGE:*
+    Undefined or valid function pointer.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding
+to the application specific IDLE thread body.  If not specified, the
+BSP or RTEMS default IDLE thread body will be used.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_IDLE_TASK_STACK_SIZE ===
+
+Specify Idle Task Stack Size
+----------------------------
+.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE
+
+*CONSTANT:*
+    ``CONFIGURE_IDLE_TASK_STACK_SIZE``
+
+*DATA TYPE:*
+    Unsigned integer (``size_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    The default value is RTEMS_MINIMUM_STACK_SIZE.
+
+**DESCRIPTION:**
+
+``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the
+desired stack size for the IDLE task.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION ===
+
+Specify Idle Task Performs Application Initialization
+-----------------------------------------------------
+.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
+
+*CONSTANT:*
+    ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default, the user is assumed
+    to provide one or more initialization tasks.
+
+**DESCRIPTION:**
+
+``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set to
+indicate that the user has configured *NO* user initialization tasks
+or threads and that the user provided IDLE task will perform application
+initialization and then transform itself into an IDLE task.
+
+**NOTES:**
+
+If you use this option be careful, the user IDLE task *CANNOT* block
+at all during the initialization sequence.  Further, once application
+initialization is complete, it must make itself preemptible and enter
+an IDLE body loop.
+
+The IDLE task must run at the lowest priority of all tasks in the system.
+
+.. COMMENT: === Scheduler Algorithm Configuration ===
+
+Scheduler Algorithm Configuration
+=================================
+
+This section defines the configuration parameters related to selecting a
+scheduling algorithm for an application.  For the schedulers built into
+RTEMS, the configuration is straightforward.  All that is required is
+to define the configuration macro which specifies which scheduler you
+want for in your application.  The currently available schedulers are:
+
+The pluggable scheduler interface also enables the user to provide their
+own scheduling algorithm.  If you choose to do this, you must define
+multiple configuration macros.
+
+.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY ===
+
+Use Deterministic Priority Scheduler
+------------------------------------
+.. index:: CONFIGURE_SCHEDULER_PRIORITY
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_PRIORITY``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is defined by default.
+    This is the default scheduler and specifying this
+    configuration parameter is redundant.
+
+**DESCRIPTION:**
+
+The Deterministic Priority Scheduler is the default scheduler in RTEMS
+for uni-processor applications and is designed for predictable performance
+under the highest loads.  It can block or unblock a thread in a constant
+amount of time.  This scheduler requires a variable amount of memory
+based upon the number of priorities configured in the system.
+
+**NOTES:**
+
+This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_PRIORITY`` although this is equivalent to the
+default behavior.
+
+.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE ===
+
+Use Simple Priority Scheduler
+-----------------------------
+.. index:: CONFIGURE_SCHEDULER_SIMPLE
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_SIMPLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+When defined, the Simple Priority Scheduler is used at the thread
+scheduling algorithm. This is an alternative scheduler in RTEMS.
+It is designed to provide the same task scheduling behaviour as the
+Deterministic Priority Scheduler while being simpler in implementation
+and uses less memory for data management.  It maintains a single sorted
+list of all ready threads.  Thus blocking or unblocking a thread is not
+a constant time operation with this scheduler.
+
+This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_SIMPLE``.
+
+**NOTES:**
+
+This scheduler is appropriate for use in small systems where RAM is limited.
+
+.. COMMENT: === CONFIGURE_SCHEDULER_EDF ===
+
+Use Earliest Deadline First Scheduler
+-------------------------------------
+.. index:: CONFIGURE_SCHEDULER_EDF
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_EDF``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in
+RTEMS for uni-processor applications. The EDF schedules tasks with dynamic
+priorities equal to deadlines. The deadlines are declared using only
+Rate Monotonic manager which handles periodic behavior.  Period is always
+equal to deadline. If a task does not have any deadline declared or the
+deadline is cancelled, the task is considered a background task which is
+scheduled in case no deadline-driven tasks are ready to run.  Moreover,
+multiple background tasks are scheduled according their priority assigned
+upon initialization. All ready tasks reside in a single ready queue.
+
+This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_EDF``.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SCHEDULER_CBS ===
+
+Use Constant Bandwidth Server Scheduler
+---------------------------------------
+.. index:: CONFIGURE_SCHEDULER_CBS
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_CBS``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler
+in RTEMS for uni-processor applications. The CBS is a budget aware extension
+of EDF scheduler. The goal of this scheduler is to ensure temporal
+isolation of tasks. The CBS is equipped with a set of additional rules
+and provides with an extensive API.
+
+This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_CBS``.
+
+.. COMMENT: XXX - add cross reference to API chapter
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY_SMP ===
+
+Use Deterministic Priority SMP Scheduler
+----------------------------------------
+.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_PRIORITY_SMP``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+The Deterministic Priority SMP Scheduler is derived from the Deterministic
+Priority Scheduler but is capable of scheduling threads across multiple
+processors.
+
+In a configuration with SMP enabled at configure time, it may be
+explicitly selected by defining ``CONFIGURE_SCHEDULER_PRIORITY_SMP``.
+
+**NOTES:**
+
+This scheduler is only available when RTEMS is configured with SMP
+support enabled.
+
+This scheduler is currently the default in SMP configurations and is
+only selected when ``CONFIGURE_SMP_APPLICATION`` is defined.
+
+.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE_SMP ===
+
+Use Simple SMP Priority Scheduler
+---------------------------------
+.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_SIMPLE_SMP``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+The Simple SMP Priority Scheduler is derived from the Simple Priority
+Scheduler but is capable of scheduling threads across multiple processors.
+It is designed to provide the same task scheduling behaviour as the
+Deterministic Priority Scheduler while distributing threads across
+multiple processors.  Being based upon the Simple Priority Scheduler, it also
+maintains a single sorted list of all ready threads.  Thus blocking or
+unblocking a thread is not a constant time operation with this scheduler.
+
+In addition, when allocating threads to processors, the algorithm is not
+constant time. This algorithm was not designed with efficiency as a
+primary design goal.  Its primary design goal was to provide an SMP-aware
+scheduling algorithm that is simple to understand.
+
+In a configuration with SMP enabled at configure time, it may be
+explicitly selected by defining ``CONFIGURE_SCHEDULER_SIMPLE_SMP``.
+
+**NOTES:**
+
+This scheduler is only available when RTEMS is configured with SMP
+support enabled.
+
+.. COMMENT: === Configuring a Scheduler Name ===
+
+Configuring a Scheduler Name
+----------------------------
+.. index:: CONFIGURE_SCHEDULER_NAME
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_NAME``
+
+*DATA TYPE:*
+    RTEMS Name (``rtems_name``).
+
+*RANGE:*
+    Any value.
+
+*DEFAULT VALUE:*
+    The default name is
+    - ``"UCBS"`` for the Uni-Processor CBS scheduler,
+    - ``"UEDF"`` for the Uni-Processor EDF scheduler,
+    - ``"UPD "`` for the Uni-Processor Deterministic Priority scheduler,
+    - ``"UPS "`` for the Uni-Processor Simple Priority scheduler,
+    - ``"MPA "`` for the Multi-Processor Priority Affinity scheduler, and
+    - ``"MPD "`` for the Multi-Processor Deterministic Priority scheduler, and
+    - ``"MPS "`` for the Multi-Processor Simple Priority scheduler.
+
+**DESCRIPTION:**
+
+Schedulers can be identified via ``rtems_scheduler_ident``.  The name of the scheduler is determined by the configuration.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === Configuring a User Scheduler ===
+
+Configuring a User Provided Scheduler
+-------------------------------------
+.. index:: CONFIGURE_SCHEDULER_USER
+
+*CONSTANT:*
+    ``CONFIGURE_SCHEDULER_USER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+RTEMS allows the application to provide its own task/thread
+scheduling algorithm. In order to do this, one must define``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its
+own scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined
+then the following additional macros must be defined:
+
+- ``CONFIGURE_SCHEDULER_CONTEXT`` must be defined to a static definition
+  of the scheduler context of the user scheduler.
+
+- ``CONFIGURE_SCHEDULER_CONTROLS`` must be defined to a scheduler
+  control initializer for the user scheduler.
+
+- ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of
+  the per-thread information of the user scheduler.
+
+**NOTES:**
+
+At this time, the mechanics and requirements for writing a
+new scheduler are evolving and not fully documented.  It is
+recommended that you look at the existing Deterministic Priority
+Scheduler in ``cpukit/score/src/schedulerpriority*.c`` for
+guidance.  For guidance on the configuration macros, please examine``cpukit/sapi/include/confdefs.h`` for how these are defined for the
+Deterministic Priority Scheduler.
+
+.. COMMENT: === Configuring Clustered Schedulers ===
+
+.. _Configuring-a-System-Configuring-Clustered-Schedulers:
+
+Configuring Clustered Schedulers
+--------------------------------
+
+Clustered scheduling helps to control the worst-case latencies in a
+multi-processor system.  The goal is to reduce the amount of shared state in
+the system and thus prevention of lock contention.  Modern multi-processor
+systems tend to have several layers of data and instruction caches.  With
+clustered scheduling it is possible to honour the cache topology of a system
+and thus avoid expensive cache synchronization traffic.
+
+We have clustered scheduling in case the set of processors of a system is
+partitioned into non-empty pairwise-disjoint subsets.  These subsets are called
+clusters.  Clusters with a cardinality of one are partitions.  Each cluster is
+owned by exactly one scheduler instance.  In order to use clustered
+scheduling the application designer has to answer two questions.
+
+# How is the set of processors partitioned into clusters?
+
+# Which scheduler is used for which cluster?
+
+**CONFIGURATION:**
+
+The schedulers in an SMP system are statically configured on RTEMS.  Firstly
+the application must select which scheduling algorithms are available with the
+following defines
+
+- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``,
+
+- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and
+
+- ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``.
+
+This is necessary to calculate the per-thread overhead introduced by the
+schedulers.  After these definitions the configuration file must ``#include
+<rtems/scheduler.h>`` to have access to scheduler specific configuration macros.
+Each scheduler needs a context to store state information at run-time.  To
+provide a context for each scheduler is the next step.  Use the following
+macros to create scheduler contexts
+
+- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``,
+
+- ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and
+
+- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``.
+
+The ``name`` parameter is used as part of a designator for a global
+variable, so the usual C/C++ designator rules apply.  Additional parameters are
+scheduler specific.  The schedulers are registered in the system via the
+scheduler table.  To create the scheduler table define``CONFIGURE_SCHEDULER_CONTROLS`` to a list of the following scheduler
+control initializers
+
+- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``,
+
+- ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and
+
+- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``.
+
+The ``name`` parameter must correspond to the parameter defining the
+scheduler context.  The ``obj_name`` determines the scheduler object name
+and can be used in ``rtems_scheduler_ident()`` to get the scheduler object
+identifier.
+
+The last step is to define which processor uses which scheduler.
+For this purpose a scheduler assignment table must be defined.  The entry count
+of this table must be equal to the configured maximum processors
+(``CONFIGURE_SMP_MAXIMUM_PROCESSORS``).  A processor assignment to a
+scheduler can be optional or mandatory.  The boot processor must have a
+scheduler assigned.  In case the system needs more mandatory processors than
+available then a fatal run-time error will occur.  To specify the scheduler
+assignments define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a list of``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros.  The ``index`` parameter
+must be a valid index into the scheduler table.  The ``attr`` parameter
+defines the scheduler assignment attributes.  By default a scheduler assignment
+to a processor is optional.  For the scheduler assignment attribute use one of
+the mutually exclusive variants
+
+- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
+
+- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
+
+- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
+
+**ERRORS:**
+
+In case one of the scheduler indices in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` is invalid a link-time error will
+occur with an undefined reference to ``RTEMS_SCHEDULER_INVALID_INDEX``.
+
+Some fatal errors may occur in case of scheduler configuration inconsistencies or a lack
+of processors on the system.  The fatal source is``RTEMS_FATAL_SOURCE_SMP``.  None of the errors is internal.
+
+- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot
+  processor must have a scheduler assigned.
+
+- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a
+  mandatory processor beyond the range of physically or virtually available
+  processors.  The processor demand must be reduced for this system.
+
+- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a
+  mandatory processor failed during system initialization.  The system may not
+  have this processor at all or it could be a problem with a boot loader for
+  example.  Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` definition.
+
+- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not
+  allowed to start multitasking on a processor with no scheduler assigned.
+
+**EXAMPLE:**
+
+The following example shows a scheduler configuration for a hypothetical
+product using two chip variants.  One variant has four processors which is used
+for the normal product line and another provides eight processors for the
+high-performance product line.  The first processor performs hard-real time
+control of actuators and sensors.  The second processor is not used by RTEMS at
+all and runs a Linux instance to provide a graphical user interface.  The
+additional processors are used for a worker thread pool to perform data
+processing operations.
+
+The processors managed by RTEMS use two Deterministic Priority scheduler
+instances capable of dealing with 256 priority levels.  The scheduler with
+index zero has the name ``"IO  "``.  The scheduler with index one has the
+name ``"WORK"``.  The scheduler assignments of the first, third and fourth
+processor are mandatory, so the system must have at least four processors,
+otherwise a fatal run-time error will occur during system startup.  The
+processor assignments for the fifth up to the eighth processor are optional so
+that the same application can be used for the normal and high-performance
+product lines.  The second processor has no scheduler assigned and runs Linux.
+A hypervisor will ensure that the two systems cannot interfere in an
+undesirable way.
+.. code:: c
+
+    #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8
+    #define CONFIGURE_MAXIMUM_PRIORITY 255
+    /* Make the scheduler algorithm available \*/
+    #define CONFIGURE_SCHEDULER_PRIORITY_SMP
+    #include <rtems/scheduler.h>
+    /* Create contexts for the two scheduler instances \*/
+    RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
+    RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
+    /* Define the scheduler table \*/
+    #define CONFIGURE_SCHEDULER_CONTROLS \\
+    RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \\
+    io, \\
+    rtems_build_name('I', 'O', ' ', ' ') \\
+    ), \\
+    RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \\
+    work, \\
+    rtems_build_name('W', 'O', 'R', 'K') \\
+    )
+    /* Define the processor to scheduler assignments \*/
+    #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \\
+    RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
+    RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \\
+    RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
+
+.. COMMENT: === SMP Specific Configuration Parameters ===
+
+SMP Specific Configuration Parameters
+=====================================
+
+When RTEMS is configured to support SMP target systems, there are other
+configuration parameters which apply.
+
+.. COMMENT: XXX - add -enable-smp
+
+.. COMMENT: === CONFIGURE_SMP_APPLICATION ===
+
+.. _Configuring-a-System-Enable-SMP-Support-for-Applications:
+
+Enable SMP Support for Applications
+-----------------------------------
+.. index:: CONFIGURE_SMP_APPLICATION
+
+*CONSTANT:*
+    ``CONFIGURE_SMP_APPLICATION``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the
+application.
+
+**NOTES:**
+
+This define may go away in the future in case all RTEMS components are SMP
+ready.  This configuration define is ignored on uni-processor configurations.
+
+.. COMMENT: === CONFIGURE_SMP_MAXIMUM_PROCESSORS ===
+
+Specify Maximum Processors in SMP System
+----------------------------------------
+.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS
+
+*CONSTANT:*
+    ``CONFIGURE_SMP_MAXIMUM_PROCESSORS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined).
+
+**DESCRIPTION:**
+
+``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` must be set to the number of
+processors in the SMP configuration.
+
+**NOTES:**
+
+If there are more processors available than configured, the rest will be
+ignored.  This configuration define is ignored on uni-processor configurations.
+
+.. COMMENT: === Device Driver Table ===
+
+Device Driver Table
+===================
+
+This section defines the configuration parameters related
+to the automatic generation of a Device Driver Table.  As``<rtems/confdefs.h>`` only is aware of a small set of
+standard device drivers, the generated Device Driver
+Table is suitable for simple applications with no
+custom device drivers.
+
+Note that network device drivers are not configured in the Device Driver Table.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_DRIVERS ===
+
+Specifying the Maximum Number of Device Drivers
+-----------------------------------------------
+.. index:: CONFIGURE_MAXIMUM_DRIVERS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_DRIVERS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    This is computed by default, and is set to the number of device drivers
+    configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER``
+    configuration parameters.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device
+drivers per node.
+
+**NOTES:**
+
+If the application will dynamically install device drivers, then this
+configuration parameter must be larger than the number of statically
+configured device drivers. Drivers configured using the``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters
+are statically installed.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ===
+
+Enable Console Device Driver
+----------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the
+application wishes to include the Console Device Driver.
+
+**NOTES:**
+
+This device driver is responsible for providing standard input and output
+using */dev/console*.
+
+BSPs should be constructed in a manner that allows ``printk()``
+to work properly without the need for the console driver to be configured.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ===
+
+Enable Clock Driver
+-------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the
+application wishes to include the Clock Device Driver.
+
+**NOTES:**
+
+This device driver is responsible for providing a regular
+interrupt which invokes the ``rtems_clock_tick`` directive.
+
+If neither the Clock Driver not Benchmark Timer is enabled and
+the configuration parameter``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined,
+then a compile time error will occur.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ===
+
+Enable the Benchmark Timer Driver
+---------------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the
+application wishes to include the Timer Driver.  This device driver is
+used to benchmark execution times by the RTEMS Timing Test Suites.
+
+**NOTES:**
+
+If neither the Clock Driver not Benchmark Timer is enabled and
+the configuration parameter``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined,
+then a compile time error will occur.
+
+.. COMMENT: === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ===
+
+Specify Clock and Benchmark Timer Drivers Are Not Needed
+--------------------------------------------------------
+.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when
+the application does *NOT* want the Clock Device Driver and is *NOT*
+using the Timer Driver.  The inclusion or exclusion of the Clock Driver
+must be explicit in user applications.
+
+**NOTES:**
+
+This configuration parameter is intended to prevent the common user error
+of using the Hello World example as the baseline for an application and
+leaving out a clock tick source.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER ===
+
+Enable Real-Time Clock Driver
+-----------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the
+application wishes to include the Real-Time Clock Driver.
+
+**NOTES:**
+
+Most BSPs do not include support for a real-time clock. This is because
+many boards do not include the required hardware.
+
+If this is defined and the BSP does not have this device driver, then
+the user will get a link time error for an undefined symbol.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ===
+
+Enable the Watchdog Device Driver
+---------------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
+is defined if the application wishes to include the Watchdog Driver.
+
+**NOTES:**
+
+Most BSPs do not include support for a watchdog device driver. This is
+because many boards do not include the required hardware.
+
+If this is defined and the BSP does not have this device driver, then
+the user will get a link time error for an undefined symbol.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ===
+
+Enable the Graphics Frame Buffer Device Driver
+----------------------------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined
+if the application wishes to include the BSPâs Frame Buffer Device Driver.
+
+**NOTES:**
+
+Most BSPs do not include support for a Frame Buffer Device Driver. This is
+because many boards do not include the required hardware.
+
+If this is defined and the BSP does not have this device driver, then
+the user will get a link time error for an undefined symbol.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER ===
+
+Enable Stub Device Driver
+-------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the
+application wishes to include the Stub Device Driver.
+
+**NOTES:**
+
+This device driver simply provides entry points that return successful
+and is primarily a test fixture. It is supported by all BSPs.
+
+.. COMMENT: === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ===
+
+Specify Application Prerequisite Device Drivers
+-----------------------------------------------
+.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS``
+
+*DATA TYPE:*
+    device driver entry structures
+
+*RANGE:*
+    Undefined or set of device driver entry structures
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the
+application has device drivers it needs to include in the Device Driver
+Table.  This should be defined to the set of device driver entries that
+will be placed in the table at the *FRONT* of the Device Driver Table
+and initialized before any other drivers *EXCEPT* any BSP prerequisite
+drivers.
+
+**NOTES:**
+
+In some cases, it is used by System On Chip BSPs to support peripheral
+buses beyond those normally found on the System On Chip. For example,
+this is used by one RTEMS system which has implemented a SPARC/ERC32
+based board with VMEBus. The VMEBus Controller initialization is performed
+by a device driver configured via this configuration parameter.
+
+.. COMMENT: XXX Add example
+
+.. COMMENT: === CONFIGURE_APPLICATION_EXTRA_DRIVERS ===
+
+Specify Extra Application Device Drivers
+----------------------------------------
+.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_EXTRA_DRIVERS``
+
+*DATA TYPE:*
+    device driver entry structures
+
+*RANGE:*
+    Undefined or set of device driver entry structures
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the
+application has device drivers it needs to include in the Device Driver
+Table.  This should be defined to the set of device driver entries that
+will be placed in the table at the *END* of the Device Driver Table.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER ===
+
+Enable /dev/null Device Driver
+------------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
+.. index:: /dev/null
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+This configuration variable is specified to enable */dev/null*
+device driver.
+
+**NOTES:**
+
+This device driver is supported by all BSPs.
+
+.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER ===
+
+Enable /dev/zero Device Driver
+------------------------------
+.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
+.. index:: /dev/zero
+
+*CONSTANT:*
+    ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+This configuration variable is specified to enable */dev/zero*
+device driver.
+
+**NOTES:**
+
+This device driver is supported by all BSPs.
+
+.. COMMENT: === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE ===
+
+Specifying Application Defined Device Driver Table
+--------------------------------------------------
+.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default, indicating the ``<rtems/confdefs.h>``
+    is providing the device driver table.
+
+**DESCRIPTION:**
+
+``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` is defined if the application
+wishes to provide their own Device Driver Table.
+
+The table must be an array of ``rtems_driver_address_table`` entries named``_IO_Driver_address_table``.  The application must also provide a const
+variable ``_IO_Number_of_drivers`` of type ``size_t`` indicating the
+number of entries in the ``_IO_Driver_address_table``.
+
+**NOTES:**
+
+It is expected that there the application would only rarely need to do this.
+
+.. COMMENT: === Multiprocessing Configuration ===
+
+Multiprocessing Configuration
+=============================
+
+This section defines the multiprocessing related system configuration
+parameters supported by ``<rtems/confdefs.h>``.  They are only used
+if the Multiprocessing Support (distinct from the SMP support) is enabled
+at configure time using the ``--enable-multiprocessing`` option.
+
+Additionally, this class of Configuration Constants are only applicable if``CONFIGURE_MP_APPLICATION`` is defined.
+
+.. COMMENT: === CONFIGURE_MP_APPLICATION ===
+
+Specify Application Will Use Multiprocessing
+--------------------------------------------
+.. index:: CONFIGURE_MP_APPLICATION
+
+*CONSTANT:*
+    ``CONFIGURE_MP_APPLICATION``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+This configuration parameter must be defined to indicate
+that the application intends to be part of a multiprocessing
+configuration. Additional configuration parameters are assumed to be
+provided.
+
+**NOTES:**
+
+This has no impact unless RTEMS was configured and built using the``--enable-multiprocessing`` option.
+
+.. COMMENT: === CONFIGURE_MP_NODE_NUMBER ===
+
+Configure Node Number in Multiprocessor Configuration
+-----------------------------------------------------
+.. index:: CONFIGURE_MP_NODE_NUMBER
+
+*CONSTANT:*
+    ``CONFIGURE_MP_NODE_NUMBER``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is ``NODE_NUMBER``, which is assumed to be
+    set by the compilation environment.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MP_NODE_NUMBER`` is the node number of
+this node in a multiprocessor system.
+
+**NOTES:**
+
+In the RTEMS Multiprocessing Test Suite, the node number is derived from
+the Makefile variable ``NODE_NUMBER``. The same code is compiled with
+the ``NODE_NUMBER`` set to different values. The test programs behave
+differently based upon their node number.
+
+.. COMMENT: === CONFIGURE_MP_MAXIMUM_NODES ===
+
+Configure Maximum Node in Multiprocessor Configuration
+------------------------------------------------------
+.. index:: CONFIGURE_MP_MAXIMUM_NODES
+
+*CONSTANT:*
+    ``CONFIGURE_MP_MAXIMUM_NODES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 2.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a
+multiprocessor system.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ===
+
+Configure Maximum Global Objects in Multiprocessor Configuration
+----------------------------------------------------------------
+.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS
+
+*CONSTANT:*
+    ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Positive.
+
+*DEFAULT VALUE:*
+    The default value is 32.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of
+concurrently active global objects in a multiprocessor system.
+
+**NOTES:**
+
+This value corresponds to the total number of objects which can be
+created with the ``RTEMS_GLOBAL`` attribute.
+
+.. COMMENT: === CONFIGURE_MP_MAXIMUM_PROXIES ===
+
+Configure Maximum Proxies in Multiprocessor Configuration
+---------------------------------------------------------
+.. index:: CONFIGURE_MP_MAXIMUM_PROXIES
+
+*CONSTANT:*
+    ``CONFIGURE_MP_MAXIMUM_PROXIES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    The default value is 32.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently
+active thread/task proxies on this node in a multiprocessor system.
+
+**NOTES:**
+
+Since a proxy is used to represent a remote task/thread which is blocking on
+this node. This configuration parameter reflects the maximum number of
+remote tasks/threads which can be blocked on objects on this node.
+
+.. COMMENT: XXX - add xref to proxy discussion in MP chapter
+
+.. COMMENT: === CONFIGURE_MP_MPCI_TABLE_POINTER ===
+
+Configure MPCI in Multiprocessor Configuration
+----------------------------------------------
+.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER
+
+*CONSTANT:*
+    ``CONFIGURE_MP_MPCI_TABLE_POINTER``
+
+*DATA TYPE:*
+    pointer to ``rtems_mpci_table``
+
+*RANGE:*
+    undefined or valid pointer
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the
+MPCI Configuration Table.  The default value of this field is``&MPCI_table``.
+
+**NOTES:**
+
+RTEMS provides a Shared Memory MPCI Device Driver which can be used on
+any Multiprocessor System assuming the BSP provides the proper set of
+supporting methods.
+
+.. COMMENT: === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE ===
+
+Do Not Generate Multiprocessor Configuration Table
+--------------------------------------------------
+.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE
+
+*CONSTANT:*
+    ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` is defined if the
+application wishes to provide their own Multiprocessing Configuration
+Table.  The generated table is named ``Multiprocessing_configuration``.
+
+**NOTES:**
+
+This is a configuration parameter which is very unlikely to be used by
+an application. If you find yourself wanting to use it in an application,
+please reconsider and discuss this on the RTEMS Users mailing list.
+
+.. COMMENT: === Ada Tasks ===
+
+Ada Tasks
+=========
+
+This section defines the system configuration parameters supported
+by ``<rtems/confdefs.h>`` related to configuring RTEMS to support
+a task using Ada tasking with GNAT/RTEMS.
+
+These configuration parameters are only available when RTEMS is built with
+the ``--enable-ada`` configure option and the application specifies``CONFIGURE_GNAT_RTEMS``.
+
+Additionally RTEMS includes an Ada language binding to the Classic
+API which has a test suite. This test suite is enabled only when``--enable-tests`` and ``--enable-expada`` are specified on the
+configure command.
+
+.. COMMENT: === CONFIGURE_GNAT_RTEMS ===
+
+Specify Application Includes Ada Code
+-------------------------------------
+.. index:: CONFIGURE_GNAT_RTEMS
+
+*CONSTANT:*
+    ``CONFIGURE_GNAT_RTEMS``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_GNAT_RTEMS`` is defined to inform RTEMS that the GNAT
+Ada run-time is to be used by the application.
+
+**NOTES:**
+
+This configuration parameter is critical as it makes``<rtems/confdefs.h>`` configure the resources (POSIX API Threads,
+Mutexes, Condition Variables, and Keys) used implicitly by the GNAT
+run-time.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_ADA_TASKS ===
+
+Specify the Maximum Number of Ada Tasks.
+----------------------------------------
+.. index:: CONFIGURE_MAXIMUM_ADA_TASKS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_ADA_TASKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Undefined or positive.
+
+*DEFAULT VALUE:*
+    If ``CONFIGURE_GNAT_RTEMS`` is defined, then the
+    default value is 20, otherwise the default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_ADA_TASKS`` is the number of Ada tasks that can
+be concurrently active in the system.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS ===
+
+Specify the Maximum Fake Ada Tasks
+----------------------------------
+.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
+
+*CONSTANT:*
+    .. index:: ``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 0.
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` is the number of *fake* Ada tasks
+that can be concurrently active in the system.  A *fake* Ada task is
+a non-Ada task that makes calls back into Ada code and thus implicitly
+uses the Ada run-time.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: === PCI Library ===
+
+PCI Library
+===========
+
+This section defines the system configuration parameters supported
+by ``rtems/confdefs.h`` related to configuring the PCI Library
+for RTEMS.
+
+The PCI Library startup behaviour can be configured in four different
+ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
+
+- .. index:: PCI_LIB_AUTO
+  ``PCI_LIB_AUTO`` is used to enable the PCI auto configuration
+  software. PCI will be automatically probed, PCI buses enumerated, all
+  devices and bridges will be initialized using Plug & Play software
+  routines. The PCI device tree will be populated based on the PCI devices
+  found in the system, PCI devices will be configured by allocating address
+  region resources automatically in PCI space according to the BSP or host
+  bridge driver set up.
+
+- .. index:: PCI_LIB_READ
+  ``PCI_LIB_READ`` is used to enable the PCI read configuration
+  software. The current PCI configuration is read to create the RAM
+  representation (the PCI device tree) of the PCI devices present. PCI devices
+  are assumed to already have been initialized and PCI buses enumerated, it is
+  therefore required that a BIOS or a boot loader has set up configuration space
+  prior to booting into RTEMS.
+
+- .. index:: PCI_LIB_STATIC
+  ``PCI_LIB_STATIC`` is used to enable the PCI static configuration
+  software. The user provides a PCI tree with information how all PCI devices
+  are to be configured at compile time by linking in a custom``struct pci_bus pci_hb`` tree. The static PCI library will not probe PCI
+  for devices, instead it will assume that all devices defined by the user are
+  present, it will enumerate the PCI buses and configure all PCI devices in
+  static configuration accordingly. Since probe and allocation software is not
+  needed the startup is faster, has smaller footprint and does not require
+  dynamic memory allocation.
+
+- .. index:: PCI_LIB_PERIPHERAL
+  ``PCI_LIB_PERIPHERAL`` is used to enable the PCI peripheral
+  configuration. It is similar to ``PCI_LIB_STATIC``, but it will never write
+  the configuration to the PCI devices since PCI peripherals are not allowed to
+  access PCI configuration space.
+
+Note that selecting PCI_LIB_STATIC or PCI_LIB_PERIPHERAL but not defining``pci_hb`` will reuslt in link errors. Note also that in these modes
+Plug & Play is not performed.
+
+.. COMMENT: === Go Tasks ===
+
+Go Tasks
+========
+
+.. COMMENT: === CONFIGURE_ENABLE_GO ===
+
+Specify Application Includes Go Code
+------------------------------------
+.. index:: CONFIGURE_ENABLE_GO
+
+*CONSTANT:*
+    ``CONFIGURE_ENABLE_GO``
+
+*DATA TYPE:*
+    Boolean feature macro.
+
+*RANGE:*
+    Defined or undefined.
+
+*DEFAULT VALUE:*
+    This is not defined by default.
+
+**DESCRIPTION:**
+
+``CONFIGURE_ENABLE_GO`` is defined to inform RTEMS that the Go
+run-time is to be used by the application.
+
+**NOTES:**
+
+The Go language support is experimental
+
+.. COMMENT: === CONFIGURE_MAXIMUM_GOROUTINES ===
+
+Specify the maximum number of Go routines
+-----------------------------------------
+.. index:: CONFIGURE_MAXIMUM_GOROUTINES
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_GOROUTINES``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 400
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_GOROUTINES`` is defined to specify the maximum number of
+Go routines.
+
+**NOTES:**
+
+The Go language support is experimental
+
+.. COMMENT: === CONFIGURE_MAXIMUM_GO_CHANNELS ===
+
+Specify the maximum number of Go Channels
+-----------------------------------------
+.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS
+
+*CONSTANT:*
+    ``CONFIGURE_MAXIMUM_GO_CHANNELS``
+
+*DATA TYPE:*
+    Unsigned integer (``uint32_t``).
+
+*RANGE:*
+    Zero or positive.
+
+*DEFAULT VALUE:*
+    The default value is 500
+
+**DESCRIPTION:**
+
+``CONFIGURE_MAXIMUM_GO_CHANNELS`` is defined to specify the maximum number
+of Go channels.
+
+**NOTES:**
+
+The Go language support is experimental
+
+.. COMMENT: === Configuration Data Structures ===
+
+Configuration Data Structures
+=============================
+
+It is recommended that applications be configured using``<rtems/confdefs.h>`` as it is simpler and insulates applications
+from changes in the underlying data structures.  However, it is sometimes
+important to understand the data structures that are automatically filled
+in by the configuration parameters.  This section describes the primary
+configuration data structures.
+
+If the user wishes to see the details of a particular data structure,
+they are are advised to look at the source code. After all, that is one
+of the advantages of RTEMS.
+
+.. COMMENT: COPYRIGHT (c) 1988-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Multiprocessing Manager
+#######################
+
+.. index:: multiprocessing
+
+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.
+
+Multiprocessing operations are transparent at the application level.
+Operations on remote objects are implicitly processed as remote
+procedure calls.  Although remote operations on objects are supported
+from Ada tasks, the calls used to support the multiprocessing
+communications should be implemented in C and are not supported
+in the Ada binding.  Since there is no Ada binding for RTEMS
+multiprocessing support services, all examples and data structures
+shown in this chapter are in C.
+
+Background
+==========
+
+.. index:: multiprocessing topologies
+
+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.
+
+Nodes
+-----
+.. index:: nodes, definition
+
+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 the ``maximum_nodes``
+configuration parameter.  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.
+
+Global Objects
+--------------
+.. index:: global objects, definition
+
+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.
+
+Global Object Table
+-------------------
+.. index:: global objects 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.
+
+Remote Operations
+-----------------
+.. index:: MPCI and 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:
+
+# The application issues a directive accessing a
+  remote global object.
+
+# RTEMS determines the node on which the object
+  resides.
+
+# RTEMS calls the user-provided MPCI routine
+  GET_PACKET to obtain a packet in which to build a RQ message.
+
+# 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).
+
+# The calling task is blocked until the RR message
+  arrives, and control of the processor is transferred to another
+  task.
+
+# The MPCI layer on the destination node senses the
+  arrival of a packet (commonly in an ISR), and calls the``rtems_multiprocessing_announce``
+  directive.  This directive readies the Multiprocessing Server.
+
+# 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.
+
+# The MPCI layer on the originating node senses the
+  arrival of a packet (typically via an interrupt), and calls the RTEMS``rtems_multiprocessing_announce`` directive.  This directive
+  readies the Multiprocessing Server.
+
+# 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.
+
+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.
+
+Proxies
+-------
+.. index:: proxy, definition
+
+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``rtems.semaphore_obtain`` and``rtems.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.
+
+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.
+
+Multiprocessor Communications Interface Layer
+=============================================
+
+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... index:: MPCI, definition
+
+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... index:: MPCI entry points
+
+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:
+
+- initialization 	initialize the MPCI
+
+- get_packet 	obtain a packet buffer
+
+- return_packet 	return a packet buffer
+
+- send_packet 	send a packet to another node
+
+- receive_packet 	called to get an arrived packet
+
+A packet is sent by RTEMS in each of the following situations:
+
+- an RQ is generated on an originating node;
+
+- an RR is generated on a destination node;
+
+- a global object is created;
+
+- a global object is deleted;
+
+- a local task blocked on a remote object is deleted;
+
+- during system initialization to check for system consistency.
+
+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``rtems_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.
+
+INITIALIZATION
+--------------
+
+The INITIALIZATION component of the user-provided
+MPCI layer is called as part of the ``rtems_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:.. index:: rtems_mpci_entry
+
+.. code:: c
+
+    rtems_mpci_entry user_mpci_initialization(
+    rtems_configuration_table \*configuration
+    );
+
+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.
+
+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:
+.. code:: c
+
+    rtems_mpci_entry user_mpci_get_packet(
+    rtems_packet_prefix \**packet
+    );
+
+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.
+
+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:
+.. code:: c
+
+    rtems_mpci_entry user_mpci_return_packet(
+    rtems_packet_prefix \*packet
+    );
+
+where packet is the address of a packet.  If the
+packet cannot be successfully returned, the fatal error manager
+should be invoked.
+
+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:
+.. code:: c
+
+    rtems_mpci_entry user_mpci_receive_packet(
+    rtems_packet_prefix \**packet
+    );
+
+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.
+
+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:
+.. code:: c
+
+    rtems_mpci_entry user_mpci_send_packet(
+    uint32_t               node,
+    rtems_packet_prefix  \**packet
+    );
+
+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.
+
+.. COMMENT: XXX packet_prefix structure needs to be defined in this document
+
+Many MPCI layers use the ``packet_length`` field of the``rtems_packet_prefix`` portion
+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 ``rtems_packet_prefix`` portion of the
+packet indicates how much of the packet in 32-bit units may require conversion
+in a heterogeneous system.
+
+Supporting Heterogeneous Environments
+-------------------------------------
+.. index:: heterogeneous multiprocessing
+
+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:
+
+.. code:: c
+
+    +---------------+----------------+---------------+----------------+
+    |               |                |               |                |
+    |    Byte 3     |     Byte 2     |    Byte 1     |    Byte 0      |
+    |               |                |               |                |
+    +---------------+----------------+---------------+----------------+
+
+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:
+.. code:: c
+
+    +---------------+----------------+---------------+----------------+
+    |               |                |               |                |
+    |    Byte 0     |     Byte 1     |    Byte 2     |    Byte 3      |
+    |               |                |               |                |
+    +---------------+----------------+---------------+----------------+
+
+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:
+
+- All packets must begin on a four byte boundary.
+
+- Packets are composed of both RTEMS and application data.  All RTEMS data
+  is treated as 32-bit unsigned quantities and is in the first ``to_convert``
+  32-bit quantities of the packet.  The ``to_convert`` field is part of the``rtems_packet_prefix`` portion of the packet.
+
+- 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.
+
+- RTEMS makes no assumptions regarding the application
+  data component of the packet.
+
+Operations
+==========
+
+Announcing a Packet
+-------------------
+
+The ``rtems_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.
+
+Directives
+==========
+
+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.
+
+MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
+-----------------------------------------------------------
+.. index:: announce arrival of package
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_multiprocessing_announce
+
+.. code:: c
+
+    void rtems_multiprocessing_announce( void );
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**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.
+
+**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.
+
+.. COMMENT: COPYRIGHT (c) 2014.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Symmetric Multiprocessing Services
+##################################
+
+Introduction
+============
+
+The Symmetric Multiprocessing (SMP) support of the RTEMS 4.10.99.0 is
+available on
+
+- ARM,
+
+- PowerPC, and
+
+- SPARC.
+
+It must be explicitly enabled via the ``--enable-smp`` configure command
+line option.  To enable SMP in the application configuration see:ref:`Configuring a System Enable SMP Support for Applications <Configuring-a-System-Enable-SMP-Support-for-Applications>`.  The default
+scheduler for SMP applications supports up to 32 processors and is a global
+fixed priority scheduler, see also :ref:`Configuring a System Configuring
+Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.  For example applications see:file:`testsuites/smptests`.
+
+*WARNING: The SMP support in RTEMS is work in progress.  Before you
+start using this RTEMS version for SMP ask on the RTEMS mailing list.*
+
+This chapter describes the services related to Symmetric Multiprocessing
+provided by RTEMS.
+
+The application level services currently provided are:
+
+- ``rtems_get_processor_count`` - Get processor count
+
+- ``rtems_get_current_processor`` - Get current processor index
+
+- ``rtems_scheduler_ident`` - Get ID of a scheduler
+
+- ``rtems_scheduler_get_processor_set`` - Get processor set of a scheduler
+
+- ``rtems_task_get_scheduler`` - Get scheduler of a task
+
+- ``rtems_task_set_scheduler`` - Set scheduler of a task
+
+- ``rtems_task_get_affinity`` - Get task processor affinity
+
+- ``rtems_task_set_affinity`` - Set task processor affinity
+
+Background
+==========
+
+Uniprocessor versus SMP Parallelism
+-----------------------------------
+
+Uniprocessor systems have long been used in embedded systems. In this hardware
+model, there are some system execution characteristics which have long been
+taken for granted:
+
+- one task executes at a time
+
+- hardware events result in interrupts
+
+There is no true parallelism. Even when interrupts appear to occur
+at the same time, they are processed in largely a serial fashion.
+This is true even when the interupt service routines are allowed to
+nest.  From a tasking viewpoint,  it is the responsibility of the real-time
+operatimg system to simulate parallelism by switching between tasks.
+These task switches occur in response to hardware interrupt events and explicit
+application events such as blocking for a resource or delaying.
+
+With symmetric multiprocessing, the presence of multiple processors
+allows for true concurrency and provides for cost-effective performance
+improvements. Uniprocessors tend to increase performance by increasing
+clock speed and complexity. This tends to lead to hot, power hungry
+microprocessors which are poorly suited for many embedded applications.
+
+The true concurrency is in sharp contrast to the single task and
+interrupt model of uniprocessor systems. This results in a fundamental
+change to uniprocessor system characteristics listed above. Developers
+are faced with a different set of characteristics which, in turn, break
+some existing assumptions and result in new challenges. In an SMP system
+with N processors, these are the new execution characteristics.
+
+- N tasks execute in parallel
+
+- hardware events result in interrupts
+
+There is true parallelism with a task executing on each processor and
+the possibility of interrupts occurring on each processor. Thus in contrast
+to their being one task and one interrupt to consider on a uniprocessor,
+there are N tasks and potentially N simultaneous interrupts to consider
+on an SMP system.
+
+This increase in hardware complexity and presence of true parallelism
+results in the application developer needing to be even more cautious
+about mutual exclusion and shared data access than in a uniprocessor
+embedded system. Race conditions that never or rarely happened when an
+application executed on a uniprocessor system, become much more likely
+due to multiple threads executing in parallel. On a uniprocessor system,
+these race conditions would only happen when a task switch occurred at
+just the wrong moment. Now there are N-1 tasks executing in parallel
+all the time and this results in many more opportunities for small
+windows in critical sections to be hit.
+
+Task Affinity
+-------------
+.. index:: task affinity
+.. index:: thread affinity
+
+RTEMS provides services to manipulate the affinity of a task. Affinity
+is used to specify the subset of processors in an SMP system on which
+a particular task can execute.
+
+By default, tasks have an affinity which allows them to execute on any
+available processor.
+
+Task affinity is a possible feature to be supported by SMP-aware
+schedulers. However, only a subset of the available schedulers support
+affinity. Although the behavior is scheduler specific, if the scheduler
+does not support affinity, it is likely to ignore all attempts to set
+affinity.
+
+The scheduler with support for arbitary processor affinities uses a proof of
+concept implementation.  See https://devel.rtems.org/ticket/2510.
+
+Task Migration
+--------------
+.. index:: task migration
+.. index:: thread migration
+
+With more than one processor in the system tasks can migrate from one processor
+to another.  There are three reasons why tasks migrate in RTEMS.
+
+- The scheduler changes explicitly via ``rtems_task_set_scheduler()`` or
+  similar directives.
+
+- The task resumes execution after a blocking operation.  On a priority
+  based scheduler it will evict the lowest priority task currently assigned to a
+  processor in the processor set managed by the scheduler instance.
+
+- The task moves temporarily to another scheduler instance due to locking
+  protocols like *Migratory Priority Inheritance* or the*Multiprocessor Resource Sharing Protocol*.
+
+Task migration should be avoided so that the working set of a task can stay on
+the most local cache level.
+
+The current implementation of task migration in RTEMS has some implications
+with respect to the interrupt latency.  It is crucial to preserve the system
+invariant that a task can execute on at most one processor in the system at a
+time.  This is accomplished with a boolean indicator in the task context.  The
+processor architecture specific low-level task context switch code will mark
+that a task context is no longer executing and waits that the heir context
+stopped execution before it restores the heir context and resumes execution of
+the heir task.  So there is one point in time in which a processor is without a
+task.  This is essential to avoid cyclic dependencies in case multiple tasks
+migrate at once.  Otherwise some supervising entity is necessary to prevent
+life-locks.  Such a global supervisor would lead to scalability problems so
+this approach is not used.  Currently the thread dispatch is performed with
+interrupts disabled.  So in case the heir task is currently executing on
+another processor then this prolongs the time of disabled interrupts since one
+processor has to wait for another processor to make progress.
+
+It is difficult to avoid this issue with the interrupt latency since interrupts
+normally store the context of the interrupted task on its stack.  In case a
+task is marked as not executing we must not use its task stack to store such an
+interrupt context.  We cannot use the heir stack before it stopped execution on
+another processor.  So if we enable interrupts during this transition we have
+to provide an alternative task independent stack for this time frame.  This
+issue needs further investigation.
+
+Clustered Scheduling
+--------------------
+
+We have clustered scheduling in case the set of processors of a system is
+partitioned into non-empty pairwise-disjoint subsets. These subsets are called
+clusters.  Clusters with a cardinality of one are partitions.  Each cluster is
+owned by exactly one scheduler instance.
+
+Clustered scheduling helps to control the worst-case latencies in
+multi-processor systems, see *Brandenburg, BjÃÂ¶rn B.: Scheduling and
+Locking in Multiprocessor Real-Time Operating Systems. PhD thesis, 2011.http://www.cs.unc.edu/~bbb/diss/brandenburg-diss.pdf*.  The goal is to
+reduce the amount of shared state in the system and thus prevention of lock
+contention. Modern multi-processor systems tend to have several layers of data
+and instruction caches.  With clustered scheduling it is possible to honour the
+cache topology of a system and thus avoid expensive cache synchronization
+traffic.  It is easy to implement.  The problem is to provide synchronization
+primitives for inter-cluster synchronization (more than one cluster is involved
+in the synchronization process). In RTEMS there are currently four means
+available
+
+- events,
+
+- message queues,
+
+- semaphores using the :ref:`Semaphore Manager Priority Inheritance <Semaphore-Manager-Priority-Inheritance>`
+  protocol (priority boosting), and
+
+- semaphores using the :ref:`Semaphore Manager Multiprocessor Resource
+  Sharing Protocol <Semaphore-Manager-Multiprocessor-Resource-Sharing-Protocol>` (MrsP).
+
+The clustered scheduling approach enables separation of functions with
+real-time requirements and functions that profit from fairness and high
+throughput provided the scheduler instances are fully decoupled and adequate
+inter-cluster synchronization primitives are used.  This is work in progress.
+
+For the configuration of clustered schedulers see :ref:`Configuring a System
+Configuring Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
+
+To set the scheduler of a task see :ref:`Symmetric Multiprocessing Services
+SCHEDULER_IDENT - Get ID of a scheduler <Symmetric-Multiprocessing-Services-SCHEDULER_005fIDENT-_002d-Get-ID-of-a-scheduler>` and :ref:`Symmetric Multiprocessing
+Services TASK_SET_SCHEDULER - Set scheduler of a task <Symmetric-Multiprocessing-Services-TASK_005fSET_005fSCHEDULER-_002d-Set-scheduler-of-a-task>`.
+
+Task Priority Queues
+--------------------
+
+Due to the support for clustered scheduling the task priority queues need
+special attention.  It makes no sense to compare the priority values of two
+different scheduler instances.  Thus, it is not possible to simply use one
+plain priority queue for tasks of different scheduler instances.
+
+One solution to this problem is to use two levels of queues.  The top level
+queue provides FIFO ordering and contains priority queues.  Each priority queue
+is associated with a scheduler instance and contains only tasks of this
+scheduler instance.  Tasks are enqueued in the priority queue corresponding to
+their scheduler instance.  In case this priority queue was empty, then it is
+appended to the FIFO.  To dequeue a task the highest priority task of the first
+priority queue in the FIFO is selected.  Then the first priority queue is
+removed from the FIFO.  In case the previously first priority queue is not
+empty, then it is appended to the FIFO.  So there is FIFO fairness with respect
+to the highest priority task of each scheduler instances. See also *Brandenburg, BjÃÂ¶rn B.: A fully preemptive multiprocessor semaphore protocol for
+latency-sensitive real-time applications. In Proceedings of the 25th Euromicro
+Conference on Real-Time Systems (ECRTS 2013), pages 292Ã¢ÂÂ302, 2013.http://www.mpi-sws.org/~bbb/papers/pdf/ecrts13b.pdf*.
+
+Such a two level queue may need a considerable amount of memory if fast enqueue
+and dequeue operations are desired (depends on the scheduler instance count).
+To mitigate this problem an approch of the FreeBSD kernel was implemented in
+RTEMS.  We have the invariant that a task can be enqueued on at most one task
+queue.  Thus, we need only as many queues as we have tasks.  Each task is
+equipped with spare task queue which it can give to an object on demand.  The
+task queue uses a dedicated memory space independent of the other memory used
+for the task itself. In case a task needs to block, then there are two options
+
+- the object already has task queue, then the task enqueues itself to this
+  already present queue and the spare task queue of the task is added to a list
+  of free queues for this object, or
+
+- otherwise, then the queue of the task is given to the object and the task
+  enqueues itself to this queue.
+
+In case the task is dequeued, then there are two options
+
+- the task is the last task on the queue, then it removes this queue from
+  the object and reclaims it for its own purpose, or
+
+- otherwise, then the task removes one queue from the free list of the
+  object and reclaims it for its own purpose.
+
+Since there are usually more objects than tasks, this actually reduces the
+memory demands. In addition the objects contain only a pointer to the task
+queue structure. This helps to hide implementation details and makes it
+possible to use self-contained synchronization objects in Newlib and GCC (C++
+and OpenMP run-time support).
+
+Scheduler Helping Protocol
+--------------------------
+
+The scheduler provides a helping protocol to support locking protocols like*Migratory Priority Inheritance* or the *Multiprocessor Resource
+Sharing Protocol*.  Each ready task can use at least one scheduler node at a
+time to gain access to a processor.  Each scheduler node has an owner, a user
+and an optional idle task.  The owner of a scheduler node is determined a task
+creation and never changes during the life time of a scheduler node.  The user
+of a scheduler node may change due to the scheduler helping protocol.  A
+scheduler node is in one of the four scheduler help states:
+
+:dfn:`help yourself`
+    This scheduler node is solely used by the owner task.  This task owns no
+    resources using a helping protocol and thus does not take part in the scheduler
+    helping protocol.  No help will be provided for other tasks.
+
+:dfn:`help active owner`
+    This scheduler node is owned by a task actively owning a resource and can be
+    used to help out tasks.
+    In case this scheduler node changes its state from ready to scheduled and the
+    task executes using another node, then an idle task will be provided as a user
+    of this node to temporarily execute on behalf of the owner task.  Thus lower
+    priority tasks are denied access to the processors of this scheduler instance.
+    In case a task actively owning a resource performs a blocking operation, then
+    an idle task will be used also in case this node is in the scheduled state.
+
+:dfn:`help active rival`
+    This scheduler node is owned by a task actively obtaining a resource currently
+    owned by another task and can be used to help out tasks.
+    The task owning this node is ready and will give away its processor in case the
+    task owning the resource asks for help.
+
+:dfn:`help passive`
+    This scheduler node is owned by a task obtaining a resource currently owned by
+    another task and can be used to help out tasks.
+    The task owning this node is blocked.
+
+The following scheduler operations return a task in need for help
+
+- unblock,
+
+- change priority,
+
+- yield, and
+
+- ask for help.
+
+A task in need for help is a task that encounters a scheduler state change from
+scheduled to ready (this is a pre-emption by a higher priority task) or a task
+that cannot be scheduled in an unblock operation.  Such a task can ask tasks
+which depend on resources owned by this task for help.
+
+In case it is not possible to schedule a task in need for help, then the
+scheduler nodes available for the task will be placed into the set of ready
+scheduler nodes of the corresponding scheduler instances.  Once a state change
+from ready to scheduled happens for one of scheduler nodes it will be used to
+schedule the task in need for help.
+
+The ask for help scheduler operation is used to help tasks in need for help
+returned by the operations mentioned above.  This operation is also used in
+case the root of a resource sub-tree owned by a task changes.
+
+The run-time of the ask for help procedures depend on the size of the resource
+tree of the task needing help and other resource trees in case tasks in need
+for help are produced during this operation.  Thus the worst-case latency in
+the system depends on the maximum resource tree size of the application.
+
+Critical Section Techniques and SMP
+-----------------------------------
+
+As discussed earlier, SMP systems have opportunities for true parallelism
+which was not possible on uniprocessor systems. Consequently, multiple
+techniques that provided adequate critical sections on uniprocessor
+systems are unsafe on SMP systems. In this section, some of these
+unsafe techniques will be discussed.
+
+In general, applications must use proper operating system provided mutual
+exclusion mechanisms to ensure correct behavior. This primarily means
+the use of binary semaphores or mutexes to implement critical sections.
+
+Disable Interrupts and Interrupt Locks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A low overhead means to ensure mutual exclusion in uni-processor configurations
+is to disable interrupts around a critical section.  This is commonly used in
+device driver code and throughout the operating system core.  On SMP
+configurations, however, disabling the interrupts on one processor has no
+effect on other processors.  So, this is insufficient to ensure system wide
+mutual exclusion.  The macros
+
+- ``rtems_interrupt_disable()``,
+
+- ``rtems_interrupt_enable()``, and
+
+- ``rtems_interrupt_flush()``
+
+are disabled on SMP configurations and its use will lead to compiler warnings
+and linker errors.  In the unlikely case that interrupts must be disabled on
+the current processor, then the
+
+- ``rtems_interrupt_local_disable()``, and
+
+- ``rtems_interrupt_local_enable()``
+
+macros are now available in all configurations.
+
+Since disabling of interrupts is not enough to ensure system wide mutual
+exclusion on SMP, a new low-level synchronization primitive was added - the
+interrupt locks.  They are a simple API layer on top of the SMP locks used for
+low-level synchronization in the operating system core.  Currently they are
+implemented as a ticket lock.  On uni-processor configurations they degenerate
+to simple interrupt disable/enable sequences.  It is disallowed to acquire a
+single interrupt lock in a nested way.  This will result in an infinite loop
+with interrupts disabled.  While converting legacy code to interrupt locks care
+must be taken to avoid this situation.
+.. code:: c
+
+    void legacy_code_with_interrupt_disable_enable( void )
+    {
+    rtems_interrupt_level level;
+    rtems_interrupt_disable( level );
+    /* Some critical stuff \*/
+    rtems_interrupt_enable( level );
+    }
+    RTEMS_INTERRUPT_LOCK_DEFINE( static, lock, "Name" )
+    void smp_ready_code_with_interrupt_lock( void )
+    {
+    rtems_interrupt_lock_context lock_context;
+    rtems_interrupt_lock_acquire( &lock, &lock_context );
+    /* Some critical stuff \*/
+    rtems_interrupt_lock_release( &lock, &lock_context );
+    }
+
+The ``rtems_interrupt_lock`` structure is empty on uni-processor
+configurations.  Empty structures have a different size in C
+(implementation-defined, zero in case of GCC) and C++ (implementation-defined
+non-zero value, one in case of GCC).  Thus the``RTEMS_INTERRUPT_LOCK_DECLARE()``, ``RTEMS_INTERRUPT_LOCK_DEFINE()``,``RTEMS_INTERRUPT_LOCK_MEMBER()``, and``RTEMS_INTERRUPT_LOCK_REFERENCE()`` macros are provided to ensure ABI
+compatibility.
+
+Highest Priority Task Assumption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On a uniprocessor system, it is safe to assume that when the highest
+priority task in an application executes, it will execute without being
+preempted until it voluntarily blocks. Interrupts may occur while it is
+executing, but there will be no context switch to another task unless
+the highest priority task voluntarily initiates it.
+
+Given the assumption that no other tasks will have their execution
+interleaved with the highest priority task, it is possible for this
+task to be constructed such that it does not need to acquire a binary
+semaphore or mutex for protected access to shared data.
+
+In an SMP system, it cannot be assumed there will never be a single task
+executing. It should be assumed that every processor is executing another
+application task. Further, those tasks will be ones which would not have
+been executed in a uniprocessor configuration and should be assumed to
+have data synchronization conflicts with what was formerly the highest
+priority task which executed without conflict.
+
+Disable Preemption
+~~~~~~~~~~~~~~~~~~
+
+On a uniprocessor system, disabling preemption in a task is very similar
+to making the highest priority task assumption. While preemption is
+disabled, no task context switches will occur unless the task initiates
+them voluntarily. And, just as with the highest priority task assumption,
+there are N-1 processors also running tasks. Thus the assumption that no
+other tasks will run while the task has preemption disabled is violated.
+
+Task Unique Data and SMP
+------------------------
+
+Per task variables are a service commonly provided by real-time operating
+systems for application use. They work by allowing the application
+to specify a location in memory (typically a ``void *``) which is
+logically added to the context of a task. On each task switch, the
+location in memory is stored and each task can have a unique value in
+the same memory location. This memory location is directly accessed as a
+variable in a program.
+
+This works well in a uniprocessor environment because there is one task
+executing and one memory location containing a task-specific value. But
+it is fundamentally broken on an SMP system because there are always N
+tasks executing. With only one location in memory, N-1 tasks will not
+have the correct value.
+
+This paradigm for providing task unique data values is fundamentally
+broken on SMP systems.
+
+Classic API Per Task Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Classic API provides three directives to support per task variables. These are:
+
+- ``rtems.task_variable_add`` - Associate per task variable
+
+- ``rtems.task_variable_get`` - Obtain value of a a per task variable
+
+- ``rtems.task_variable_delete`` - Remove per task variable
+
+As task variables are unsafe for use on SMP systems, the use of these services
+must be eliminated in all software that is to be used in an SMP environment.
+The task variables API is disabled on SMP. Its use will lead to compile-time
+and link-time errors. It is recommended that the application developer consider
+the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys are available
+in all RTEMS configurations.  For the availablity of TLS on a particular
+architecture please consult the *RTEMS CPU Architecture Supplement*.
+
+The only remaining user of task variables in the RTEMS code base is the Ada
+support.  So basically Ada is not available on RTEMS SMP.
+
+OpenMP
+------
+
+OpenMP support for RTEMS is available via the GCC provided libgomp.  There is
+libgomp support for RTEMS in the POSIX configuration of libgomp since GCC 4.9
+(requires a Newlib snapshot after 2015-03-12). In GCC 6.1 or later (requires a
+Newlib snapshot after 2015-07-30 for <sys/lock.h> provided self-contained
+synchronization objects) there is a specialized libgomp configuration for RTEMS
+which offers a significantly better performance compared to the POSIX
+configuration of libgomp.  In addition application configurable thread pools
+for each scheduler instance are available in GCC 6.1 or later.
+
+The run-time configuration of libgomp is done via environment variables
+documented in the `libgomp
+manual <https://gcc.gnu.org/onlinedocs/libgomp/>`_.  The environment variables are evaluated in a constructor function
+which executes in the context of the first initialization task before the
+actual initialization task function is called (just like a global C++
+constructor).  To set application specific values, a higher priority
+constructor function must be used to set up the environment variables.
+.. code:: c
+
+    #include <stdlib.h>
+    void __attribute__((constructor(1000))) config_libgomp( void )
+    {
+    setenv( "OMP_DISPLAY_ENV", "VERBOSE", 1 );
+    setenv( "GOMP_SPINCOUNT", "30000", 1 );
+    setenv( "GOMP_RTEMS_THREAD_POOLS", "1$2@SCHD", 1 );
+    }
+
+The environment variable ``GOMP_RTEMS_THREAD_POOLS`` is RTEMS-specific.  It
+determines the thread pools for each scheduler instance.  The format for``GOMP_RTEMS_THREAD_POOLS`` is a list of optional``<thread-pool-count>[$<priority>]@<scheduler-name>`` configurations
+separated by ``:`` where:
+
+- ``<thread-pool-count>`` is the thread pool count for this scheduler
+  instance.
+
+- ``$<priority>`` is an optional priority for the worker threads of a
+  thread pool according to ``pthread_setschedparam``.  In case a priority
+  value is omitted, then a worker thread will inherit the priority of the OpenMP
+  master thread that created it.  The priority of the worker thread is not
+  changed by libgomp after creation, even if a new OpenMP master thread using the
+  worker has a different priority.
+
+- ``@<scheduler-name>`` is the scheduler instance name according to the
+  RTEMS application configuration.
+
+In case no thread pool configuration is specified for a scheduler instance,
+then each OpenMP master thread of this scheduler instance will use its own
+dynamically allocated thread pool.  To limit the worker thread count of the
+thread pools, each OpenMP master thread must call ``omp_set_num_threads``.
+
+Lets suppose we have three scheduler instances ``IO``, ``WRK0``, and``WRK1`` with ``GOMP_RTEMS_THREAD_POOLS`` set to``"1@WRK0:3$4@WRK1"``.  Then there are no thread pool restrictions for
+scheduler instance ``IO``.  In the scheduler instance ``WRK0`` there is
+one thread pool available.  Since no priority is specified for this scheduler
+instance, the worker thread inherits the priority of the OpenMP master thread
+that created it.  In the scheduler instance ``WRK1`` there are three thread
+pools available and their worker threads run at priority four.
+
+Thread Dispatch Details
+-----------------------
+
+This section gives background information to developers interested in the
+interrupt latencies introduced by thread dispatching.  A thread dispatch
+consists of all work which must be done to stop the currently executing thread
+on a processor and hand over this processor to an heir thread.
+
+On SMP systems, scheduling decisions on one processor must be propagated to
+other processors through inter-processor interrupts.  So, a thread dispatch
+which must be carried out on another processor happens not instantaneous.  Thus
+several thread dispatch requests might be in the air and it is possible that
+some of them may be out of date before the corresponding processor has time to
+deal with them.  The thread dispatch mechanism uses three per-processor
+variables,
+
+- the executing thread,
+
+- the heir thread, and
+
+- an boolean flag indicating if a thread dispatch is necessary or not.
+
+Updates of the heir thread and the thread dispatch necessary indicator are
+synchronized via explicit memory barriers without the use of locks.  A thread
+can be an heir thread on at most one processor in the system.  The thread context
+is protected by a TTAS lock embedded in the context to ensure that it is used
+on at most one processor at a time.  The thread post-switch actions use a
+per-processor lock.  This implementation turned out to be quite efficient and
+no lock contention was observed in the test suite.
+
+The current implementation of thread dispatching has some implications with
+respect to the interrupt latency.  It is crucial to preserve the system
+invariant that a thread can execute on at most one processor in the system at a
+time.  This is accomplished with a boolean indicator in the thread context.
+The processor architecture specific context switch code will mark that a thread
+context is no longer executing and waits that the heir context stopped
+execution before it restores the heir context and resumes execution of the heir
+thread (the boolean indicator is basically a TTAS lock).  So, there is one
+point in time in which a processor is without a thread.  This is essential to
+avoid cyclic dependencies in case multiple threads migrate at once.  Otherwise
+some supervising entity is necessary to prevent deadlocks.  Such a global
+supervisor would lead to scalability problems so this approach is not used.
+Currently the context switch is performed with interrupts disabled.  Thus in
+case the heir thread is currently executing on another processor, the time of
+disabled interrupts is prolonged since one processor has to wait for another
+processor to make progress.
+
+It is difficult to avoid this issue with the interrupt latency since interrupts
+normally store the context of the interrupted thread on its stack.  In case a
+thread is marked as not executing, we must not use its thread stack to store
+such an interrupt context.  We cannot use the heir stack before it stopped
+execution on another processor.  If we enable interrupts during this
+transition, then we have to provide an alternative thread independent stack for
+interrupts in this time frame.  This issue needs further investigation.
+
+The problematic situation occurs in case we have a thread which executes with
+thread dispatching disabled and should execute on another processor (e.g. it is
+an heir thread on another processor).  In this case the interrupts on this
+other processor are disabled until the thread enables thread dispatching and
+starts the thread dispatch sequence.  The scheduler (an exception is the
+scheduler with thread processor affinity support) tries to avoid such a
+situation and checks if a new scheduled thread already executes on a processor.
+In case the assigned processor differs from the processor on which the thread
+already executes and this processor is a member of the processor set managed by
+this scheduler instance, it will reassign the processors to keep the already
+executing thread in place.  Therefore normal scheduler requests will not lead
+to such a situation.  Explicit thread migration requests, however, can lead to
+this situation.  Explicit thread migrations may occur due to the scheduler
+helping protocol or explicit scheduler instance changes.  The situation can
+also be provoked by interrupts which suspend and resume threads multiple times
+and produce stale asynchronous thread dispatch requests in the system.
+
+Operations
+==========
+
+Setting Affinity to a Single Processor
+--------------------------------------
+
+On some embedded applications targeting SMP systems, it may be beneficial to
+lock individual tasks to specific processors.  In this way, one can designate a
+processor for I/O tasks, another for computation, etc..  The following
+illustrates the code sequence necessary to assign a task an affinity for
+processor with index ``processor_index``.
+.. code:: c
+
+    #include <rtems.h>
+    #include <assert.h>
+    void pin_to_processor(rtems_id task_id, int processor_index)
+    {
+    rtems_status_code sc;
+    cpu_set_t         cpuset;
+    CPU_ZERO(&cpuset);
+    CPU_SET(processor_index, &cpuset);
+    sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset);
+    assert(sc == RTEMS_SUCCESSFUL);
+    }
+
+It is important to note that the ``cpuset`` is not validated until the``rtems.task_set_affinity`` call is made. At that point,
+it is validated against the current system configuration.
+
+Directives
+==========
+
+This section details the symmetric multiprocessing services.  A subsection
+is dedicated to each of these services and describes the calling sequence,
+related constants, usage, and status codes.
+
+.. COMMENT: rtems_get_processor_count
+
+GET_PROCESSOR_COUNT - Get processor count
+-----------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+The count of processors in the system.
+
+**DESCRIPTION:**
+
+On uni-processor configurations a value of one will be returned.
+
+On SMP configurations this returns the value of a global variable set during
+system initialization to indicate the count of utilized processors.  The
+processor count depends on the physically or virtually available processors and
+application configuration.  The value will always be less than or equal to the
+maximum count of application configured processors.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: rtems_get_current_processor
+
+GET_CURRENT_PROCESSOR - Get current processor index
+---------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+The index of the current processor.
+
+**DESCRIPTION:**
+
+On uni-processor configurations a value of zero will be returned.
+
+On SMP configurations an architecture specific method is used to obtain the
+index of the current processor in the system.  The set of processor indices is
+the range of integers starting with zero up to the processor count minus one.
+
+Outside of sections with disabled thread dispatching the current processor
+index may change after every instruction since the thread may migrate from one
+processor to another.  Sections with disabled interrupts are sections with
+thread dispatching disabled.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: rtems_scheduler_ident
+
+.. _Symmetric-Multiprocessing-Services-SCHEDULER_005fIDENT-_002d-Get-ID-of-a-scheduler:
+
+SCHEDULER_IDENT - Get ID of a scheduler
+---------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
+``RTEMS.INVALID_NAME`` - invalid scheduler name
+``RTEMS.UNSATISFIED`` - - a scheduler with this name exists, but
+the processor set of this scheduler is empty
+
+**DESCRIPTION:**
+
+Identifies a scheduler by its name.  The scheduler name is determined by the
+scheduler configuration.  See :ref:`Configuring a System Configuring Clustered
+Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: rtems_scheduler_get_processor_set
+
+SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
+--------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ADDRESS`` - ``cpuset`` is NULL
+``RTEMS.INVALID_ID`` - invalid scheduler id
+``RTEMS.INVALID_NUMBER`` - the affinity set buffer is too small for
+set of processors owned by the scheduler
+
+**DESCRIPTION:**
+
+Returns the processor set owned by the scheduler in ``cpuset``.  A set bit
+in the processor set means that this processor is owned by the scheduler and a
+cleared bit means the opposite.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: rtems_task_get_scheduler
+
+TASK_GET_SCHEDULER - Get scheduler of a task
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ADDRESS`` - ``scheduler_id`` is NULL
+``RTEMS.INVALID_ID`` - invalid task id
+
+**DESCRIPTION:**
+
+Returns the scheduler identifier of a task identified by ``task_id`` in``scheduler_id``.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: rtems_task_set_scheduler
+
+.. _Symmetric-Multiprocessing-Services-TASK_005fSET_005fSCHEDULER-_002d-Set-scheduler-of-a-task:
+
+TASK_SET_SCHEDULER - Set scheduler of a task
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ID`` - invalid task or scheduler id
+``RTEMS.INCORRECT_STATE`` - the task is in the wrong state to
+perform a scheduler change
+
+**DESCRIPTION:**
+
+Sets the scheduler of a task identified by ``task_id`` to the scheduler
+identified by ``scheduler_id``.  The scheduler of a task is initialized to
+the scheduler of the task that created it.
+
+**NOTES:**
+
+None.
+
+**EXAMPLE:**
+
+.. code:: c
+
+    #include <rtems.h>
+    #include <assert.h>
+    void task(rtems_task_argument arg);
+    void example(void)
+    {
+    rtems_status_code sc;
+    rtems_id          task_id;
+    rtems_id          scheduler_id;
+    rtems_name        scheduler_name;
+    scheduler_name = rtems_build_name('W', 'O', 'R', 'K');
+    sc = rtems_scheduler_ident(scheduler_name, &scheduler_id);
+    assert(sc == RTEMS_SUCCESSFUL);
+    sc = rtems_task_create(
+    rtems_build_name('T', 'A', 'S', 'K'),
+    1,
+    RTEMS_MINIMUM_STACK_SIZE,
+    RTEMS_DEFAULT_MODES,
+    RTEMS_DEFAULT_ATTRIBUTES,
+    &task_id
+    );
+    assert(sc == RTEMS_SUCCESSFUL);
+    sc = rtems_task_set_scheduler(task_id, scheduler_id);
+    assert(sc == RTEMS_SUCCESSFUL);
+    sc = rtems_task_start(task_id, task, 0);
+    assert(sc == RTEMS_SUCCESSFUL);
+    }
+
+.. COMMENT: rtems_task_get_affinity
+
+TASK_GET_AFFINITY - Get task processor affinity
+-----------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ADDRESS`` - ``cpuset`` is NULL
+``RTEMS.INVALID_ID`` - invalid task id
+``RTEMS.INVALID_NUMBER`` - the affinity set buffer is too small for
+the current processor affinity set of the task
+
+**DESCRIPTION:**
+
+Returns the current processor affinity set of the task in ``cpuset``.  A set
+bit in the affinity set means that the task can execute on this processor and a
+cleared bit means the opposite.
+
+**NOTES:**
+
+None.
+
+.. COMMENT: rtems_task_set_affinity
+
+TASK_SET_AFFINITY - Set task processor affinity
+-----------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.SUCCESSFUL`` - successful operation
+``RTEMS.INVALID_ADDRESS`` - ``cpuset`` is NULL
+``RTEMS.INVALID_ID`` - invalid task id
+``RTEMS.INVALID_NUMBER`` - invalid processor affinity set
+
+**DESCRIPTION:**
+
+Sets the processor affinity set for the task specified by ``cpuset``.  A set
+bit in the affinity set means that the task can execute on this processor and a
+cleared bit means the opposite.
+
+**NOTES:**
+
+This function will not change the scheduler of the task.  The intersection of
+the processor affinity set and the set of processors owned by the scheduler of
+the task must be non-empty.  It is not an error if the processor affinity set
+contains processors that are not part of the set of processors owned by the
+scheduler instance of the task.  A task will simply not run under normal
+circumstances on these processors since the scheduler ignores them.  Some
+locking protocols may temporarily use processors that are not included in the
+processor affinity set of the task.  It is also not an error if the processor
+affinity set contains processors that are not part of the system.
+
+.. COMMENT: COPYRIGHT (c) 2011,2015
+
+.. COMMENT: Aeroflex Gaisler AB
+
+.. COMMENT: All rights reserved.
+
+PCI Library
+###########
+
+.. index:: libpci
+
+Introduction
+============
+
+The Peripheral Component Interconnect (PCI) bus is a very common computer
+bus architecture that is found in almost every PC today. The PCI bus is
+normally located at the motherboard where some PCI devices are soldered
+directly onto the PCB and expansion slots allows the user to add custom
+devices easily. There is a wide range of PCI hardware available implementing
+all sorts of interfaces and functions.
+
+This section describes the PCI Library available in RTEMS used to access the
+PCI bus in a portable way across computer architectures supported by RTEMS.
+
+The PCI Library aims to be compatible with PCI 2.3 with a couple of
+limitations, for example there is no support for hot-plugging, 64-bit
+memory space and cardbus bridges.
+
+In order to support different architectures and with small foot-print embedded
+systems in mind the PCI Library offers four different configuration options
+listed below. It is selected during compile time by defining the appropriate
+macros in confdefs.h. It is also possible to enable PCI_LIB_NONE (No
+Configuration) which can be used for debuging PCI access functions.
+
+- Auto Configuration (do Plug & Play)
+
+- Read Configuration (read BIOS or boot loader configuration)
+
+- Static Configuration (write user defined configuration)
+
+- Peripheral Configuration (no access to cfg-space)
+
+Background
+==========
+
+The PCI bus is constructed in a way where on-board devices and devices
+in expansion slots can be automatically found (probed) and configured
+using Plug & Play completely implemented in software. The bus is set up once
+during boot up. The Plug & Play information can be read and written from
+PCI configuration space. A PCI device is identified in configuration space by
+a unique bus, slot and function number. Each PCI slot can have up to 8
+functions and interface to another PCI sub-bus by implementing a PCI-to-PCI
+bridge according to the PCI Bridge Architecture specification.
+
+Using the unique \[bus:slot:func] any device can be configured regardless of how
+PCI is currently set up as long as all PCI buses are enumerated correctly. The
+enumeration is done during probing, all bridges are given a bus number in
+order for the bridges to respond to accesses from both directions. The PCI
+library can assign address ranges to which a PCI device should respond using
+Plug & Play technique or a static user defined configuration. After the
+configuration has been performed the PCI device drivers can find devices by
+the read-only PCI Class type, Vendor ID and Device ID information found in
+configuration space for each device.
+
+In some systems there is a boot loader or BIOS which have already configured
+all PCI devices, but on embedded targets it is quite common that there is no
+BIOS or boot loader, thus RTEMS must configure the PCI bus. Only the PCI host
+may do configuration space access, the host driver or BSP is responsible to
+translate the \[bus:slot:func] into a valid PCI configuration space access.
+
+If the target is not a host, but a peripheral, configuration space can not be
+accessed, the peripheral is set up by the host during start up. In complex
+embedded PCI systems the peripheral may need to access other PCI boards than
+the host. In such systems a custom (static) configuration of both the host
+and peripheral may be a convenient solution.
+
+The PCI bus defines four interrupt signals INTA#..INTD#. The interrupt signals
+must be mapped into a system interrupt/vector, it is up to the BSP or host
+driver to know the mapping, however the BIOS or boot loader may use the
+8-bit read/write "Interrupt Line" register to pass the knowledge along to the
+OS.
+
+The PCI standard defines and recommends that the backplane route the interupt
+lines in a systematic way, however in standard there is no such requirement.
+The PCI Auto Configuration Library implements the recommended way of routing
+which is very common but it is also supported to some extent to override the
+interrupt routing from the BSP or Host Bridge driver using the configuration
+structure.
+
+Software Components
+-------------------
+
+The PCI library is located in cpukit/libpci, it consists of different parts:
+
+- PCI Host bridge driver interface
+
+- Configuration routines
+
+- Access (Configuration, I/O and Memory space) routines
+
+- Interrupt routines (implemented by BSP)
+
+- Print routines
+
+- Static/peripheral configuration creation
+
+- PCI shell command
+
+PCI Configuration
+-----------------
+
+During start up the PCI bus must be configured in order for host and
+peripherals to access one another using Memory or I/O accesses and that
+interrupts are properly handled. Three different spaces are defined and
+mapped separately:
+
+# I/O space (IO)
+
+# non-prefetchable Memory space (MEMIO)
+
+# prefetchable Memory space (MEM)
+
+Regions of the same type (I/O or Memory) may not overlap which is guaranteed
+by the software. MEM regions may be mapped into MEMIO regions, but MEMIO
+regions can not be mapped into MEM, for that could lead to prefetching of
+registers. The interrupt pin which a board is driving can be read out from
+PCI configuration space, however it is up to software to know how interrupt
+signals are routed between PCI-to-PCI bridges and how PCI INT[A..D]# pins are
+mapped to system IRQ. In systems where previous software (boot loader or BIOS)
+has already set up this the configuration is overwritten or simply read out.
+
+In order to support different configuration methods the following configuration
+libraries are selectable by the user:
+
+- Auto Configuration (run Plug & Play software)
+
+- Read Configuration (relies on a boot loader or BIOS)
+
+- Static Configuration (write user defined setup, no Plug & Play)
+
+- Peripheral Configuration (user defined setup, no access to
+  configuration space)
+
+A host driver can be made to support all three configuration methods, or any
+combination. It may be defined by the BSP which approach is used.
+
+The configuration software is called from the PCI driver (pci_config_init()).
+
+Regardless of configuration method a PCI device tree is created in RAM during
+initialization, the tree can be accessed to find devices and resources without
+accessing configuration space later on. The user is responsible to create the
+device tree at compile time when using the static/peripheral method.
+
+RTEMS Configuration selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The active configuration method can be selected at compile time in the same
+way as other project parameters by including rtems/confdefs.h and setting
+
+- CONFIGURE_INIT
+
+- RTEMS_PCI_CONFIG_LIB
+
+- CONFIGURE_PCI_LIB = PCI_LIB_(AUTO,STATIC,READ,PERIPHERAL)
+
+See the RTEMS configuration section how to setup the PCI library.
+
+Auto Configuration
+~~~~~~~~~~~~~~~~~~
+
+The auto configuration software enumerates PCI buses and initializes all PCI
+devices found using Plug & Play. The auto configuration software requires
+that a configuration setup has been registered by the driver or BSP in order
+to setup the I/O and Memory regions at the correct address ranges. PCI
+interrupt pins can optionally be routed over PCI-to-PCI bridges and mapped
+to a system interrupt number. BAR resources are sorted by size and required
+alignment, unused "dead" space may be created when PCI bridges are present
+due to the PCI bridge window size does not equal the alignment. To cope with
+that resources are reordered to fit smaller BARs into the dead space to minimize
+the PCI space required. If a BAR or ROM register can not be allocated a PCI
+address region (due to too few resources available) the register will be given
+the value of pci_invalid_address which defaults to 0.
+
+The auto configuration routines support:
+
+- PCI 2.3
+
+- Little and big endian PCI bus
+
+- one I/O 16 or 32-bit range (IO)
+
+- memory space (MEMIO)
+
+- prefetchable memory space (MEM), if not present MEM will be mapped into
+  MEMIO
+
+- multiple PCI buses - PCI-to-PCI bridges
+
+- standard BARs, PCI-to-PCI bridge BARs, ROM BARs
+
+- Interrupt routing over bridges
+
+- Interrupt pin to system interrupt mapping
+
+Not supported:
+
+- hot-pluggable devices
+
+- Cardbus bridges
+
+- 64-bit memory space
+
+- 16-bit and 32-bit I/O address ranges at the same time
+
+In PCI 2.3 there may exist I/O BARs that must be located at the low 64kBytes
+address range, in order to support this the host driver or BSP must make sure
+that I/O addresses region is within this region.
+
+Read Configuration
+~~~~~~~~~~~~~~~~~~
+
+When a BIOS or boot loader already has setup the PCI bus the configuration can
+be read directly from the PCI resource registers and buses are already
+enumerated, this is a much simpler approach than configuring PCI ourselves. The
+PCI device tree is automatically created based on the current configuration and
+devices present. After initialization is done there is no difference between
+the auto or read configuration approaches.
+
+Static Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+To support custom configurations and small-footprint PCI systems, the user may
+provide the PCI device tree which contains the current configuration. The
+PCI buses are enumerated and all resources are written to PCI devices during
+initialization. When this approach is selected PCI boards must be located at
+the same slots every time and devices can not be removed or added, Plug & Play
+is not performed. Boards of the same type may of course be exchanged.
+
+The user can create a configuration by calling pci_cfg_print() on a running
+system that has had PCI setup by the auto or read configuration routines, it
+can be called from the PCI shell command. The user must provide the PCI device
+tree named pci_hb.
+
+Peripheral Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+On systems where a peripheral PCI device needs to access other PCI devices than
+the host the peripheral configuration approach may be handy. Most PCI devices
+answers on the PCI hostâs requests and start DMA accesses into the Hosts memory,
+however in some complex systems PCI devices may want to access other devices
+on the same bus or at another PCI bus.
+
+A PCI peripheral is not allowed to do PCI configuration cycles, which
+means that it must either rely on the host to give it the addresses it
+needs, or that the addresses are predefined.
+
+This configuration approach is very similar to the static option, however the
+configuration is never written to PCI bus, instead it is only used for drivers
+to find PCI devices and resources using the same PCI API as for the host
+
+PCI Access
+----------
+
+The PCI access routines are low-level routines provided for drivers,
+configuration software, etc. in order to access different regions in a way
+not dependent upon the host driver, BSP or platform.
+
+- PCI configuration space
+
+- PCI I/O space
+
+- Registers over PCI memory space
+
+- Translate PCI address into CPU accessible address and vice versa
+
+By using the access routines drivers can be made portable over different
+architectures. The access routines take the architecture endianness into
+consideration and let the host driver or BSP implement I/O space and
+configuration space access.
+
+Some non-standard hardware may also define the PCI bus big-endian, for example
+the LEON2 AT697 PCI host bridge and some LEON3 systems may be configured that
+way. It is up to the BSP to set the appropriate PCI endianness on compile time
+(BSP_PCI_BIG_ENDIAN) in order for inline macros to be correctly defined.
+Another possibility is to use the function pointers defined by the access
+layer to implement drivers that support "run-time endianness detection".
+
+Configuration space
+~~~~~~~~~~~~~~~~~~~
+
+Configuration space is accessed using the routines listed below. The
+pci_dev_t type is used to specify a specific PCI bus, device and function. It
+is up to the host driver or BSP to create a valid access to the requested
+PCI slot. Requests made to slots that are not supported by hardware should
+result in PCISTS_MSTABRT and/or data must be ignored (writes) or 0xffffffff
+is always returned (reads).
+.. code:: c
+
+    /* Configuration Space Access Read Routines \*/
+    extern int pci_cfg_r8(pci_dev_t dev, int ofs, uint8_t \*data);
+    extern int pci_cfg_r16(pci_dev_t dev, int ofs, uint16_t \*data);
+    extern int pci_cfg_r32(pci_dev_t dev, int ofs, uint32_t \*data);
+    /* Configuration Space Access Write Routines \*/
+    extern int pci_cfg_w8(pci_dev_t dev, int ofs, uint8_t data);
+    extern int pci_cfg_w16(pci_dev_t dev, int ofs, uint16_t data);
+    extern int pci_cfg_w32(pci_dev_t dev, int ofs, uint32_t data);
+
+I/O space
+~~~~~~~~~
+
+The BSP or driver provide special routines in order to access I/O space. Some
+architectures have a special instruction accessing I/O space, others have it
+mapped into a "PCI I/O window" in the standard address space accessed by the
+CPU. The window size may vary and must be taken into consideration by the
+host driver. The below routines must be used to access I/O space. The address
+given to the functions is not the PCI I/O addresses, the caller must have
+translated PCI I/O addresses (available in the PCI BARs) into a BSP or host
+driver custom address, see :ref:`PCI Library Access functions <PCI-Library-Access-functions>` for how
+addresses are translated.
+.. code:: c
+
+    /* Read a register over PCI I/O Space \*/
+    extern uint8_t pci_io_r8(uint32_t adr);
+    extern uint16_t pci_io_r16(uint32_t adr);
+    extern uint32_t pci_io_r32(uint32_t adr);
+    /* Write a register over PCI I/O Space \*/
+    extern void pci_io_w8(uint32_t adr, uint8_t data);
+    extern void pci_io_w16(uint32_t adr, uint16_t data);
+    extern void pci_io_w32(uint32_t adr, uint32_t data);
+
+Registers over Memory space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PCI host bridge hardware normally swap data accesses into the endianness of the
+host architecture in order to lower the load of the CPU, peripherals can do DMA
+without swapping. However, the host controller can not separate a standard
+memory access from a memory access to a register, registers may be mapped into
+memory space. This leads to register content being swapped, which must be
+swapped back. The below routines makes it possible to access registers over PCI
+memory space in a portable way on different architectures, the BSP or
+architecture must provide necessary functions in order to implement this.
+.. code:: c
+
+    static inline uint16_t pci_ld_le16(volatile uint16_t \*addr);
+    static inline void pci_st_le16(volatile uint16_t \*addr, uint16_t val);
+    static inline uint32_t pci_ld_le32(volatile uint32_t \*addr);
+    static inline void pci_st_le32(volatile uint32_t \*addr, uint32_t val);
+    static inline uint16_t pci_ld_be16(volatile uint16_t \*addr);
+    static inline void pci_st_be16(volatile uint16_t \*addr, uint16_t val);
+    static inline uint32_t pci_ld_be32(volatile uint32_t \*addr);
+    static inline void pci_st_be32(volatile uint32_t \*addr, uint32_t val);
+
+In order to support non-standard big-endian PCI bus the above pci_* functions
+is required, pci_ld_le16 != ld_le16 on big endian PCI buses.
+
+.. _PCI-Library-Access-functions:
+
+Access functions
+~~~~~~~~~~~~~~~~
+
+The PCI Access Library can provide device drivers with function pointers
+executing the above Configuration, I/O and Memory space accesses. The
+functions have the same arguments and return values as the above
+functions.
+
+The pci_access_func() function defined below can be used to get a function
+pointer of a specific access type.
+.. code:: c
+
+    /* Get Read/Write function for accessing a register over PCI Memory Space
+    * (non-inline functions).
+    *
+    * Arguments
+    *  wr             0(Read), 1(Write)
+    *  size           1(Byte), 2(Word), 4(Double Word)
+    *  func           Where function pointer will be stored
+    *  endian         PCI_LITTLE_ENDIAN or PCI_BIG_ENDIAN
+    *  type           1(I/O), 3(REG over MEM), 4(CFG)
+    *
+    * Return
+    *  0              Found function
+    *  others         No such function defined by host driver or BSP
+    \*/
+    int pci_access_func(int wr, int size, void \**func, int endian, int type);
+
+PCI device drivers may be written to support run-time detection of endianess,
+this is mosly for debugging or for development systems. When the product is
+finally deployed macros switch to using the inline functions instead which
+have been configured for the correct endianness.
+
+PCI address translation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When PCI addresses, both I/O and memory space, is not mapped 1:1 address
+translation before access is needed. If drivers read the PCI resources directly
+using configuration space routines or in the device tree, the addresses given
+are PCI addresses. The below functions can be used to translate PCI addresses
+into CPU accessible addresses or vice versa, translation may be different for
+different PCI spaces/regions.
+.. code:: c
+
+    /* Translate PCI address into CPU accessible address \*/
+    static inline int pci_pci2cpu(uint32_t \*address, int type);
+    /* Translate CPU accessible address into PCI address (for DMA) \*/
+    static inline int pci_cpu2pci(uint32_t \*address, int type);
+
+PCI Interrupt
+-------------
+
+The PCI specification defines four different interrupt lines INTA#..INTD#,
+the interrupts are low level sensitive which make it possible to support
+multiple interrupt sources on the same interrupt line. Since the lines are
+level sensitive the interrupt sources must be acknowledged before clearing the
+interrupt contoller, or the interrupt controller must be masked. The BSP must
+provide a routine for clearing/acknowledging the interrupt controller, it is
+up to the interrupt service routine to acknowledge the interrupt source.
+
+The PCI Library relies on the BSP for implementing shared interrupt handling
+through the BSP_PCI_shared_interrupt_* functions/macros, they must be defined
+when including bsp.h.
+
+PCI device drivers may use the pci_interrupt_ routines in order to call the
+BSP specific functions in a platform independent way. The PCI interrupt
+interface has been made similar to the RTEMS IRQ extension so that a BSP can
+use the standard RTEMS interrupt functions directly.
+
+PCI Shell command
+-----------------
+
+The RTEMS shell has a PCI command âpciâ which makes it possible to read/write
+configuration space, print the current PCI configuration and print out a
+configuration C-file for the static or peripheral library.
+
+.. COMMENT: COPYRIGHT (c) 1988-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Stack Bounds Checker
+####################
+
+Introduction
+============
+
+The stack bounds checker is an RTEMS support component that determines
+if a task has overrun its run-time stack.  The routines provided
+by the stack bounds checker manager are:
+
+- ``rtems.stack_checker_is_blown`` - Has the Current Task Blown its Stack
+
+- ``rtems.stack_checker_report_usage`` - Report Task Stack Usage
+
+Background
+==========
+
+Task Stack
+----------
+
+Each task in a system has a fixed size stack associated with it.  This
+stack is allocated when the task is created.  As the task executes, the
+stack is used to contain parameters, return addresses, saved registers,
+and local variables.  The amount of stack space required by a task
+is dependent on the exact set of routines used.  The peak stack usage
+reflects the worst case of subroutine pushing information on the stack.
+For example, if a subroutine allocates a local buffer of 1024 bytes, then
+this data must be accounted for in the stack of every task that invokes that
+routine.
+
+Recursive routines make calculating peak stack usage difficult, if not
+impossible.  Each call to the recursive routine consumes *n* bytes
+of stack space.  If the routine recursives 1000 times, then``1000 * *n*`` bytes of stack space are required.
+
+Execution
+---------
+
+The stack bounds checker operates as a set of task extensions.  At
+task creation time, the taskâs stack is filled with a pattern to
+indicate the stack is unused.  As the task executes, it will overwrite
+this pattern in memory.  At each task switch, the stack bounds checkerâs
+task switch extension is executed.  This extension checks that:
+
+- the last ``n`` bytes of the taskâs stack have
+  not been overwritten.  If this pattern has been damaged, it
+  indicates that at some point since this task was context
+  switch to the CPU, it has used too much stack space.
+
+- the current stack pointer of the task is not within
+  the address range allocated for use as the taskâs stack.
+
+If either of these conditions is detected, then a blown stack
+error is reported using the ``printk`` routine.
+
+The number of bytes checked for an overwrite is processor family dependent.
+The minimum stack frame per subroutine call varies widely between processor
+families.  On CISC families like the Motorola MC68xxx and Intel ix86, all
+that is needed is a return address.  On more complex RISC processors,
+the minimum stack frame per subroutine call may include space to save
+a significant number of registers.
+
+Another processor dependent feature that must be taken into account by
+the stack bounds checker is the direction that the stack grows.  On some
+processor families, the stack grows up or to higher addresses as the
+task executes.  On other families, it grows down to lower addresses.  The
+stack bounds checker implementation uses the stack description definitions
+provided by every RTEMS port to get for this information.
+
+Operations
+==========
+
+Initializing the Stack Bounds Checker
+-------------------------------------
+
+The stack checker is initialized automatically when its task
+create extension runs for the first time.
+
+The application must include the stack bounds checker extension set
+in its set of Initial Extensions.  This set of extensions is
+defined as ``STACK_CHECKER_EXTENSION``.  If using ``<rtems/confdefs.h>``
+for Configuration Table generation, then all that is necessary is
+to define the macro ``CONFIGURE_STACK_CHECKER_ENABLED`` before including``<rtems/confdefs.h>`` as shown below:
+.. code:: c
+
+    #define CONFIGURE_STACK_CHECKER_ENABLED
+    ...
+    #include <rtems/confdefs.h>
+
+Checking for Blown Task Stack
+-----------------------------
+
+The application may check whether the stack pointer of currently
+executing task is within proper bounds at any time by calling
+the ``rtems.stack_checker_is_blown`` method.  This
+method return ``FALSE`` if the task is operating within its
+stack bounds and has not damaged its pattern area.
+
+Reporting Task Stack Usage
+--------------------------
+
+The application may dynamically report the stack usage for every task
+in the system by calling the``rtems.stack_checker_report_usage`` routine.
+This routine prints a table with the peak usage and stack size of
+every task in the system.  The following is an example of the
+report generated:
+.. code:: c
+
+    ID      NAME       LOW        HIGH     AVAILABLE      USED
+    0x04010001  IDLE  0x003e8a60  0x003e9667       2952        200
+    0x08010002  TA1   0x003e5750  0x003e7b57       9096       1168
+    0x08010003  TA2   0x003e31c8  0x003e55cf       9096       1168
+    0x08010004  TA3   0x003e0c40  0x003e3047       9096       1104
+    0xffffffff  INTR  0x003ecfc0  0x003effbf      12160        128
+
+Notice the last time.  The task id is 0xffffffff and its name is "INTR".
+This is not actually a task, it is the interrupt stack.
+
+When a Task Overflows the Stack
+-------------------------------
+
+When the stack bounds checker determines that a stack overflow has occurred,
+it will attempt to print a message using ``printk`` identifying the
+task and then shut the system down.  If the stack overflow has caused
+corruption, then it is possible that the message cannot be printed.
+
+The following is an example of the output generated:
+.. code:: c
+
+    BLOWN STACK!!! Offending task(0x3eb360): id=0x08010002; name=0x54413120
+    stack covers range 0x003e5750 - 0x003e7b57 (9224 bytes)
+    Damaged pattern begins at 0x003e5758 and is 128 bytes long
+
+The above includes the task id and a pointer to the task control block as
+well as enough information so one can look at the taskâs stack and
+see what was happening.
+
+Routines
+========
+
+This section details the stack bounds checkerâs routines.
+A subsection is dedicated to each of routines
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+.. COMMENT: rtems_stack_checker_is_blown
+
+STACK_CHECKER_IS_BLOWN - Has Current Task Blown Its Stack
+---------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Stack_Checker_Is_Blown return RTEMS.Boolean;
+
+**STATUS CODES:**
+
+``TRUE`` - Stack is operating within its stack limits
+``FALSE`` - Current stack pointer is outside allocated area
+
+**DESCRIPTION:**
+
+This method is used to determine if the current stack pointer
+of the currently executing task is within bounds.
+
+**NOTES:**
+
+This method checks the current stack pointer against
+the high and low addresses of the stack memory allocated when
+the task was created and it looks for damage to the high water
+mark pattern for the worst case usage of the task being called.
+
+STACK_CHECKER_REPORT_USAGE - Report Task Stack Usage
+----------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Stack_Checker_Report_Usage;
+
+**STATUS CODES: NONE**
+
+**DESCRIPTION:**
+
+This routine prints a table with the peak stack usage and stack space
+allocation of every task in the system.
+
+**NOTES:**
+
+NONE
+
+.. COMMENT: COPYRIGHT (c) 1988-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+CPU Usage Statistics
+####################
+
+Introduction
+============
+
+The CPU usage statistics manager is an RTEMS support
+component that provides a convenient way to manipulate
+the CPU usage information associated with each task
+The routines provided by the CPU usage statistics manager are:
+
+- ``rtems.cpu_usage_report`` - Report CPU Usage Statistics
+
+- ``rtems.cpu_usage_reset`` - Reset CPU Usage Statistics
+
+Background
+==========
+
+When analyzing and debugging real-time applications, it is important
+to be able to know how much CPU time each task in the system consumes.
+This support component provides a mechanism to easily obtain this
+information with little burden placed on the target.
+
+The raw data is gathered as part of performing a context switch.  RTEMS
+keeps track of how many clock ticks have occurred which the task being
+switched out has been executing.  If the task has been running less than
+1 clock tick, then for the purposes of the statistics, it is assumed to
+have executed 1 clock tick.  This results in some inaccuracy but the
+alternative is for the task to have appeared to execute 0 clock ticks.
+
+RTEMS versions newer than the 4.7 release series, support the ability
+to obtain timestamps with nanosecond granularity if the BSP provides
+support.  It is a desirable enhancement to change the way the usage
+data is gathered to take advantage of this recently added capability.
+Please consider sponsoring the core RTEMS development team to add
+this capability.
+
+Operations
+==========
+
+Report CPU Usage Statistics
+---------------------------
+
+The application may dynamically report the CPU usage for every
+task in the system by calling the``rtems.cpu_usage_report`` routine.
+This routine prints a table with the following information per task:
+
+- task id
+
+- task name
+
+- number of clock ticks executed
+
+- percentage of time consumed by this task
+
+The following is an example of the report generated:
+.. code:: c
+
+    -------------------------------------------------------------------------------
+    CPU USAGE BY THREAD
+    ------------+----------------------------------------+---------------+---------
+    ID         | NAME                                   | SECONDS       | PERCENT
+    ------------+----------------------------------------+---------------+---------
+    0x04010001 | IDLE                                   |             0 |   0.000
+    0x08010002 | TA1                                    |          1203 |   0.748
+    0x08010003 | TA2                                    |           203 |   0.126
+    0x08010004 | TA3                                    |           202 |   0.126
+    ------------+----------------------------------------+---------------+---------
+    TICKS SINCE LAST SYSTEM RESET:                                           1600
+    TOTAL UNITS:                                                             1608
+    -------------------------------------------------------------------------------
+
+Notice that the "TOTAL UNITS" is greater than the ticks per reset.
+This is an artifact of the way in which RTEMS keeps track of CPU
+usage.  When a task is context switched into the CPU, the number
+of clock ticks it has executed is incremented.  While the task
+is executing, this number is incremented on each clock tick.
+Otherwise, if a task begins and completes execution between
+successive clock ticks, there would be no way to tell that it
+executed at all.
+
+Another thing to keep in mind when looking at idle time, is that
+many systems â especially during debug â have a task providing
+some type of debug interface.  It is usually fine to think of the
+total idle time as being the sum of the IDLE task and a debug
+task that will not be included in a production build of an application.
+
+Reset CPU Usage Statistics
+--------------------------
+
+Invoking the ``rtems.cpu_usage_reset`` routine resets
+the CPU usage statistics for all tasks in the system.
+
+Directives
+==========
+
+This section details the CPU usage statistics 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.
+
+cpu_usage_report - Report CPU Usage Statistics
+----------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure CPU_Usage_Report;
+
+**STATUS CODES: NONE**
+
+**DESCRIPTION:**
+
+This routine prints out a table detailing the CPU usage statistics for
+all tasks in the system.
+
+**NOTES:**
+
+The table is printed using the ``printk`` routine.
+
+cpu_usage_reset - Reset CPU Usage Statistics
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure CPU_Usage_Reset;
+
+**STATUS CODES: NONE**
+
+**DESCRIPTION:**
+
+This routine re-initializes the CPU usage statistics for all tasks
+in the system to their initial state.  The initial state is that
+a task has not executed and thus has consumed no CPU time.
+default state which is when zero period executions have occurred.
+
+**NOTES:**
+
+NONE
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Object Services
+###############
+
+.. index:: object manipulation
+
+Introduction
+============
+
+RTEMS provides a collection of services to assist in the
+management and usage of the objects created and utilized
+via other managers.  These services assist in the
+manipulation of RTEMS objects independent of the API used
+to create them.  The object related services provided by
+RTEMS are:
+
+- build_id
+
+- ``rtems.build_name`` - build object name from characters
+
+- ``rtems.object_get_classic_name`` - lookup name from Id
+
+- ``rtems.object_get_name`` - obtain object name as string
+
+- ``rtems.object_set_name`` - set object name
+
+- ``rtems.object_id_get_api`` - obtain API from Id
+
+- ``rtems.object_id_get_class`` - obtain class from Id
+
+- ``rtems.object_id_get_node`` - obtain node from Id
+
+- ``rtems.object_id_get_index`` - obtain index from Id
+
+- ``rtems.build_id`` - build object id from components
+
+- ``rtems.object_id_api_minimum`` - obtain minimum API value
+
+- ``rtems.object_id_api_maximum`` - obtain maximum API value
+
+- ``rtems.object_id_api_minimum_class`` - obtain minimum class value
+
+- ``rtems.object_id_api_maximum_class`` - obtain maximum class value
+
+- ``rtems.object_get_api_name`` - obtain API name
+
+- ``rtems.object_get_api_class_name`` - obtain class name
+
+- ``rtems.object_get_class_information`` - obtain class information
+
+Background
+==========
+
+APIs
+----
+
+RTEMS implements multiple APIs including an Internal API,
+the Classic API, and the POSIX API.  These
+APIs share the common foundation of SuperCore objects and
+thus share object management code. This includes a common
+scheme for object Ids and for managing object names whether
+those names be in the thirty-two bit form used by the Classic
+API or C strings.
+
+The object Id contains a field indicating the API that
+an object instance is associated with.  This field
+holds a numerically small non-zero integer.
+
+Object Classes
+--------------
+
+Each API consists of a collection of managers.  Each manager
+is responsible for instances of a particular object class.
+Classic API Tasks and POSIX Mutexes example classes.
+
+The object Id contains a field indicating the class that
+an object instance is associated with.  This field
+holds a numerically small non-zero integer.  In all APIs,
+a class value of one is reserved for tasks or threads.
+
+Object Names
+------------
+
+Every RTEMS object which has an Id may also have a
+name associated with it.  Depending on the API, names
+may be either thirty-two bit integers as in the Classic
+API or strings as in the POSIX API.
+
+Some objects have Ids but do not have a defined way to associate
+a name with them.  For example, POSIX threads have
+Ids but per POSIX do not have names. In RTEMS, objects
+not defined to have thirty-two bit names may have string
+names assigned to them via the ``rtems.object_set_name``
+service.  The original impetus in providing this service
+was so the normally anonymous POSIX threads could have
+a user defined name in CPU Usage Reports.
+
+Operations
+==========
+
+Decomposing and Recomposing an Object Id
+----------------------------------------
+
+Services are provided to decompose an object Id into its
+subordinate components. The following services are used
+to do this:
+
+- ``rtems.object_id_get_api``
+
+- ``rtems.object_id_get_class``
+
+- ``rtems.object_id_get_node``
+
+- ``rtems.object_id_get_index``
+
+The following C language example illustrates the
+decomposition of an Id and printing the values.
+.. code:: c
+
+    void printObjectId(rtems_id id)
+    {
+    printf(
+    "API=%d Class=%d Node=%d Index=%d\\n",
+    rtems_object_id_get_api(id),
+    rtems_object_id_get_class(id),
+    rtems_object_id_get_node(id),
+    rtems_object_id_get_index(id)
+    );
+    }
+
+This prints the components of the Ids as integers.
+
+It is also possible to construct an arbitrary Id using
+the ``rtems.build_id`` service.  The following
+C language example illustrates how to construct the
+"next Id."
+.. code:: c
+
+    rtems_id nextObjectId(rtems_id id)
+    {
+    return rtems_build_id(
+    rtems_object_id_get_api(id),
+    rtems_object_id_get_class(id),
+    rtems_object_id_get_node(id),
+    rtems_object_id_get_index(id) + 1
+    );
+    }
+
+Note that this Id may not be valid in this
+system or associated with an allocated object.
+
+Printing an Object Id
+---------------------
+
+RTEMS also provides services to associate the API and Class
+portions of an Object Id with strings.  This allows the
+application developer to provide more information about
+an object in diagnostic messages.
+
+In the following C language example, an Id is decomposed into
+its constituent parts and "pretty-printed."
+.. code:: c
+
+    void prettyPrintObjectId(rtems_id id)
+    {
+    int tmpAPI, tmpClass;
+    tmpAPI   = rtems_object_id_get_api(id),
+    tmpClass = rtems_object_id_get_class(id),
+    printf(
+    "API=%s Class=%s Node=%d Index=%d\\n",
+    rtems_object_get_api_name(tmpAPI),
+    rtems_object_get_api_class_name(tmpAPI, tmpClass),
+    rtems_object_id_get_node(id),
+    rtems_object_id_get_index(id)
+    );
+    }
+
+Directives
+==========
+
+BUILD_NAME - Build object name from characters
+----------------------------------------------
+.. index:: build object name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Build_Name(
+    c1   : in     RTEMS.Unsigned8;
+    c2   : in     RTEMS.Unsigned8;
+    c3   : in     RTEMS.Unsigned8;
+    c4   : in     RTEMS.Unsigned8;
+    Name :    out RTEMS.Name
+    );
+
+**DIRECTIVE STATUS CODES**
+
+Returns a name constructed from the four characters.
+
+**DESCRIPTION:**
+
+This service takes the four characters provided as arguments
+and constructs a thirty-two bit object name with ``c1``
+in the most significant byte and ``c4`` in the least
+significant byte.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_GET_CLASSIC_NAME - Lookup name from id
+---------------------------------------------
+.. index:: get name from id
+.. index:: obtain name from id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Get_Classic_Name(
+    ID     : in     RTEMS.ID;
+    Name   :    out RTEMS.Name;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES**
+
+``RTEMS.SUCCESSFUL`` - name looked up successfully
+``RTEMS.INVALID_ADDRESS`` - invalid name pointer
+``RTEMS.INVALID_ID`` - invalid object id
+
+**DESCRIPTION:**
+
+This service looks up the name for the object ``id`` specified
+and, if found, places the result in ``*name``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_GET_NAME - Obtain object name as string
+----------------------------------------------
+.. index:: get object name as string
+.. index:: obtain object name as string
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Get_Name(
+    ID     : in     RTEMS.ID;
+    Name   :    out RTEMS.Name;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES**
+
+Returns a pointer to the name if successful or ``NULL``
+otherwise.
+
+**DESCRIPTION:**
+
+This service looks up the name of the object specified by``id`` and places it in the memory pointed to by ``name``.
+Every attempt is made to return name as a printable string even
+if the object has the Classic API thirty-two bit style name.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_SET_NAME - Set object name
+---------------------------------
+.. index:: set object name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Set_Name(
+    ID     : in     RTEMS.ID;
+    Name   : in     String;
+    Result :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES**
+
+``RTEMS.SUCCESSFUL`` - name looked up successfully
+``RTEMS.INVALID_ADDRESS`` - invalid name pointer
+``RTEMS.INVALID_ID`` - invalid object id
+
+**DESCRIPTION:**
+
+This service sets the name of ``id`` to that specified
+by the string located at ``name``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+If the object specified by ``id`` is of a class that
+has a string name, this method will free the existing
+name to the RTEMS Workspace and allocate enough memory
+from the RTEMS Workspace to make a copy of the string
+located at ``name``.
+
+If the object specified by ``id`` is of a class that
+has a thirty-two bit integer style name, then the first
+four characters in ``*name`` will be used to construct
+the name.
+name to the RTEMS Workspace and allocate enough memory
+from the RTEMS Workspace to make a copy of the string
+
+OBJECT_ID_GET_API - Obtain API from Id
+--------------------------------------
+.. index:: obtain API from id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Id_Get_API(
+    ID  : in     RTEMS.ID;
+    API :    out RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+Returns the API portion of the object Id.
+
+**DESCRIPTION:**
+
+This directive returns the API portion of the provided object ``id``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+This directive does NOT validate the ``id`` provided.
+
+OBJECT_ID_GET_CLASS - Obtain Class from Id
+------------------------------------------
+.. index:: obtain class from object id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Id_Get_Class(
+    ID        : in     RTEMS.ID;
+    The_Class :    out RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+Returns the class portion of the object Id.
+
+**DESCRIPTION:**
+
+This directive returns the class portion of the provided object ``id``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+This directive does NOT validate the ``id`` provided.
+
+OBJECT_ID_GET_NODE - Obtain Node from Id
+----------------------------------------
+.. index:: obtain node from object id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Id_Get_Node(
+    ID   : in     RTEMS.ID;
+    Node :    out RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+Returns the node portion of the object Id.
+
+**DESCRIPTION:**
+
+This directive returns the node portion of the provided object ``id``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+This directive does NOT validate the ``id`` provided.
+
+OBJECT_ID_GET_INDEX - Obtain Index from Id
+------------------------------------------
+.. index:: obtain index from object id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Id_Get_Index(
+    ID    : in     RTEMS.ID;
+    Index :    out RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+Returns the index portion of the object Id.
+
+**DESCRIPTION:**
+
+This directive returns the index portion of the provided object ``id``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+This directive does NOT validate the ``id`` provided.
+
+BUILD_ID - Build Object Id From Components
+------------------------------------------
+.. index:: build object id from components
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Build_Id(
+    the_api   : in     RTEMS.Unsigned32;
+    the_class : in     RTEMS.Unsigned32;
+    the_node  : in     RTEMS.Unsigned32;
+    the_index : in     RTEMS.Unsigned32
+    ) return RTEMS.Id;
+
+**DIRECTIVE STATUS CODES**
+
+Returns an object Id constructed from the provided arguments.
+
+**DESCRIPTION:**
+
+This service constructs an object Id from the provided``the_api``, ``the_class``, ``the_node``, and ``the_index``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+This directive does NOT validate the arguments provided
+or the Object id returned.
+
+OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
+------------------------------------------------
+.. index:: obtain minimum API value
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Object_Id_API_Minimum return RTEMS.Unsigned32;
+
+**DIRECTIVE STATUS CODES**
+
+Returns the minimum valid for the API portion of an object Id.
+
+**DESCRIPTION:**
+
+This service returns the minimum valid for the API portion of
+an object Id.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
+------------------------------------------------
+.. index:: obtain maximum API value
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    function Object_Id_API_Maximum return RTEMS.Unsigned32;
+
+**DIRECTIVE STATUS CODES**
+
+Returns the maximum valid for the API portion of an object Id.
+
+**DESCRIPTION:**
+
+This service returns the maximum valid for the API portion of
+an object Id.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
+-----------------------------------------------------
+.. index:: obtain minimum class value
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_API_Minimum_Class(
+    API     : in     RTEMS.Unsigned32;
+    Minimum :    out RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+If ``api`` is not valid, -1 is returned.
+
+If successful, this service returns the minimum valid for the class
+portion of an object Id for the specified ``api``.
+
+**DESCRIPTION:**
+
+This service returns the minimum valid for the class portion of
+an object Id for the specified ``api``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
+-----------------------------------------------------
+.. index:: obtain maximum class value
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_API_Maximum_Class(
+    API     : in     RTEMS.Unsigned32;
+    Maximum :    out RTEMS.Unsigned32
+    );
+
+**DIRECTIVE STATUS CODES**
+
+If ``api`` is not valid, -1 is returned.
+
+If successful, this service returns the maximum valid for the class
+portion of an object Id for the specified ``api``.
+
+**DESCRIPTION:**
+
+This service returns the maximum valid for the class portion of
+an object Id for the specified ``api``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+OBJECT_GET_API_NAME - Obtain API Name
+-------------------------------------
+.. index:: obtain API name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Get_API_Name(
+    API  : in     RTEMS.Unsigned32;
+    Name :    out String
+    );
+
+**DIRECTIVE STATUS CODES**
+
+If ``api`` is not valid, the string ``"BAD API"`` is returned.
+
+If successful, this service returns a pointer to a string
+containing the name of the specified ``api``.
+
+**DESCRIPTION:**
+
+This service returns the name of the specified ``api``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+The string returned is from constant space.  Do not modify
+or free it.
+
+OBJECT_GET_API_CLASS_NAME - Obtain Class Name
+---------------------------------------------
+.. index:: obtain class name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Get_API_Class_Name(
+    The_API   : in     RTEMS.Unsigned32;
+    The_Class : in     RTEMS.Unsigned32;
+    Name      :    out String
+    );
+
+**DIRECTIVE STATUS CODES**
+
+If ``the_api`` is not valid, the string ``"BAD API"`` is returned.
+
+If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned.
+
+If successful, this service returns a pointer to a string
+containing the name of the specified ``the_api``/``the_class`` pair.
+
+**DESCRIPTION:**
+
+This service returns the name of the object class indicated by the
+specified ``the_api`` and ``the_class``.
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+The string returned is from constant space.  Do not modify
+or free it.
+
+OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
+-------------------------------------------------------
+.. index:: obtain class information
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    procedure Object_Get_Class_Information(
+    The_API   : in     RTEMS.Unsigned32;
+    The_Class : in     RTEMS.Unsigned32;
+    Info      :    out RTEMS.Object_API_Class_Information;
+    Result    :    out RTEMS.Status_Codes
+    );
+
+**DIRECTIVE STATUS CODES**
+
+``RTEMS.SUCCESSFUL`` - information obtained successfully
+``RTEMS.INVALID_ADDRESS`` - ``info`` is NULL
+``RTEMS.INVALID_NUMBER`` - invalid ``api`` or ``the_class``
+
+If successful, the structure located at ``info`` will be filled
+in with information about the specified ``api``/``the_class`` pairing.
+
+**DESCRIPTION:**
+
+This service returns information about the object class indicated by the
+specified ``api`` and ``the_class``. This structure is defined as
+follows:
+
+.. code:: c
+
+**NOTES:**
+
+This directive is strictly local and does not impact task scheduling.
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Chains
+######
+
+.. index:: chains
+
+Introduction
+============
+
+The Chains API is an interface to the Super Core (score) chain
+implementation. The Super Core uses chains for all list type
+functions. This includes wait queues and task queues. The Chains API
+provided by RTEMS is:
+
+- build_id
+
+- ``rtems.chain_node`` - Chain node used in user objects
+
+- ``rtems.chain_control`` - Chain control node
+
+- ``rtems.chain_initialize`` - initialize the chain with nodes
+
+- ``rtems.chain_initialize_empty`` - initialize the chain as empty
+
+- ``rtems.chain_is_null_node`` - Is the node NULL ?
+
+- ``rtems.chain_head`` - Return the chainâs head
+
+- ``rtems.chain_tail`` - Return the chainâs tail
+
+- ``rtems.chain_are_nodes_equal`` - Are the nodeâs equal ?
+
+- ``rtems.chain_is_empty`` - Is the chain empty ?
+
+- ``rtems.chain_is_first`` - Is the Node the first in the chain ?
+
+- ``rtems.chain_is_last`` - Is the Node the last in the chain ?
+
+- ``rtems.chain_has_only_one_node`` - Does the node have one node ?
+
+- ``rtems.chain_node_count_unprotected`` - Returns the node count of the chain (unprotected)
+
+- ``rtems.chain_is_head`` - Is the node the head ?
+
+- ``rtems.chain_is_tail`` - Is the node the tail ?
+
+- ``rtems.chain_extract`` - Extract the node from the chain
+
+- ``rtems.chain_extract_unprotected`` - Extract the node from the chain (unprotected)
+
+- ``rtems.chain_get`` - Return the first node on the chain
+
+- ``rtems.chain_get_unprotected`` - Return the first node on the chain (unprotected)
+
+- ``rtems.chain_get_first_unprotected`` - Get the first node on the chain (unprotected)
+
+- ``rtems.chain_insert`` - Insert the node into the chain
+
+- ``rtems.chain_insert_unprotected`` - Insert the node into the chain (unprotected)
+
+- ``rtems.chain_append`` - Append the node to chain
+
+- ``rtems.chain_append_unprotected`` - Append the node to chain (unprotected)
+
+- ``rtems.chain_prepend`` - Prepend the node to the end of the chain
+
+- ``rtems.chain_prepend_unprotected`` - Prepend the node to chain (unprotected)
+
+Background
+==========
+
+The Chains API maps to the Super Core Chains API. Chains are
+implemented as a double linked list of nodes anchored to a control
+node. The list starts at the control node and is terminated at the
+control node. A node has previous and next pointers. Being a double
+linked list nodes can be inserted and removed without the need to
+travse the chain.
+
+Chains have a small memory footprint and can be used in interrupt
+service routines and are thread safe in a multi-threaded
+environment. The directives list which operations disable interrupts.
+
+Chains are very useful in Board Support packages and applications.
+
+Nodes
+-----
+
+A chain is made up from nodes that orginate from a chain control
+object. A node is of type ``rtems.chain_node``. The node
+is designed to be part of a user data structure and a cast is used to
+move from the node address to the user data structure address. For
+example:
+.. code:: c
+
+    typedef struct foo
+    {
+    rtems.chain_node node;
+    int              bar;
+    } foo;
+
+creates a type ``foo`` that can be placed on a chain. To get the
+foo structure from the list you perform the following:
+.. code:: c
+
+    foo* get_foo(rtems.chain_control* control)
+    {
+    return (foo*) rtems.chain_get(control);
+    }
+
+The node is placed at the start of the userâs structure to allow the
+node address on the chain to be easly cast to the userâs structure
+address.
+
+Controls
+--------
+
+A chain is anchored with a control object. Chain control provide the
+user with access to the nodes on the chain. The control is head of the
+node.
+
+.. code:: c
+
+    Control
+    first ------------------------>
+    permanent_null <--------------- NODE
+    last ------------------------->
+
+The implementation does not require special checks for manipulating
+the first and last nodes on the chain. To accomplish this the``rtems.chain_control`` structure is treated as two
+overlapping ``rtems.chain_node`` structures.  The
+permanent head of the chain overlays a node structure on the first and``permanent_null`` fields.  The ``permanent_tail`` of the chain
+overlays a node structure on the ``permanent_null`` and ``last``
+elements of the structure.
+
+Operations
+==========
+
+Multi-threading
+---------------
+
+Chains are designed to be used in a multi-threading environment. The
+directives list which operations mask interrupts. Chains supports
+tasks and interrupt service routines appending and extracting nodes
+with out the need for extra locks. Chains how-ever cannot insure the
+integrity of a chain for all operations. This is the responsibility of
+the user. For example an interrupt service routine extracting nodes
+while a task is iterating over the chain can have unpredictable
+results.
+
+Creating a Chain
+----------------
+
+To create a chain you need to declare a chain control then add nodes
+to the control. Consider a user structure and chain control:
+.. code:: c
+
+    typedef struct foo
+    {
+    rtems.chain_node node;
+    uint8_t char*    data;
+    } foo;
+    rtems.chain_control chain;
+
+Add nodes with the following code:
+.. code:: c
+
+    rtems.chain_initialize_empty (&chain);
+    for (i = 0; i < count; i++)
+    {
+    foo* bar = malloc (sizeof (foo));
+    if (!bar)
+    return -1;
+    bar->data = malloc (size);
+    rtems.chain_append (&chain, &bar->node);
+    }
+
+The chain is initialized and the nodes allocated and appended to the
+chain. This is an example of a pool of buffers.
+
+Iterating a Chain
+-----------------
+.. index:: chain iterate
+
+Iterating a chain is a common function. The example shows how to
+iterate the buffer pool chain created in the last section to find
+buffers starting with a specific string. If the buffer is located it is
+extracted from the chain and placed on another chain:
+.. code:: c
+
+    void foobar (const char*          match,
+    rtems.chain_control* chain,
+    rtems.chain_control* out)
+    {
+    rtems.chain_node* node;
+    foo*              bar;
+    rtems.chain_initialize_empty (out);
+    node = chain->first;
+    while (!rtems.chain_is_tail (chain, node))
+    {
+    bar = (foo*) node;
+    rtems_chain_node* next_node = node->next;
+    if (strcmp (match, bar->data) == 0)
+    {
+    rtems.chain_extract (node);
+    rtems.chain_append (out, node);
+    }
+    node = next_node;
+    }
+    }
+
+Directives
+==========
+
+The section details the Chains directives.
+
+.. COMMENT: Initialize this Chain With Nodes
+
+Initialize Chain With Nodes
+---------------------------
+.. index:: chain initialize
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns nothing.
+
+**DESCRIPTION:**
+
+This function take in a pointer to a chain control and initializes it
+to contain a set of chain nodes.  The chain will contain ``number_nodes``
+chain nodes from the memory pointed to by ``start_address``.  Each node
+is assumed to be ``node_size`` bytes.
+
+**NOTES:**
+
+This call will discard any nodes on the chain.
+
+This call does NOT inititialize any user data on each node.
+
+.. COMMENT: Initialize this Chain as Empty
+
+Initialize Empty
+----------------
+.. index:: chain initialize empty
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns nothing.
+
+**DESCRIPTION:**
+
+This function take in a pointer to a chain control and initializes it
+to empty.
+
+**NOTES:**
+
+This call will discard any nodes on the chain.
+
+Is Null Node ?
+--------------
+.. index:: chain is node null
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns ``true`` is the node point is NULL and ``false`` if the node is not
+NULL.
+
+**DESCRIPTION:**
+
+Tests the node to see if it is a NULL returning ``true`` if a null.
+
+Head
+----
+.. index:: chain get head
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns the permanent head node of the chain.
+
+**DESCRIPTION:**
+
+This function returns a pointer to the first node on the chain.
+
+Tail
+----
+.. index:: chain get tail
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns the permanent tail node of the chain.
+
+**DESCRIPTION:**
+
+This function returns a pointer to the last node on the chain.
+
+Are Two Nodes Equal ?
+---------------------
+.. index:: chare are nodes equal
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if the left node and the right node are
+equal, and ``false`` otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if the left node and the right node are
+equal, and ``false`` otherwise.
+
+Is the Chain Empty
+------------------
+.. index:: chain is chain empty
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if there a no nodes on the chain and ``false``
+otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if there a no nodes on the chain and ``false``
+otherwise.
+
+Is this the First Node on the Chain ?
+-------------------------------------
+.. index:: chain is node the first
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if the node is the first node on a chain
+and ``false`` otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if the node is the first node on a chain
+and ``false`` otherwise.
+
+Is this the Last Node on the Chain ?
+------------------------------------
+.. index:: chain is node the last
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if the node is the last node on a chain and``false`` otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if the node is the last node on a chain and``false`` otherwise.
+
+Does this Chain have only One Node ?
+------------------------------------
+.. index:: chain only one node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if there is only one node on the chain and``false`` otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if there is only one node on the chain and``false`` otherwise.
+
+Returns the node count of the chain (unprotected)
+-------------------------------------------------
+.. index:: chain only one node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns the node count of the chain.
+
+**DESCRIPTION:**
+
+This function returns the node count of the chain.
+
+Is this Node the Chain Head ?
+-----------------------------
+.. index:: chain is node the head
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if the node is the head of the chain and``false`` otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if the node is the head of the chain and``false`` otherwise.
+
+Is this Node the Chain Tail ?
+-----------------------------
+.. index:: chain is node the tail
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+This function returns ``true`` if the node is the tail of the chain and``false`` otherwise.
+
+**DESCRIPTION:**
+
+This function returns ``true`` if the node is the tail of the chain and``false`` otherwise.
+
+Extract a Node
+--------------
+.. index:: chain extract a node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns nothing.
+
+**DESCRIPTION:**
+
+This routine extracts the node from the chain on which it resides.
+
+**NOTES:**
+
+Interrupts are disabled while extracting the node to ensure the
+atomicity of the operation.
+
+Use ``rtems.chain_extract_unprotected()`` to avoid disabling of
+interrupts.
+
+Get the First Node
+------------------
+.. index:: chain get first node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns a pointer a node. If a node was removed, then a pointer to
+that node is returned. If the chain was empty, then NULL is
+returned.
+
+**DESCRIPTION:**
+
+This function removes the first node from the chain and returns a
+pointer to that node.  If the chain is empty, then NULL is returned.
+
+**NOTES:**
+
+Interrupts are disabled while obtaining the node to ensure the
+atomicity of the operation.
+
+Use ``rtems.chain_get_unprotected()`` to avoid disabling of
+interrupts.
+
+Get the First Node (unprotected)
+--------------------------------
+.. index:: chain get first node
+
+**CALLING SEQUENCE:**
+
+**RETURNS:**
+
+A pointer to the former first node is returned.
+
+**DESCRIPTION:**
+
+Removes the first node from the chain and returns a pointer to it.  In case the
+chain was empty, then the results are unpredictable.
+
+**NOTES:**
+
+The function does nothing to ensure the atomicity of the operation.
+
+Insert a Node
+-------------
+.. index:: chain insert a node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns nothing.
+
+**DESCRIPTION:**
+
+This routine inserts a node on a chain immediately following the
+specified node.
+
+**NOTES:**
+
+Interrupts are disabled during the insert to ensure the atomicity of
+the operation.
+
+Use ``rtems.chain_insert_unprotected()`` to avoid disabling of
+interrupts.
+
+Append a Node
+-------------
+.. index:: chain append a node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns nothing.
+
+**DESCRIPTION:**
+
+This routine appends a node to the end of a chain.
+
+**NOTES:**
+
+Interrupts are disabled during the append to ensure the atomicity of
+the operation.
+
+Use ``rtems.chain_append_unprotected()`` to avoid disabling of
+interrupts.
+
+Prepend a Node
+--------------
+.. index:: prepend node
+
+**CALLING SEQUENCE:**
+
+**RETURNS**
+
+Returns nothing.
+
+**DESCRIPTION:**
+
+This routine prepends a node to the front of the chain.
+
+**NOTES:**
+
+Interrupts are disabled during the prepend to ensure the atomicity of
+the operation.
+
+Use ``rtems.chain_prepend_unprotected()`` to avoid disabling of
+interrupts.
+
+.. COMMENT: Copyright 2014 Gedare Bloom.
+
+.. COMMENT: All rights reserved.
+
+Red-Black Trees
+###############
+
+.. index:: rbtrees
+
+Introduction
+============
+
+The Red-Black Tree API is an interface to the SuperCore (score) rbtree
+implementation. Within RTEMS, red-black trees are used when a binary search
+tree is needed, including dynamic priority thread queues and non-contiguous
+heap memory. The Red-Black Tree API provided by RTEMS is:
+
+- build_id
+
+- ``rtems.rtems_rbtree_node`` - Red-Black Tree node embedded in another struct
+
+- ``rtems.rtems_rbtree_control`` - Red-Black Tree control node for an entire tree
+
+- ``rtems.rtems_rbtree_initialize`` - initialize the red-black tree with nodes
+
+- ``rtems.rtems_rbtree_initialize_empty`` - initialize the red-black tree as empty
+
+- ``rtems.rtems_rbtree_set_off_tree`` - Clear a nodeâs links
+
+- ``rtems.rtems_rbtree_root`` - Return the red-black treeâs root node
+
+- ``rtems.rtems_rbtree_min`` - Return the red-black treeâs minimum node
+
+- ``rtems.rtems_rbtree_max`` - Return the red-black treeâs maximum node
+
+- ``rtems.rtems_rbtree_left`` - Return a nodeâs left child node
+
+- ``rtems.rtems_rbtree_right`` - Return a nodeâs right child node
+
+- ``rtems.rtems_rbtree_parent`` - Return a nodeâs parent node
+
+- ``rtems.rtems_rbtree_are_nodes_equal`` - Are the nodeâs equal ?
+
+- ``rtems.rtems_rbtree_is_empty`` - Is the red-black tree empty ?
+
+- ``rtems.rtems_rbtree_is_min`` - Is the Node the minimum in the red-black tree ?
+
+- ``rtems.rtems_rbtree_is_max`` - Is the Node the maximum in the red-black tree ?
+
+- ``rtems.rtems_rbtree_is_root`` - Is the Node the root of the red-black tree ?
+
+- ``rtems.rtems_rbtree_find`` - Find the node with a matching key in the red-black tree
+
+- ``rtems.rtems_rbtree_predecessor`` - Return the in-order predecessor of a node.
+
+- ``rtems.rtems_rbtree_successor`` - Return the in-order successor of a node.
+
+- ``rtems.rtems_rbtree_extract`` - Remove the node from the red-black tree
+
+- ``rtems.rtems_rbtree_get_min`` - Remove the minimum node from the red-black tree
+
+- ``rtems.rtems_rbtree_get_max`` - Remove the maximum node from the red-black tree
+
+- ``rtems.rtems_rbtree_peek_min`` - Returns the minimum node from the red-black tree
+
+- ``rtems.rtems_rbtree_peek_max`` - Returns the maximum node from the red-black tree
+
+- ``rtems.rtems_rbtree_insert`` - Add the node to the red-black tree
+
+Background
+==========
+
+The Red-Black Trees API is a thin layer above the SuperCore Red-Black Trees
+implementation. A Red-Black Tree is defined by a control node with pointers to
+the root, minimum, and maximum nodes in the tree. Each node in the tree
+consists of a parent pointer, two children pointers, and a color attribute.  A
+tree is parameterized as either unique, meaning identical keys are rejected, or
+not, in which case duplicate keys are allowed.
+
+Users must provide a comparison functor that gets passed to functions that need
+to compare nodes. In addition, no internal synchronization is offered within
+the red-black tree implementation, thus users must ensure at most one thread
+accesses a red-black tree instance at a time.
+
+Nodes
+-----
+
+A red-black tree is made up from nodes that orginate from a red-black tree control
+object. A node is of type ``rtems.rtems_rbtree_node``. The node
+is designed to be part of a user data structure. To obtain the encapsulating
+structure users can use the ``RTEMS_CONTAINER_OF`` macro.
+The node can be placed anywhere within the userâs structure and the macro will
+calculate the structureâs address from the nodeâs address.
+
+Controls
+--------
+
+A red-black tree is rooted with a control object. Red-Black Tree control
+provide the user with access to the nodes on the red-black tree.  The
+implementation does not require special checks for manipulating the root of the
+red-black tree. To accomplish this the``rtems.rtems_rbtree_control`` structure is treated as a``rtems.rtems_rbtree_node`` structure with a ``NULL`` parent
+and left child pointing to the root.
+
+Operations
+==========
+
+Examples for using the red-black trees
+can be found in the testsuites/sptests/sprbtree01/init.c file.
+
+Directives
+==========
+
+Documentation for the Red-Black Tree Directives
+-----------------------------------------------
+.. index:: rbtree doc
+
+Source documentation for the Red-Black Tree API can be found in the
+generated Doxygen output for cpukit/sapi.
+
+.. COMMENT: COPYRIGHT (c) 1988-2012.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Timespec Helpers
+################
+
+Introduction
+============
+
+The Timespec helpers manager provides directives to assist in manipulating
+instances of the POSIX ``struct timespec`` structure.
+
+The directives provided by the timespec helpers manager are:
+
+- ``rtems_timespec_set`` - Set timespecâs value
+
+- ``rtems_timespec_zero`` - Zero timespecâs value
+
+- ``rtems_timespec_is_valid`` - Check if timespec is valid
+
+- ``rtems_timespec_add_to`` - Add two timespecs
+
+- ``rtems_timespec_subtract`` - Subtract two timespecs
+
+- ``rtems_timespec_divide`` - Divide two timespecs
+
+- ``rtems_timespec_divide_by_integer`` - Divide timespec by integer
+
+- ``rtems_timespec_less_than`` - Less than operator
+
+- ``rtems_timespec_greater_than`` - Greater than operator
+
+- ``rtems_timespec_equal_to`` - Check if two timespecs are equal
+
+- ``rtems_timespec_get_seconds`` - Obtain seconds portion of timespec
+
+- ``rtems_timespec_get_nanoseconds`` - Obtain nanoseconds portion of timespec
+
+- ``rtems_timespec_to_ticks`` - Convert timespec to number of ticks
+
+- ``rtems_timespec_from_ticks`` - Convert ticks to timespec
+
+Background
+==========
+
+Time Storage Conventions
+------------------------
+
+Time can be stored in many ways. One of them is the ``struct timespec``
+format which is a structure that consists of the fields ``tv_sec``
+to represent seconds and ``tv_nsec`` to represent nanoseconds.  The``struct timeval`` structure is simular and consists of seconds (stored
+in ``tv_sec``) and microseconds (stored in ``tv_usec``). Either``struct timespec`` or ``struct timeval`` can be used to represent
+elapsed time, time of executing some operations, or time of day.
+
+Operations
+==========
+
+Set and Obtain Timespec Value
+-----------------------------
+
+A user may write a specific time by passing the desired seconds and
+nanoseconds values and the destination ``struct timespec`` using the``rtems_timespec_set`` directive.
+
+The ``rtems_timespec_zero`` directive is used to zero the seconds
+and nanoseconds portions of a ``struct timespec`` instance.
+
+Users may obtain the seconds or nanoseconds portions of a ``struct
+timespec`` instance with the ``rtems_timespec_get_seconds`` or``rtems_timespec_get_nanoseconds`` methods, respectively.
+
+Timespec Math
+-------------
+
+A user can perform multiple operations on ``struct timespec``
+instances. The helpers in this manager assist in adding, subtracting, and
+performing divison on ``struct timespec`` instances.
+
+- Adding two ``struct timespec`` can be done using the``rtems_timespec_add_to`` directive. This directive is used mainly
+  to calculate total amount of time consumed by multiple operations.
+
+- The ``rtems_timespec_subtract`` is used to subtract two``struct timespecs`` instances and determine the elapsed time between
+  those two points in time.
+
+- The ``rtems_timespec_divide`` is used to use to divide one``struct timespec`` instance by another. This calculates the percentage
+  with a precision to three decimal points.
+
+- The ``rtems_timespec_divide_by_integer`` is used to divide a``struct timespec`` instance by an integer. It is commonly used in
+  benchmark calculations to dividing duration by the number of iterations
+  performed.
+
+Comparing struct timespec Instances
+-----------------------------------
+
+A user can compare two ``struct timespec`` instances using the``rtems_timespec_less_than``, ``rtems_timespec_greater_than``
+or ``rtems_timespec_equal_to`` routines.
+
+Conversions and Validity Check
+------------------------------
+
+Conversion to and from clock ticks may be performed by using the``rtems_timespec_to_ticks`` and ``rtems_timespec_from_ticks``
+directives.
+
+User can also check validity of timespec with``rtems_timespec_is_valid`` routine.
+
+Directives
+==========
+
+This section details the Timespec Helpers 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.
+
+TIMESPEC_SET - Set struct timespec Instance
+-------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive sets the ``struct timespec`` ``time`` value to the
+desired ``seconds`` and ``nanoseconds`` values.
+
+**NOTES:**
+
+This method does NOT check if ``nanoseconds`` is less than the
+maximum number of nanoseconds in a second.
+
+TIMESPEC_ZERO - Zero struct timespec Instance
+---------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This routine sets the contents of the ``struct timespec`` instance``time`` to zero.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_IS_VALID - Check validity of a struct timespec instance
+----------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This method returns ``true`` if the instance is valid, and ``false``
+otherwise.
+
+**DESCRIPTION:**
+
+This routine check validity of a ``struct timespec`` instance. It
+checks if the nanoseconds portion of the ``struct timespec`` instanceis
+in allowed range (less than the maximum number of nanoseconds per second).
+
+**NOTES:**
+
+TIMESPEC_ADD_TO - Add Two struct timespec Instances
+---------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+The method returns the number of seconds ``time`` increased by.
+
+**DESCRIPTION:**
+
+This routine adds two ``struct timespec`` instances. The second argument is added to the first. The parameter ``time`` is the base time to which the ``add`` parameter is added.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
+----------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This routine subtracts ``start`` from ``end`` saves the difference
+in ``result``. The primary use of this directive is to calculate
+elapsed time.
+
+**NOTES:**
+
+It is possible to subtract when ``end`` is less than ``start``
+and it produce negative ``result``. When doing this you should be
+careful and remember that only the seconds portion of a ``struct
+timespec`` instance is signed, which means that nanoseconds portion is
+always increasing. Due to that when your timespec has seconds = -1 and
+nanoseconds=500,000,000 it means that result is -0.5 second, NOT the
+expected -1.5!
+
+TIMESPEC_DIVIDE - Divide Two struct timespec Instances
+------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This routine divides the ``struct timespec`` instance ``lhs`` by
+the ``struct timespec`` instance ``rhs``. The result is returned
+in the ``ival_percentage`` and ``fval_percentage``, representing
+the integer and fractional results of the division respectively.
+
+The ``ival_percentage`` is integer value of calculated percentage and ``fval_percentage`` is fractional part of calculated percentage.
+
+**NOTES:**
+
+The intended use is calculating percentges to three decimal points.
+
+When dividing by zero, this routine return both ``ival_percentage``
+and ``fval_percentage`` equal zero.
+
+The division is performed using exclusively integer operations.
+
+TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
+----------------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This routine divides the ``struct timespec`` instance ``time`` by the integer value ``iterations``.
+The result is saved in ``result``.
+
+**NOTES:**
+
+The expected use is to assist in benchmark calculations where you
+typically divide a duration (``time``) by a number of iterations what
+gives average time.
+
+TIMESPEC_LESS_THAN - Less than operator
+---------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This method returns ``struct true`` if ``lhs`` is less than``rhs`` and ``struct false`` otherwise.
+
+**DESCRIPTION:**
+
+This method is the less than operator for ``struct timespec`` instances. The first parameter is the left hand side and the second is the right hand side of the comparison.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_GREATER_THAN - Greater than operator
+---------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This method returns ``struct true`` if ``lhs`` is greater than``rhs`` and ``struct false`` otherwise.
+
+**DESCRIPTION:**
+
+This method is greater than operator for ``struct timespec`` instances.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_EQUAL_TO - Check equality of timespecs
+-----------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This method returns ``struct true`` if ``lhs`` is equal to``rhs`` and ``struct false`` otherwise.
+
+**DESCRIPTION:**
+
+This method is equality operator for ``struct timespec`` instances.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
+----------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This method returns the seconds portion of the specified ``struct
+timespec`` instance.
+
+**DESCRIPTION:**
+
+This method returns the seconds portion of the specified ``struct timespec`` instance ``time``.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
+----------------------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This method returns the nanoseconds portion of the specified ``struct
+timespec`` instance.
+
+**DESCRIPTION:**
+
+This method returns the nanoseconds portion of the specified timespec
+which is pointed by ``_time``.
+
+**NOTES:**
+
+TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
+-------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+This directive returns the number of ticks computed.
+
+**DESCRIPTION:**
+
+This directive converts the ``time`` timespec to the corresponding number of clock ticks.
+
+**NOTES:**
+
+NONE
+
+TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
+---------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+Not Currently Supported In Ada
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This routine converts the ``ticks`` to the corresponding ``struct timespec`` representation and stores it in ``time``.
+
+**NOTES:**
+
+NONE
+
+.. COMMENT: COPYRIGHT (c) 2011.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Constant Bandwidth Server Scheduler API
+#######################################
+
+.. index:: cbs
+
+Introduction
+============
+
+Unlike simple schedulers, the Constant Bandwidth Server (CBS) requires
+a special API for tasks to indicate their scheduling parameters.
+The directives provided by the CBS API are:
+
+- ``rtems.cbs_initialize`` - Initialize the CBS library
+
+- ``rtems.cbs_cleanup`` - Cleanup the CBS library
+
+- ``rtems.cbs_create_server`` - Create a new bandwidth server
+
+- ``rtems.cbs_attach_thread`` - Attach a thread to server
+
+- ``rtems.cbs_detach_thread`` - Detach a thread from server
+
+- ``rtems.cbs_destroy_server`` - Destroy a bandwidth server
+
+- ``rtems.cbs_get_server_id`` - Get an ID of a server
+
+- ``rtems.cbs_get_parameters`` - Get scheduling parameters of a server
+
+- ``rtems.cbs_set_parameters`` - Set scheduling parameters of a server
+
+- ``rtems.cbs_get_execution_time`` - Get elapsed execution time
+
+- ``rtems.cbs_get_remaining_budget`` - Get remainig execution time
+
+- ``rtems.cbs_get_approved_budget`` - Get scheduler approved execution time
+
+Background
+==========
+
+Constant Bandwidth Server Definitions
+-------------------------------------
+.. index:: CBS parameters
+
+.. index:: rtems_cbs_parameters
+
+The Constant Bandwidth Server API enables tasks to communicate with
+the scheduler and indicate its scheduling parameters. The scheduler
+has to be set up first (by defining ``CONFIGURE_SCHEDULER_CBS`` macro).
+
+The difference to a plain EDF is the presence of servers.
+It is a budget aware extention of the EDF scheduler, therefore, tasks
+attached to servers behave in a similar way as with EDF unless they
+exceed their budget.
+
+The intention of servers is reservation of a certain computation
+time (budget) of the processor for all subsequent periods. The structure``rtems_cbs_parameters`` determines the behavior of
+a server. It contains ``deadline`` which is equal to period,
+and ``budget`` which is the time the server is allowed to
+spend on CPU per each period. The ratio between those two parameters
+yields the maximum percentage of the CPU the server can use
+(bandwidth). Moreover, thanks to this limitation the overall
+utilization of CPU is under control, and the sum of bandwidths
+of all servers in the system yields the overall reserved portion
+of processor. The rest is still available for ordinary tasks that
+are not attached to any server.
+
+In order to make the server effective to the executing tasks,
+tasks have to be attached to the servers. The``rtems_cbs_server_id`` is a type denoting an id of a server
+and ``rtems_id`` a type for id of tasks.
+
+Handling Periodic Tasks
+-----------------------
+.. index:: CBS periodic tasks
+
+Each taskâs execution begins with a default background priority
+(see the chapter Scheduling Concepts to understand the concept of
+priorities in EDF). Once you decide the tasks should start periodic
+execution, you have two possibilities. Either you use only the Rate
+Monotonic manager which takes care of periodic behavior, or you declare
+deadline and budget using the CBS API in which case these properties
+are constant for all subsequent periods, unless you change them using
+the CBS API again. Task now only has to indicate and end of
+each period using ``rtems_rate_monotonic_period``.
+
+Registering a Callback Function
+-------------------------------
+.. index:: CBS overrun handler
+
+In case tasks attached to servers are not aware of their execution time
+and happen to exceed it, the scheduler does not guarantee execution any
+more and pulls the priority of the task to background, which would
+possibly lead to immediate preemption (if there is at least one ready
+task with a higher pirority). However, the task is not blocked but a
+callback function is invoked. The callback function
+(``rtems_cbs_budget_overrun``) might be optionally registered upon
+a server creation (``rtems_cbs_create_server``).
+
+This enables the user to define what should happen in case of budget
+overrun. There is obviously no space for huge operations because the
+priority is down and not real time any more, however, you still can at
+least in release resources for other tasks, restart the task or log an
+error information. Since the routine is called directly from kernel,
+use ``printk()`` instead of ``printf()``.
+
+The calling convention of the callback function is:
+
+Limitations
+-----------
+.. index:: CBS limitations
+
+When using this scheduler you have to keep in mind several things:
+
+- it_limitations
+
+- In the current implementation it is possible to attach only
+  a single task to each server.
+
+- If you have a task attached to a server and you voluntatily
+  block it in the beginning of its execution, its priority will be
+  probably pulled to background upon unblock, thus not guaranteed
+  deadline any more. This is because you are effectively raising
+  computation time of the task. When unbocking, you should be always
+  sure that the ratio between remaining computation time and remaining
+  deadline is not higher that the utilization you have agreed with the
+  scheduler.
+
+Operations
+==========
+
+Setting up a server
+-------------------
+
+The directive ``rtems_cbs_create_server`` is used to create a new
+server that is characterized by ``rtems_cbs_parameters``. You also
+might want to register the ``rtems_cbs_budget_overrun`` callback
+routine. After this step tasks can be attached to the server. The directive``rtems_cbs_set_parameters`` can change the scheduling parameters
+to avoid destroying and creating a new server again.
+
+Attaching Task to a Server
+--------------------------
+
+If a task is attached to a server using ``rtems_cbs_attach_thread``,
+the taskâs computation time per period is limited by the server and
+the deadline (period) of task is equal to deadline of the server which
+means if you conclude a period using ``rate_monotonic_period``,
+the length of next period is always determined by the serverâs property.
+
+The task has a guaranteed bandwidth given by the server but should not
+exceed it, otherwise the priority is pulled to background until the
+start of next period and the ``rtems_cbs_budget_overrun`` callback
+function is invoked.
+
+When attaching a task to server, the preemptability flag of the task
+is raised, otherwise it would not be possible to control the execution
+of the task.
+
+Detaching Task from a Server
+----------------------------
+
+The directive ``rtems_cbs_detach_thread`` is just an inverse
+operation to the previous one, the task continues its execution with
+the initial priority.
+
+Preemptability of the task is restored to the initial value.
+
+Examples
+--------
+
+The following example presents a simple common use of the API.
+
+You can see the initialization and cleanup call here, if there are
+multiple tasks in the system, it is obvious that the initialization
+should be called before creating the task.
+
+Notice also that in this case we decided to register an overrun handler,
+instead of which there could be ``NULL``. This handler just prints
+a message to terminal, what else may be done here depends on a specific
+application.
+
+During the periodic execution, remaining budget should be watched
+to avoid overrun.
+.. code:: c
+
+    void overrun_handler (
+    rtems_cbs_server_id server_id
+    )
+    {
+    printk( "Budget overrun, fixing the task\\n" );
+    return;
+    }
+    rtems_task Tasks_Periodic(
+    rtems_task_argument argument
+    )
+    {
+    rtems_id          rmid;
+    rtems_cbs_server_id server_id;
+    rtems_cbs_parameters params;
+    params.deadline = 10;
+    params.budget = 4;
+    rtems_cbs_initialize();
+    rtems_cbs_create_server( &params, &overrun_handler, &server_id )
+    rtems_cbs_attach_thread( server_id, SELF );
+    rtems_rate_monotonic_create( argument, &rmid );
+    while ( 1 ) {
+    if (rtems_rate_monotonic_period(rmid, params.deadline)==RTEMS_TIMEOUT)
+    break;
+    /* Perform some periodic action \*/
+    }
+    rtems_rate_monotonic_delete( rmid );
+    rtems_cbs_cleanup();
+    exit( 1 );
+    }
+
+Directives
+==========
+
+This section details the Constant Bandwidth Serverâs directives.
+A subsection is dedicated to each of this managerâs directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+CBS_INITIALIZE - Initialize the CBS library
+-------------------------------------------
+.. index:: initialize the CBS library
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful initialization
+``RTEMS.CBS_ERROR_NO_MEMORY`` - not enough memory for data
+
+**DESCRIPTION:**
+
+This routine initializes the library in terms of allocating necessary memory
+for the servers. In case not enough memory is available in the system,``RTEMS.CBS_ERROR_NO_MEMORY`` is returned, otherwise``RTEMS.CBS_OK``.
+
+**NOTES:**
+
+Additional memory per each server is allocated upon invocation of``rtems_cbs_create_server``.
+
+Tasks in the system are not influenced, they still keep executing
+with their initial parameters.
+
+CBS_CLEANUP - Cleanup the CBS library
+-------------------------------------
+.. index:: cleanup the CBS library
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - always successful
+
+**DESCRIPTION:**
+
+This routine detaches all tasks from their servers, destroys all servers
+and returns memory back to the system.
+
+**NOTES:**
+
+All tasks continue executing with their initial priorities.
+
+CBS_CREATE_SERVER - Create a new bandwidth server
+-------------------------------------------------
+.. index:: create a new bandwidth server
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successfully created
+``RTEMS.CBS_ERROR_NO_MEMORY`` - not enough memory for data
+``RTEMS.CBS_ERROR_FULL`` - maximum servers exceeded
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+
+**DESCRIPTION:**
+
+This routine prepares an instance of a constant bandwidth server.
+The input parameter ``rtems_cbs_parameters`` specifies scheduling
+parameters of the server (period and budget). If these are not valid,``RTEMS.CBS_ERROR_INVALID_PARAMETER`` is returned.
+The ``budget_overrun_callback`` is an optional callback function, which is
+invoked in case the serverâs budget within one period is exceeded.
+Output parameter ``server_id`` becomes an id of the newly created server.
+If there is not enough memory, the ``RTEMS.CBS_ERROR_NO_MEMORY``
+is returned. If the maximum server count in the system is exceeded,``RTEMS.CBS_ERROR_FULL`` is returned.
+
+**NOTES:**
+
+No task execution is being influenced so far.
+
+CBS_ATTACH_THREAD - Attach a thread to server
+---------------------------------------------
+.. index:: attach a thread to server
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successfully attached
+``RTEMS.CBS_ERROR_FULL`` - server maximum tasks exceeded
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+Attaches a task (``task_id``) to a server (``server_id``).
+The server has to be previously created. Now, the task starts
+to be scheduled according to the server parameters and not
+using initial priority. This implementation allows only one task
+per server, if the user tries to bind another task to the same
+server, ``RTEMS.CBS_ERROR_FULL`` is returned.
+
+**NOTES:**
+
+Tasks attached to servers become preemptible.
+
+CBS_DETACH_THREAD - Detach a thread from server
+-----------------------------------------------
+.. index:: detach a thread from server
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successfully detached
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive detaches a thread from server. The task continues its
+execution with initial priority.
+
+**NOTES:**
+
+The server can be reused for any other task.
+
+CBS_DESTROY_SERVER - Destroy a bandwidth server
+-----------------------------------------------
+.. index:: destroy a bandwidth server
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successfully destroyed
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive destroys a server. If any task was attached to the server,
+the task is detached and continues its execution according to EDF rules
+with initial properties.
+
+**NOTES:**
+
+This again enables one more task to be created.
+
+CBS_GET_SERVER_ID - Get an ID of a server
+-----------------------------------------
+.. index:: get an ID of a server
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive returns an id of server belonging to a given task.
+
+CBS_GET_PARAMETERS - Get scheduling parameters of a server
+----------------------------------------------------------
+.. index:: get scheduling parameters of a server
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive returns a structure with current scheduling parameters
+of a given server (period and execution time).
+
+**NOTES:**
+
+It makes no difference if any task is assigned or not.
+
+CBS_SET_PARAMETERS - Set scheduling parameters
+----------------------------------------------
+.. index:: set scheduling parameters
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive sets new scheduling parameters to the server. This operation
+can be performed regardless of whether a task is assigned or not.
+If a task is assigned, the parameters become effective imediately, therefore it
+is recommended to apply the change between two subsequent periods.
+
+**NOTES:**
+
+There is an upper limit on both period and budget equal to (2^31)-1 ticks.
+
+CBS_GET_EXECUTION_TIME - Get elapsed execution time
+---------------------------------------------------
+.. index:: get elapsed execution time
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This routine returns consumed execution time (``exec_time``) of a server
+during the current period.
+
+**NOTES:**
+
+Absolute time (``abs_time``) not supported now.
+
+CBS_GET_REMAINING_BUDGET - Get remaining execution time
+-------------------------------------------------------
+.. index:: get remaining execution time
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive returns remaining execution time of a given server for
+current period.
+
+**NOTES:**
+
+If the execution time approaches zero, the assigned task should finish
+computations of the current period.
+
+CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time
+---------------------------------------------------------------
+.. index:: get scheduler approved execution time
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS.CBS_OK`` - successful
+``RTEMS.CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
+``RTEMS.CBS_ERROR_NOSERVER`` - server is not valid
+
+**DESCRIPTION:**
+
+This directive returns serverâs approved budget for subsequent periods.
+
+.. COMMENT: COPYRIGHT (c) 1989-2011.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Directive Status Codes
+######################
+
+Introduction
+============
+
+*``RTEMS.SUCCESSFUL`` - successful completion*
+
+*``RTEMS.TASK_EXITTED`` - returned from a task*
+
+*``RTEMS.MP_NOT_CONFIGURED`` - multiprocessing not configured*
+
+*``RTEMS.INVALID_NAME`` - invalid object name*
+
+*``RTEMS.INVALID_ID`` - invalid object id*
+
+*``RTEMS.TOO_MANY`` - too many*
+
+*``RTEMS.TIMEOUT`` - timed out waiting*
+
+*``RTEMS.OBJECT_WAS_DELETED`` - object was deleted while waiting*
+
+*``RTEMS.INVALID_SIZE`` - invalid specified size*
+
+*``RTEMS.INVALID_ADDRESS`` - invalid address specified*
+
+*``RTEMS.INVALID_NUMBER`` - number was invalid*
+
+*``RTEMS.NOT_DEFINED`` - item not initialized*
+
+*``RTEMS.RESOURCE_IN_USE`` - resources outstanding*
+
+*``RTEMS.UNSATISFIED`` - request not satisfied*
+
+*``RTEMS.INCORRECT_STATE`` - task is in wrong state*
+
+*``RTEMS.ALREADY_SUSPENDED`` - task already in state*
+
+*``RTEMS.ILLEGAL_ON_SELF`` - illegal for calling task*
+
+*``RTEMS.ILLEGAL_ON_REMOTE_OBJECT`` - illegal for remote object*
+
+*``RTEMS.CALLED_FROM_ISR`` - invalid environment*
+
+*``RTEMS.INVALID_PRIORITY`` - invalid task priority*
+
+*``RTEMS.INVALID_CLOCK`` - invalid time buffer*
+
+*``RTEMS.INVALID_NODE`` - invalid node id*
+
+*``RTEMS.NOT_CONFIGURED`` - directive not configured*
+
+*``RTEMS.NOT_OWNER_OF_RESOURCE`` - not owner of resource*
+
+*``RTEMS.NOT_IMPLEMENTED`` - directive not implemented*
+
+*``RTEMS.INTERNAL_ERROR`` - RTEMS inconsistency detected*
+
+*``RTEMS.NO_MEMORY`` - could not get enough memory*
+
+Directives
+==========
+
+STATUS_TEXT - Returns the enumeration name for a status code
+------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+**DIRECTIVE STATUS CODES**
+
+The status code enumeration name or "?" in case the status code is invalid.
+
+**DESCRIPTION:**
+
+Returns the enumeration name for the specified status code.
+
+.. COMMENT: Copyright 2015 embedded brains GmbH
+
+.. COMMENT: All rights reserved.
+
+.. _Linker-Sets:
+
+Linker Sets
+###########
+
+.. index:: linkersets
+
+Introduction
+============
+
+Linker sets are a flexible means to create arrays of items out of a set of
+object files at link-time.  For example its possible to define an item *I*
+of type *T* in object file *A* and an item *J* of type *T*
+in object file *B* to be a member of a linker set *S*.  The linker
+will then collect these two items *I* and *J* and place them in
+consecutive memory locations, so that they can be accessed like a normal array
+defined in one object file.  The size of a linker set is defined by its begin
+and end markers.  A linker set may be empty.  It should only contain items of
+the same type.
+
+The following macros are provided to create, populate and use linker sets.
+
+- ``RTEMS_LINKER_SET_BEGIN`` - Designator of the linker set begin marker
+
+- ``RTEMS_LINKER_SET_END`` - Designator of the linker set end marker
+
+- ``RTEMS_LINKER_SET_SIZE`` - The linker set size in characters
+
+- ``RTEMS_LINKER_ROSET_DECLARE`` - Declares a read-only linker set
+
+- ``RTEMS_LINKER_ROSET`` - Defines a read-only linker set
+
+- ``RTEMS_LINKER_ROSET_ITEM_DECLARE`` - Declares a read-only linker set item
+
+- ``RTEMS_LINKER_ROSET_ITEM_REFERENCE`` - References a read-only linker set item
+
+- ``RTEMS_LINKER_ROSET_ITEM`` - Defines a read-only linker set item
+
+- ``RTEMS_LINKER_ROSET_ITEM_ORDERED`` - Defines an ordered read-only linker set item
+
+- ``RTEMS_LINKER_RWSET_DECLARE`` - Declares a read-write linker set
+
+- ``RTEMS_LINKER_RWSET`` - Defines a read-write linker set
+
+- ``RTEMS_LINKER_RWSET_ITEM_DECLARE`` - Declares a read-write linker set item
+
+- ``RTEMS_LINKER_RWSET_ITEM_REFERENCE`` - References a read-write linker set item
+
+- ``RTEMS_LINKER_RWSET_ITEM`` - Defines a read-write linker set item
+
+- ``RTEMS_LINKER_RWSET_ITEM_ORDERED`` - Defines an ordered read-write linker set item
+
+Background
+==========
+
+Linker sets are used not only in RTEMS, but also for example in Linux, in
+FreeBSD, for the GNU C constructor extension and for global C++ constructors.
+They provide a space efficient and flexible means to initialize modules.  A
+linker set consists of
+
+- dedicated input sections for the linker (e.g. ``.ctors`` and``.ctors.*`` in the case of global constructors),
+
+- a begin marker (e.g. provided by ``crtbegin.o``, and
+
+- an end marker (e.g. provided by ``ctrend.o``).
+
+A module may place a certain data item into the dedicated input section.  The
+linker will collect all such data items in this section and creates a begin and
+end marker.  The initialization code can then use the begin and end markers to
+find all the collected data items (e.g. pointers to initialization functions).
+
+In the linker command file of the GNU linker we need the following output
+section descriptions.
+.. code:: c
+
+    /* To be placed in a read-only memory region \*/
+    .rtemsroset : {
+    KEEP (\*(SORT(.rtemsroset.*)))
+    }
+    /* To be placed in a read-write memory region \*/
+    .rtemsrwset : {
+    KEEP (\*(SORT(.rtemsrwset.*)))
+    }
+
+The ``KEEP()`` ensures that a garbage collection by the linker will not
+discard the content of this section.  This would normally be the case since the
+linker set items are not referenced directly.  The ``SORT()`` directive
+sorts the input sections lexicographically.  Please note the lexicographical
+order of the ``.begin``, ``.content`` and ``.end`` section name parts
+in the RTEMS linker sets macros which ensures that the position of the begin
+and end markers are right.
+
+So, what is the benefit of using linker sets to initialize modules?  It can be
+used to initialize and include only those RTEMS managers and other components
+which are used by the application.  For example, in case an application uses
+message queues, it must call ``rtems_message_queue_create()``.  In the
+module implementing this function, we can place a linker set item and register
+the message queue handler constructor.  Otherwise, in case the application does
+not use message queues, there will be no reference to the``rtems_message_queue_create()`` function and the constructor is not
+registered, thus nothing of the message queue handler will be in the final
+executable.
+
+For an example see test program :file:`sptests/splinkersets01`.
+
+Directives
+==========
+
+RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker
+------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_SET_BEGIN
+
+.. code:: c
+
+    volatile type \*begin = RTEMS_LINKER_SET_BEGIN( set );
+
+**DESCRIPTION:**
+
+This macro generates the designator of the begin marker of the linker set
+identified by ``set``.  The item at the begin marker address is the first
+member of the linker set if it exists, e.g. the linker set is not empty.  A
+linker set is empty, if and only if the begin and end markers have the same
+address.
+The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set.
+
+RTEMS_LINKER_SET_END - Designator of the linker set end marker
+--------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_SET_END
+
+.. code:: c
+
+    volatile type \*end = RTEMS_LINKER_SET_END( set );
+
+**DESCRIPTION:**
+
+This macro generates the designator of the end marker of the linker set
+identified by ``set``.  The item at the end marker address is not a member
+of the linker set.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set.
+
+RTEMS_LINKER_SET_SIZE - The linker set size in characters
+---------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_SET_SIZE
+
+.. code:: c
+
+    size_t size = RTEMS_LINKER_SET_SIZE( set );
+
+**DESCRIPTION:**
+
+This macro returns the size of the linker set identified by ``set`` in
+characters.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set.
+
+RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set
+------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_ROSET_DECLARE
+
+.. code:: c
+
+    RTEMS_LINKER_ROSET_DECLARE( set, type );
+
+**DESCRIPTION:**
+
+This macro generates declarations for the begin and end markers of a read-only
+linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set.
+
+RTEMS_LINKER_ROSET - Defines a read-only linker set
+---------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_ROSET
+
+.. code:: c
+
+    RTEMS_LINKER_ROSET( set, type );
+
+**DESCRIPTION:**
+
+This macro generates definitions for the begin and end markers of a read-only
+linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set.
+
+RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item
+----------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE
+
+.. code:: c
+
+    RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item );
+
+**DESCRIPTION:**
+
+This macro generates a declaration of an item contained in the read-only linker
+set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set.
+
+RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item
+--------------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE
+
+.. code:: c
+
+    RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item );
+
+**DESCRIPTION:**
+
+This macro generates a reference to an item contained in the read-only linker set
+identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set.
+
+RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item
+-------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_ROSET_ITEM
+
+.. code:: c
+
+    RTEMS_LINKER_ROSET_ITEM( set, type, item );
+
+**DESCRIPTION:**
+
+This macro generates a definition of an item contained in the read-only linker set
+identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set.
+
+RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item
+------------------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED
+
+.. code:: c
+
+    RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order );
+
+**DESCRIPTION:**
+
+This macro generates a definition of an ordered item contained in the read-only
+linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set.
+The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set. The ``order`` parameter must be a valid linker input section name part on
+which macro expansion is performed.  The items are lexicographically ordered
+according to the ``order`` parameter within a linker set.  Ordered items are
+placed before unordered items in the linker set.
+
+**NOTES:**
+
+To be resilient to typos in the order parameter, it is recommended to use the
+following construct in macros defining items for a particular linker set (see
+enum in ``XYZ_ITEM()``).
+.. code:: c
+
+    #include <rtems/linkersets.h>
+    typedef struct {
+    int foo;
+    } xyz_item;
+    /* The XYZ-order defines \*/
+    #define XYZ_ORDER_FIRST 0x00001000
+    #define XYZ_ORDER_AND_SO_ON 0x00002000
+    /* Defines an ordered XYZ-item \*/
+    #define XYZ_ITEM( item, order ) \\
+    enum { xyz_##item = order - order }; \\
+    RTEMS_LINKER_ROSET_ITEM_ORDERED( \\
+    xyz, const xyz_item \*, item, order \\
+    ) = { &item }
+    /* Example item \*/
+    static const xyz_item some_item = { 123 };
+    XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
+
+RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set
+-------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_RWSET_DECLARE
+
+.. code:: c
+
+    RTEMS_LINKER_RWSET_DECLARE( set, type );
+
+**DESCRIPTION:**
+
+This macro generates declarations for the begin and end markers of a read-write
+linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set.
+
+RTEMS_LINKER_RWSET - Defines a read-write linker set
+----------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_RWSET
+
+.. code:: c
+
+    RTEMS_LINKER_RWSET( set, type );
+
+**DESCRIPTION:**
+
+This macro generates definitions for the begin and end markers of a read-write
+linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set.
+
+RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item
+-----------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE
+
+.. code:: c
+
+    RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item );
+
+**DESCRIPTION:**
+
+This macro generates a declaration of an item contained in the read-write linker
+set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set.
+
+RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item
+---------------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE
+
+.. code:: c
+
+    RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item );
+
+**DESCRIPTION:**
+
+This macro generates a reference to an item contained in the read-write linker set
+identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set.
+
+RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item
+--------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_RWSET_ITEM
+
+.. code:: c
+
+    RTEMS_LINKER_RWSET_ITEM( set, type, item );
+
+**DESCRIPTION:**
+
+This macro generates a definition of an item contained in the read-write linker set
+identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set.
+
+RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item
+-------------------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED
+
+.. code:: c
+
+    RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order );
+
+**DESCRIPTION:**
+
+This macro generates a definition of an ordered item contained in the read-write
+linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
+must be the same for all macro invocations of a particular linker set.
+The ``item`` parameter itself must be a valid C designator on which no macro
+expansion is performed.  It uniquely identifies an item in the linker set. The ``order`` parameter must be a valid linker input section name part on
+which macro expansion is performed.  The items are lexicographically ordered
+according to the ``order`` parameter within a linker set.  Ordered items are
+placed before unordered items in the linker set.
+
+**NOTES:**
+
+To be resilient to typos in the order parameter, it is recommended to use the
+following construct in macros defining items for a particular linker set (see
+enum in ``XYZ_ITEM()``).
+.. code:: c
+
+    #include <rtems/linkersets.h>
+    typedef struct {
+    int foo;
+    } xyz_item;
+    /* The XYZ-order defines \*/
+    #define XYZ_ORDER_FIRST 0x00001000
+    #define XYZ_ORDER_AND_SO_ON 0x00002000
+    /* Defines an ordered XYZ-item \*/
+    #define XYZ_ITEM( item, order ) \\
+    enum { xyz_##item = order - order }; \\
+    RTEMS_LINKER_RWSET_ITEM_ORDERED( \\
+    xyz, const xyz_item \*, item, order \\
+    ) = { &item }
+    /* Example item \*/
+    static const xyz_item some_item = { 123 };
+    XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
+
+.. COMMENT: COPYRIGHT (c) 1989-2014.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Example Application
+###################
+
+.. code:: c
+
+    Currently there is no example Ada application provided.
+
+.. COMMENT: COPYRIGHT (c) 1989-2011.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+
+Glossary
+########
+
+:dfn:`active`
+    A term used to describe an object
+    which has been created by an application.
+
+:dfn:`aperiodic task`
+    A task which must execute only at
+    irregular intervals and has only a soft deadline.
+
+:dfn:`application`
+    In this document, software which makes
+    use of RTEMS.
+
+:dfn:`ASR`
+    see Asynchronous Signal Routine.
+
+:dfn:`asynchronous`
+    Not related in order or timing to
+    other occurrences in the system.
+
+:dfn:`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.
+
+:dfn:`atomic operations`
+    Atomic operations are defined in terms of *ISO/IEC 9899:2011*.
+
+:dfn:`awakened`
+    A term used to describe a task that has
+    been unblocked and may be scheduled to the CPU.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`block`
+    A physically contiguous area of memory.
+
+:dfn:`blocked task`
+    The task state entered by a task which has been previously started and cannot
+    continue execution until the reason for waiting has been satisfied.  Blocked
+    tasks are not an element of the set of ready tasks of a scheduler instance.
+
+:dfn:`broadcast`
+    To simultaneously send a message to a
+    logical set of destinations.
+
+:dfn:`BSP`
+    see Board Support Package.
+
+:dfn:`Board Support Package`
+    A collection of device
+    initialization and control routines specific to a particular
+    type of board or collection of boards.
+
+:dfn:`buffer`
+    A fixed length block of memory allocated
+    from a partition.
+
+:dfn:`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.
+
+:dfn:`Central Processing Unit`
+    This term is equivalent to
+    the terms processor and microprocessor.
+
+:dfn:`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.
+
+:dfn:`cluster`
+    We have clustered scheduling in case the set of processors of a system is
+    partitioned into non-empty pairwise disjoint subsets.  These subsets are called:dfn:`clusters`.  Clusters with a cardinality of one are partitions.  Each
+    cluster is owned by exactly one scheduler instance.
+
+:dfn:`coalesce`
+    The process of merging adjacent holes into
+    a single larger hole.  Sometimes this process is referred to as
+    garbage collection.
+
+:dfn:`Configuration Table`
+    A table which contains
+    information used to tailor RTEMS for a particular application.
+
+:dfn:`context`
+    All of the processor registers and
+    operating system data structures associated with a task.
+
+:dfn:`context switch`
+    Alternate term for task switch.
+    Taking control of the processor from one task and transferring
+    it to another task.
+
+:dfn:`control block`
+    A data structure used by the
+    executive to define and control an object.
+
+:dfn:`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.
+
+:dfn:`CPU`
+    An acronym for Central Processing Unit.
+
+:dfn:`critical section`
+    A section of code which must be
+    executed indivisibly.
+
+:dfn:`CRT`
+    An acronym for Cathode Ray Tube.  Normally used
+    in reference to the man-machine interface.
+
+:dfn:`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.
+
+:dfn:`device`
+    A peripheral used by the application that
+    requires special operation software.  See also device driver.
+
+:dfn:`device driver`
+    Control software for special
+    peripheral devices used by the application.
+
+:dfn:`directives`
+    RTEMSâ provided routines that provide
+    support mechanisms for real-time applications.
+
+:dfn:`dispatch`
+    The act of loading a taskâs context onto
+    the CPU and transferring control of the CPU to that task.
+
+:dfn:`dormant`
+    The state entered by a task after it is
+    created and before it has been started.
+
+:dfn:`Device Driver Table`
+    A table which contains the
+    entry points for each of the configured device drivers.
+
+:dfn:`dual-ported`
+    A term used to describe memory which
+    can be accessed at two different addresses.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`events`
+    A method for task communication and
+    synchronization. The directives provided by the event manager
+    are used to service events.
+
+:dfn:`exception`
+    A synonym for interrupt.
+
+:dfn:`executing task`
+    The task state entered by a task after it has been given control of the
+    processor.  On SMP configurations a task may be registered as executing on more
+    than one processor for short time frames during task migration.  Blocked tasks
+    can be executing until they issue a thread dispatch.
+
+:dfn:`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.
+
+:dfn:`exported`
+    An object known by all nodes in a
+    multiprocessor system.  An object created with the GLOBAL
+    attribute will be exported.
+
+:dfn:`external address`
+    The address used to access
+    dual-ported memory by all the nodes in a system which do not own
+    the memory.
+
+:dfn:`FIFO`
+    An acronym for First In First Out.
+
+:dfn:`First In First Out`
+    A discipline for manipulating entries in a data structure.
+
+:dfn:`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.
+
+:dfn:`freed`
+    A resource that has been released by the
+    application to RTEMS.
+
+:dfn:`Giant lock`
+    The :dfn:`Giant lock` is a recursive SMP lock protecting most parts of the
+    operating system state.  Virtually every operating system service must acquire
+    and release the Giant lock during its operation.
+
+:dfn:`global`
+    An object that has been created with the
+    GLOBAL attribute and exported to all nodes in a multiprocessor
+    system.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`heap`
+    A data structure used to dynamically allocate
+    and deallocate variable sized blocks of memory.
+
+:dfn:`heir task`
+    A task is an :dfn:`heir` if it is registered as an heir in a processor of the
+    system.  A task can be the heir on at most one processor in the system.  In
+    case the executing and heir tasks differ on a processor and a thread dispatch
+    is marked as necessary, then the next thread dispatch will make the heir task
+    the executing task.
+
+:dfn:`heterogeneous`
+    A multiprocessor computer system composed of dissimilar processors.
+
+:dfn:`homogeneous`
+    A multiprocessor computer system composed of a single type of processor.
+
+:dfn:`ID`
+    An RTEMS assigned identification tag used to
+    access an active object.
+
+:dfn:`IDLE task`
+    A special low priority task which assumes
+    control of the CPU when no other task is able to execute.
+
+:dfn:`interface`
+    A specification of the methodology used
+    to connect multiple independent subsystems.
+
+:dfn:`internal address`
+    The address used to access
+    dual-ported memory by the node which owns the memory.
+
+:dfn:`interrupt`
+    A hardware facility that causes the CPU
+    to suspend execution, save its status, and transfer control to a
+    specific location.
+
+:dfn:`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.
+
+:dfn:`Interrupt Service Routine`
+    An ISR is invoked by the
+    CPU to process a pending interrupt.
+
+:dfn:`I/O`
+    An acronym for Input/Output.
+
+:dfn:`ISR`
+    An acronym for Interrupt Service Routine.
+
+:dfn:`kernel`
+    In this document, this term is used as a
+    synonym for executive.
+
+:dfn:`list`
+    A data structure which allows for dynamic
+    addition and removal of entries.  It is not statically limited
+    to a particular size.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`local operation`
+    The manipulation of an object which
+    resides on the same node as the calling task.
+
+:dfn:`logical address`
+    An address used by an application.
+    In a system without memory management, logical addresses will
+    equal physical addresses.
+
+:dfn:`loosely-coupled`
+    A multiprocessor configuration
+    where shared memory is not used for communication.
+
+:dfn:`major number`
+    The index of a device driver in the
+    Device Driver Table.
+
+:dfn:`manager`
+    A group of related RTEMSâ directives which
+    provide access and control over resources.
+
+:dfn:`memory pool`
+    Used interchangeably with heap.
+
+:dfn:`message`
+    A sixteen byte entity used to communicate
+    between tasks.  Messages are sent to message queues and stored
+    in message buffers.
+
+:dfn:`message buffer`
+    A block of memory used to store
+    messages.
+
+:dfn:`message queue`
+    An RTEMS object used to synchronize
+    and communicate between tasks by transporting messages between
+    sending and receiving tasks.
+
+:dfn:`Message Queue Control Block`
+    A data structure associated with each message queue used by RTEMS
+    to manage that message queue.
+
+:dfn:`minor number`
+    A numeric value passed to a device
+    driver, the exact usage of which is driver dependent.
+
+:dfn:`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.
+
+:dfn:`MPCI`
+    An acronym for Multiprocessor Communications
+    Interface Layer.
+
+:dfn:`multiprocessing`
+    The simultaneous execution of two
+    or more processes by a multiple processor computer system.
+
+:dfn:`multiprocessor`
+    A computer with multiple CPUs
+    available for executing applications.
+
+:dfn:`Multiprocessor Communications Interface Layer`
+    A set
+    of user-provided routines which enable the nodes in a
+    multiprocessor system to communicate with one another.
+
+:dfn:`Multiprocessor Configuration Table`
+    The data structure defining the characteristics of the multiprocessor
+    target system with which RTEMS will communicate.
+
+:dfn:`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.
+
+:dfn:`mutual exclusion`
+    A term used to describe the act of
+    preventing other tasks from accessing a resource simultaneously.
+
+:dfn:`nested`
+    A term used to describe an ASR that occurs
+    during another ASR or an ISR that occurs during another ISR.
+
+:dfn:`node`
+    A term used to reference a processor running
+    RTEMS in a multiprocessor system.
+
+:dfn:`non-existent`
+    The state occupied by an uncreated or
+    deleted task.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`operating system`
+    The software which controls all
+    the computerâs resources and provides the base upon which
+    application programs can be written.
+
+:dfn:`overhead`
+    The portion of the CPUs processing power
+    consumed by the operating system.
+
+:dfn:`packet`
+    A buffer which contains the messages passed
+    between nodes in a multiprocessor system.  A packet is the
+    contents of an envelope.
+
+:dfn:`partition`
+    An RTEMS object which is used to allocate
+    and deallocate fixed size blocks of memory from an dynamically
+    specified area of memory.
+
+:dfn:`partition`
+    Clusters with a cardinality of one are :dfn:`partitions`.
+
+:dfn:`Partition Control Block`
+    A data structure associated
+    with each partition used by RTEMS to manage that partition.
+
+:dfn:`pending`
+    A term used to describe a task blocked
+    waiting for an event, message, semaphore, or signal.
+
+:dfn:`periodic task`
+    A task which must execute at regular
+    intervals and comply with a hard deadline.
+
+:dfn:`physical address`
+    The actual hardware address of a
+    resource.
+
+:dfn:`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.
+
+:dfn:`pool`
+    A collection from which resources are
+    allocated.
+
+:dfn:`portability`
+    A term used to describe the ease with
+    which software can be rehosted on another computer.
+
+:dfn:`posting`
+    The act of sending an event, message,
+    semaphore, or signal to a task.
+
+:dfn:`preempt`
+    The act of forcing a task to relinquish the
+    processor and dispatching to another task.
+
+:dfn:`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.
+
+:dfn:`priority boosting`
+    A simple approach to extend the priority inheritance protocol for clustered
+    scheduling is :dfn:`priority boosting`.  In case a mutex is owned by a task of
+    another cluster, then the priority of the owner task is raised to an
+    artificially high priority, the pseudo-interrupt priority.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`processor utilization`
+    The percentage of processor
+    time used by a task or a set of tasks.
+
+:dfn:`proxy`
+    An RTEMS control structure used to represent,
+    on a remote node, a task which must block as part of a remote
+    operation.
+
+:dfn:`Proxy Control Block`
+    A data structure associated
+    with each proxy used by RTEMS to manage that proxy.
+
+:dfn:`PTCB`
+    An acronym for Partition Control Block.
+
+:dfn:`PXCB`
+    An acronym for Proxy Control Block.
+
+:dfn:`quantum`
+    The application defined unit of time in
+    which the processor is allocated.
+
+:dfn:`queue`
+    Alternate term for message queue.
+
+:dfn:`QCB`
+    An acronym for Message Queue Control Block.
+
+:dfn:`ready task`
+    A task occupies this state when it is available to be given control of a
+    processor.  A ready task has no processor assigned.  The scheduler decided that
+    other tasks are currently more important.  A task that is ready to execute and
+    has a processor assigned is called scheduled.
+
+:dfn:`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.
+
+:dfn:`reentrant`
+    A term used to describe routines which do
+    not modify themselves or global variables.
+
+:dfn:`region`
+    An RTEMS object which is used to allocate
+    and deallocate variable size blocks of memory from a dynamically
+    specified area of memory.
+
+:dfn:`Region Control Block`
+    A data structure associated
+    with each region used by RTEMS to manage that region.
+
+:dfn:`registers`
+    Registers are locations physically
+    located within a component, typically used for device control or
+    general purpose storage.
+
+:dfn:`remote`
+    Any object that does not reside on the local
+    node.
+
+:dfn:`remote operation`
+    The manipulation of an object
+    which does not reside on the same node as the calling task.
+
+:dfn:`return code`
+    Also known as error code or return
+    value.
+
+:dfn:`resource`
+    A hardware or software entity to which
+    access must be controlled.
+
+:dfn:`resume`
+    Removing a task from the suspend state.  If
+    the taskâs state is ready following a call to the ``rtems.task_resume``
+    directive, then the task is available for scheduling.
+
+:dfn:`return code`
+    A value returned by RTEMS directives to
+    indicate the completion status of the directive.
+
+:dfn:`RNCB`
+    An acronym for Region Control Block.
+
+:dfn:`round-robin`
+    A task scheduling discipline in which
+    tasks of equal priority are executed in the order in which they
+    are made ready.
+
+:dfn:`RS-232`
+    A standard for serial communications.
+
+:dfn:`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.
+
+:dfn:`schedulable`
+    A set of tasks which can be guaranteed
+    to meet their deadlines based upon a specific scheduling
+    algorithm.
+
+:dfn:`schedule`
+    The process of choosing which task should
+    next enter the executing state.
+
+:dfn:`scheduled task`
+    A task is :dfn:`scheduled` if it is allowed to execute and has a processor
+    assigned.  Such a task executes currently on a processor or is about to start
+    execution.  A task about to start execution it is an heir task on exactly one
+    processor in the system.
+
+:dfn:`scheduler`
+    A :dfn:`scheduler` or :dfn:`scheduling algorithm` allocates processors to a
+    subset of its set of ready tasks.  So it manages access to the processor
+    resource.  Various algorithms exist to choose the tasks allowed to use a
+    processor out of the set of ready tasks.  One method is to assign each task a
+    priority number and assign the tasks with the lowest priority number to one
+    processor of the set of processors owned by a scheduler instance.
+
+:dfn:`scheduler instance`
+    A :dfn:`scheduler instance` is a scheduling algorithm with a corresponding
+    context to store its internal state.  Each processor in the system is owned by
+    at most one scheduler instance.  The processor to scheduler instance assignment
+    is determined at application configuration time.  See :ref:`Configuring a System
+    Configuring Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
+
+:dfn:`segments`
+    Variable sized memory blocks allocated
+    from a region.
+
+:dfn:`semaphore`
+    An RTEMS object which is used to
+    synchronize tasks and provide mutually exclusive access to
+    resources.
+
+:dfn:`Semaphore Control Block`
+    A data structure associated
+    with each semaphore used by RTEMS to manage that semaphore.
+
+:dfn:`shared memory`
+    Memory which is accessible by
+    multiple nodes in a multiprocessor system.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`SMCB`
+    An acronym for Semaphore Control Block.
+
+:dfn:`SMP locks`
+    The :dfn:`SMP locks` ensure mutual exclusion on the lowest level and are a
+    replacement for the sections of disabled interrupts.  Interrupts are usually
+    disabled while holding an SMP lock.  They are implemented using atomic
+    operations.  Currently a ticket lock is used in RTEMS.
+
+:dfn:`SMP barriers`
+    The :dfn:`SMP barriers` ensure that a defined set of independent threads of
+    execution on a set of processors reaches a common synchronization point in
+    time.  They are implemented using atomic operations.  Currently a sense barrier
+    is used in RTEMS.
+
+:dfn:`soft real-time system`
+    A real-time system in which a
+    missed deadline does not compromise the integrity of the system.
+
+:dfn:`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.
+
+:dfn:`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.
+
+:dfn:`status code`
+    Also known as error code or return
+    value.
+
+:dfn:`suspend`
+    A term used to describe a task that is not
+    competing for the CPU because it has had a ``rtems.task_suspend`` directive.
+
+:dfn:`synchronous`
+    Related in order or timing to other
+    occurrences in the system.
+
+:dfn:`system call`
+    In this document, this is used as an
+    alternate term for directive.
+
+:dfn:`target`
+    The system on which the application will
+    ultimately execute.
+
+:dfn:`task`
+    A logically complete thread of execution.  It consists normally of a set of
+    registers and a stack.  The terms :dfn:`task` and :dfn:`thread` are synonym in
+    RTEMS.  The scheduler assigns processors to a subset of the ready tasks.
+
+:dfn:`Task Control Block`
+    A data structure associated with
+    each task used by RTEMS to manage that task.
+
+:dfn:`task migration`
+    :dfn:`Task migration` happens in case a task stops execution on one processor
+    and resumes execution on another processor.
+
+:dfn:`task processor affinity`
+    The set of processors on which a task is allowed to execute.
+
+:dfn:`task switch`
+    Alternate terminology for context
+    switch.  Taking control of the processor from one task and given
+    to another.
+
+:dfn:`TCB`
+    An acronym for Task Control Block.
+
+:dfn:`thread dispatch`
+    The :dfn:`thread dispatch` transfers control of the processor from the currently
+    executing thread to the heir thread of the processor.
+
+:dfn:`tick`
+    The basic unit of time used by RTEMS.  It is a
+    user-configurable number of microseconds.  The current tick
+    expires when the ``rtems.clock_tick``
+    directive is invoked.
+
+:dfn:`tightly-coupled`
+    A multiprocessor configuration
+    system which communicates via shared memory.
+
+:dfn:`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.
+
+:dfn:`timer`
+    An RTEMS object used to invoke subprograms at
+    a later time.
+
+:dfn:`Timer Control Block`
+    A data structure associated
+    with each timer used by RTEMS to manage that timer.
+
+:dfn:`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.
+
+:dfn:`timeslice`
+    The application defined unit of time in
+    which the processor is allocated.
+
+:dfn:`TMCB`
+    An acronym for Timer Control Block.
+
+:dfn:`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.
+
+:dfn:`user extensions`
+    Software routines provided by the
+    application to enhance the functionality of RTEMS.
+
+:dfn:`User Extension Table`
+    A table which contains the
+    entry points for each user extensions.
+
+:dfn:`User Initialization Tasks Table`
+    A table which
+    contains the information needed to create and start each of the
+    user initialization tasks.
+
+:dfn:`user-provided`
+    Alternate term for user-supplied.
+    This term is used to designate any software routines which must
+    be written by the application designer.
+
+:dfn:`user-supplied`
+    Alternate term for user-provided.
+    This term is used to designate any software routines which must
+    be written by the application designer.
+
+:dfn:`vector`
+    Memory pointers used by the processor to
+    fetch the address of routines which will handle various
+    exceptions and interrupts.
+
+:dfn:`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.
+
+:dfn:`yield`
+    When a task voluntarily releases control of the processor.
+
+Command and Variable Index
+##########################
+
+.. COMMENT: There are currently no Command and Variable Index entries.
+
+Concept Index
+#############
+
+.. COMMENT: There are currently no Concept Index entries.
+
Index: ada_user/index.rst
===================================================================
--- ada_user/index.rst	(revision 5daabd23cfd13662e74ce8d069204882eb1fbad9)
+++ ada_user/index.rst	(revision 5daabd23cfd13662e74ce8d069204882eb1fbad9)
@@ -0,0 +1,1 @@
+.. include:: ada_user.rst
Index: ada_user/wscript
===================================================================
--- ada_user/wscript	(revision 5daabd23cfd13662e74ce8d069204882eb1fbad9)
+++ ada_user/wscript	(revision 5daabd23cfd13662e74ce8d069204882eb1fbad9)
@@ -0,0 +1,19 @@
+from sys import path
+from os.path import abspath
+path.append(abspath('../common/'))
+
+from waf import cmd_configure, cmd_build
+
+def configure(ctx):
+	cmd_configure(ctx)
+
+def build(ctx):
+
+	sub = {
+		"VERSION":				"1.0",
+		"RELEASE":				"5.0.0",
+		"DOC":					"ADA User",
+		"FILE_DOC":				"rtemsada_user",
+	}
+
+	cmd_build(ctx, sub)
