summaryrefslogtreecommitdiffstats
path: root/c-user/overview.rst
diff options
context:
space:
mode:
Diffstat (limited to 'c-user/overview.rst')
-rw-r--r--c-user/overview.rst427
1 files changed, 427 insertions, 0 deletions
diff --git a/c-user/overview.rst b/c-user/overview.rst
new file mode 100644
index 0000000..273e5ed
--- /dev/null
+++ b/c-user/overview.rst
@@ -0,0 +1,427 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
+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.
+
+.. figure:: ../images/c_user/rtemsarc.png
+ :width: 488
+ :height: 100px
+ :align: center
+ :alt: RTEMS Application Architecture
+
+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:
+
+.. figure:: ../images/c_user/rtemspie.png
+ :width: 70%
+ :align: center
+ :alt: RTEMS Internal Architecture
+
+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`.
+
+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.