rtems-docs/c-user/overview.rst

.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)

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.

.. index:: Real-time applications

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.

.. index:: Real-time executive

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.

.. index:: Application architecture

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.

.. index:: Internal Architecture

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 3:
    Key Concepts: presents an introduction to the ideas which are common across
    multiple RTEMS managers.

Chapter 4:
    RTEMS Data Types: describes the fundamental data types shared by the
    services in the RTEMS Classic API.

Chapter 5:
    Scheduling Concepts: details the various RTEMS scheduling algorithms and
    task state transitions.

Chapter 6:
    Initialization Manager: describes the functionality and directives provided
    by the Initialization Manager.

Chapter 7:
    Task Manager: describes the functionality and directives provided by the
    Task Manager.

Chapter 8:
    Interrupt Manager: describes the functionality and directives provided by
    the Interrupt Manager.

Chapter 9:
    Clock Manager: describes the functionality and directives provided by the
    Clock Manager.

Chapter 10:
    Timer Manager: describes the functionality and directives provided by the
    Timer Manager.

Chapter 11:
    Rate Monotonic Manager: describes the functionality and directives provided
    by the Rate Monotonic Manager.

Chapter 12:
    Semaphore Manager: describes the functionality and directives provided by
    the Semaphore Manager.

Chapter 13:
    Barrier Manager: describes the functionality and directives provided by the
    Barrier Manager.

Chapter 14:
    Message Manager: describes the functionality and directives provided by the
    Message Manager.

Chapter 15:
    Event Manager: describes the functionality and directives provided by the
    Event Manager.

Chapter 16:
    Signal Manager: describes the functionality and directives provided by the
    Signal Manager.

Chapter 17:
    Partition Manager: describes the functionality and directives provided by
    the Partition Manager.

Chapter 18:
    Region Manager: describes the functionality and directives provided by the
    Region Manager.

Chapter 19:
    Dual-Ported Memory Manager: describes the functionality and directives
    provided by the Dual-Ported Memory Manager.

Chapter 20:
    I/O Manager: describes the functionality and directives provided by the I/O
    Manager.

Chapter 21:
    Fatal Error Manager: describes the functionality and directives provided by
    the Fatal Error Manager.

Chapter 22:
    Board Support Packages: defines the functionality required of user-supplied
    board support packages.

Chapter 23:
    User Extensions: shows the user how to extend RTEMS to incorporate custom
    features.

Chapter 24:
    Configuring a System: details the process by which one tailors RTEMS for a
    particular single-processor or multiprocessor application.

Chapter 25:
    Self-Contained Objects: contains information about objects like threads,
    mutexes and semaphores.

Chapter 26:
    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 27:
    Symmetric Multiprocessing (SMP): information regarding the SMP features.

Chapter 28:
    PCI Library: information about using the PCI bus in RTEMS.

Chapter 29:
    Stack Bounds Checker: presents the capabilities of the RTEMS task stack
    checker which can report stack usage as well as detect bounds violations.

Chapter 30:
    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 31:
    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 32:
    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 33:
    Red-Black Trees: information about how to use the Red-Black Tree API.

Chapter 34:
    Timespec Helpers: presents a set of helper services useful when
    manipulating POSIX ``struct timespec`` instances.

Chapter 35:
    Constant Bandwidth Server Scheduler API.

Chapter 36:
    Ada Support: information about Ada programming language support.

Chapter 37:
    Directive Status Codes: provides a definition of each of the directive
    status codes referenced in this manual.

Chapter 38:
    Linker Sets: information about linker set features.

Chapter 39:
    Example Application: provides a template for simple RTEMS applications.

Chapter 40:
    Glossary: defines terms used throughout this manual.

Chapter 41:
    References: References.

Chapter 42:
    Index: Index.