Split document into seperate files by section.

1 files changed, 489 insertions, 0 deletions

diff --git a/c_user/overview.rst b/c_user/overview.rst
new file mode 100644
index 0000000..6b4d125
--- /dev/null
+++ b/c_user/overview.rst
@@ -0,0 +1,489 @@
+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 C 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 `Configuring a System`_.
+
+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 C, a basic
+understanding of the C programming language
+is required to fully
+understand the material presented.  However, because of the
+similarity of the Ada and C RTEMS implementations, users will
+find that the use and behavior of the two implementations is
+very similar.  A working knowledge of the target processor is
+helpful in understanding some of RTEMS’ features.  A thorough
+understanding of the executive cannot be obtained without
+studying the entire manual because many of RTEMS’ concepts and
+features are interrelated.  Experienced RTEMS users will find
+that the manual organization facilitates its use as a reference
+document.
+
+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
+  structure 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
+