source: rtems-docs/c_user/overview.rst @ 9aafb39

Last change on this file since 9aafb39 was 9aafb39, checked in by Chris Johns <chrisj@…>, on Oct 28, 2016 at 12:56:02 PM

c_user: Remove errors and warnings.

  • Property mode set to 100644
File size: 16.4 KB
[489740f]1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
[b8d3f6b]3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
[b8d3f6b]13RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive
14(kernel) which provides a high performance environment for embedded military
15applications including the following features:
17- multitasking capabilities
19- homogeneous and heterogeneous multiprocessor systems
21- event-driven, priority-based, preemptive scheduling
23- optional rate monotonic scheduling
25- intertask communication and synchronization
27- priority inheritance
29- responsive interrupt management
31- dynamic memory allocation
33- high level of user configurability
[b8d3f6b]35This manual describes the usage of RTEMS for applications written in the C
36programming language.  Those implementation details that are processor
37dependent are provided in the Applications Supplement documents.  A supplement
38document which addresses specific architectural issues that affect RTEMS is
39provided for each processor type that is supported.
41Real-time Application Systems
[b8d3f6b]44Real-time application systems are a special class of computer applications.
45They have a complex set of characteristics that distinguish them from other
46software problems.  Generally, they must adhere to more rigorous requirements.
47The correctness of the system depends not only on the results of computations,
48but also on the time at which the results are produced.  The most important and
49complex characteristic of real-time application systems is that they must
50receive and respond to a set of external stimuli within rigid and critical time
51constraints referred to as deadlines.  Systems can be buried by an avalanche of
52interdependent, asynchronous or cyclical event streams.
54Deadlines can be further characterized as either hard or soft based upon the
55value of the results when produced after the deadline has passed.  A deadline
56is hard if the results have no value or if their use will result in a
57catastrophic event.  In contrast, results which are produced after a soft
58deadline may have some value.
60Another distinguishing requirement of real-time application systems is the
61ability to coordinate or manage a large number of concurrent activities. Since
62software is a synchronous entity, this presents special problems.  One
63instruction follows another in a repeating synchronous cycle.  Even though
64mechanisms have been developed to allow for the processing of external
65asynchronous events, the software design efforts required to process and manage
66these events and tasks are growing more complicated.
68The design process is complicated further by spreading this activity over a set
69of processors instead of a single processor. The challenges associated with
70designing and building real-time application systems become very complex when
71multiple processors are involved.  New requirements such as interprocessor
72communication channels and global resources that must be shared between
73competing processors are introduced.  The ramifications of multiple processors
74complicate each and every characteristic of a real-time system.
76Real-time Executive
[b8d3f6b]79Fortunately, real-time operating systems or real-time executives serve as a
80cornerstone on which to build the application system.  A real-time multitasking
81executive allows an application to be cast into a set of logical, autonomous
82processes or tasks which become quite manageable.  Each task is internally
83synchronous, but different tasks execute independently, resulting in an
84asynchronous processing stream.  Tasks can be dynamically paused for many
85reasons resulting in a different task being allowed to execute for a period of
86time.  The executive also provides an interface to other system components such
87as interrupt handlers and device drivers.  System components may request the
88executive to allocate and coordinate resources, and to wait for and trigger
89synchronizing conditions.  The executive system calls effectively extend the
90CPU instruction set to support efficient multitasking.  By causing tasks to
91travel through well-defined state transitions, system calls permit an
92application to demand-switch between tasks in response to real-time events.
94By proper grouping of responses to stimuli into separate tasks, a system can
95now asynchronously switch between independent streams of execution, directly
96responding to external stimuli as they occur.  This allows the system design to
97meet critical performance specifications which are typically measured by
98guaranteed response time and transaction throughput.  The multiprocessor
99extensions of RTEMS provide the features necessary to manage the extra
100requirements introduced by a system distributed across several processors.  It
101removes the physical barriers of processor boundaries from the world of the
102system designer, enabling more critical aspects of the system to receive the
103required attention. Such a system, based on an efficient real-time,
104multiprocessor executive, is a more realistic model of the outside world or
105environment for which it is designed.  As a result, the system will always be
106more logical, efficient, and reliable.
108By using the directives provided by RTEMS, the real-time applications developer
109is freed from the problem of controlling and synchronizing multiple tasks and
110processors.  In addition, one need not develop, test, debug, and document
111routines to manage memory, pass messages, or provide mutual exclusion.  The
112developer is then able to concentrate solely on the application.  By using
113standard software components, the time and cost required to develop
114sophisticated real-time applications is significantly reduced.
116RTEMS Application Architecture
[b8d3f6b]119One important design goal of RTEMS was to provide a bridge between two critical
120layers of typical real-time systems.  As shown in the following figure, RTEMS
121serves as a buffer between the project dependent application code and the
122target hardware.  Most hardware dependencies for real-time applications can be
[fd6dc8c]123localized to the low level device drivers.
[170418a]125.. figure:: ../images/c_user/rtemsarc.png
[b8d3f6b]126         :width: 488
127         :height: 100px
128         :align: center
129         :alt: RTEMS Application Architecture
131The RTEMS I/O interface manager provides an efficient tool for incorporating
[b8d3f6b]132these hardware dependencies into the system while simultaneously providing a
133general mechanism to the application code that accesses them.  A well designed
134real-time system can benefit from this architecture by building a rich library
135of standard application components which can be used repeatedly in other
[fd6dc8c]136real-time projects.
138RTEMS Internal Architecture
[b8d3f6b]141RTEMS can be viewed as a set of layered components that work in harmony to
142provide a set of services to a real-time application system.  The executive
143interface presented to the application is formed by grouping directives into
144logical sets called resource managers.  Functions utilized by multiple managers
145such as scheduling, dispatching, and object management are provided in the
146executive core.  The executive core depends on a small set of CPU dependent
147routines.  Together these components provide a powerful run time environment
148that promotes the development of efficient real-time application systems.  The
149following figure illustrates this organization:
[170418a]151.. figure:: ../images/c_user/rtemspie.png
[b8d3f6b]152         :width: 70%
153         :align: center
154         :alt: RTEMS Internal Architecture
156Subsequent chapters present a detailed description of the capabilities provided
157by each of the following RTEMS managers:
159- initialization
161- task
163- interrupt
165- clock
167- timer
169- semaphore
171- message
173- event
175- signal
177- partition
179- region
181- dual ported memory
183- I/O
185- fatal error
187- rate monotonic
189- user extensions
191- multiprocessing
193User Customization and Extensibility
[b8d3f6b]196As thirty-two bit microprocessors have decreased in cost, they have become
197increasingly common in a variety of embedded systems.  A wide range of custom
198and general-purpose processor boards are based on various thirty-two bit
199processors.  RTEMS was designed to make no assumptions concerning the
200characteristics of individual microprocessor families or of specific support
201hardware.  In addition, RTEMS allows the system developer a high degree of
202freedom in customizing and extending its features.
204RTEMS assumes the existence of a supported microprocessor and sufficient memory
205for both RTEMS and the real-time application.  Board dependent components such
206as clocks, interrupt controllers, or I/O devices can be easily integrated with
207RTEMS.  The customization and extensibility features allow RTEMS to efficiently
208support as many environments as possible.
[b8d3f6b]213The issue of portability was the major factor in the creation of RTEMS.  Since
214RTEMS is designed to isolate the hardware dependencies in the specific board
215support packages, the real-time application should be easily ported to any
216other processor.  The use of RTEMS allows the development of real-time
217applications which can be completely independent of a particular microprocessor
220Memory Requirements
[b8d3f6b]223Since memory is a critical resource in many real-time embedded systems, RTEMS
224was specifically designed to automatically leave out all services that are not
225required from the run-time environment.  Features such as networking, various
226fileystems, and many other features are completely optional.  This allows the
227application designer the flexibility to tailor RTEMS to most efficiently meet
228system requirements while still satisfying even the most stringent memory
229constraints.  As a result, the size of the RTEMS executive is application
[b8d3f6b]232RTEMS requires RAM to manage each instance of an RTEMS object that is created.
233Thus the more RTEMS objects an application needs, the more memory that must be
[9aafb39]234reserved.  See :ref:`Configuring a System`.
[b8d3f6b]236RTEMS utilizes memory for both code and data space.  Although RTEMS' data space
237must be in RAM, its code space can be located in either ROM or RAM.
[b8d3f6b]242This manual was written for experienced real-time software developers.
243Although some background is provided, it is assumed that the reader is familiar
244with the concepts of task management as well as intertask communication and
245synchronization.  Since directives, user related data structures, and examples
246are presented in C, a basic understanding of the C programming language is
247required to fully understand the material presented.  However, because of the
248similarity of the Ada and C RTEMS implementations, users will find that the use
249and behavior of the two implementations is very similar.  A working knowledge
250of the target processor is helpful in understanding some of RTEMS' features.  A
251thorough understanding of the executive cannot be obtained without studying the
252entire manual because many of RTEMS' concepts and features are interrelated.
253Experienced RTEMS users will find that the manual organization facilitates its
254use as a reference document.
259The following conventions are used in this manual:
[b8d3f6b]261- Significant words or phrases as well as all directive names are printed in
262  bold type.
[b8d3f6b]264- Items in bold capital letters are constants defined by RTEMS.  Each language
265  interface provided by RTEMS includes a file containing the standard set of
266  constants, data types, and structure definitions which can be incorporated
267  into the user application.
[b8d3f6b]269- A number of type definitions are provided by RTEMS and can be found in
270  rtems.h.
[b8d3f6b]272- The characters "0x" preceding a number indicates that the number is in
273  hexadecimal format.  Any other numbers are assumed to be in decimal format.
275Manual Organization
[b8d3f6b]278This first chapter has presented the introductory and background material for
279the RTEMS executive.  The remaining chapters of this manual present a detailed
280description of RTEMS and the environment, including run time behavior, it
281creates for the user.
[b8d3f6b]283A chapter is dedicated to each manager and provides a detailed discussion of
284each RTEMS manager and the directives which it provides.  The presentation
285format for each directive includes the following sections:
287- Calling sequence
289- Directive status codes
291- Description
293- Notes
[b8d3f6b]295The following provides an overview of the remainder of this manual:
297Chapter 2:
[b8d3f6b]298    Key Concepts: presents an introduction to the ideas which are common across
299    multiple RTEMS managers.
301Chapter 3:
[b8d3f6b]302    RTEMS Data Types: describes the fundamental data types shared by the
303    services in the RTEMS Classic API.
305Chapter 4:
[b8d3f6b]306    Scheduling Concepts: details the various RTEMS scheduling algorithms and
307    task state transitions.
309Chapter 5:
[b8d3f6b]310    Initialization Manager: describes the functionality and directives provided
311    by the Initialization Manager.
313Chapter 6:
[b8d3f6b]314    Task Manager: describes the functionality and directives provided by the
315    Task Manager.
317Chapter 7:
[b8d3f6b]318    Interrupt Manager: describes the functionality and directives provided by
319    the Interrupt Manager.
321Chapter 8:
[b8d3f6b]322    Clock Manager: describes the functionality and directives provided by the
323    Clock Manager.
325Chapter 9:
[b8d3f6b]326    Timer Manager: describes the functionality and directives provided by the
327    Timer Manager.
329Chapter 10:
[b8d3f6b]330    Rate Monotonic Manager: describes the functionality and directives provided
331    by the Rate Monotonic Manager.
333Chapter 11:
[b8d3f6b]334    Semaphore Manager: describes the functionality and directives provided by
335    the Semaphore Manager.
337Chapter 12:
[b8d3f6b]338    Barrier Manager: describes the functionality and directives provided by the
339    Barrier Manager.
341Chapter 13:
[b8d3f6b]342    Message Manager: describes the functionality and directives provided by the
343    Message Manager.
345Chapter 14:
[b8d3f6b]346    Event Manager: describes the functionality and directives provided by the
347    Event Manager.
349Chapter 15:
[b8d3f6b]350    Signal Manager: describes the functionality and directives provided by the
351    Signal Manager.
353Chapter 16:
[b8d3f6b]354    Partition Manager: describes the functionality and directives provided by
355    the Partition Manager.
357Chapter 17:
[b8d3f6b]358    Region Manager: describes the functionality and directives provided by the
359    Region Manager.
361Chapter 18:
[b8d3f6b]362    Dual-Ported Memory Manager: describes the functionality and directives
363    provided by the Dual-Ported Memory Manager.
365Chapter 19:
[b8d3f6b]366    I/O Manager: describes the functionality and directives provided by the I/O
367    Manager.
369Chapter 20:
[b8d3f6b]370    Fatal Error Manager: describes the functionality and directives provided by
371    the Fatal Error Manager.
373Chapter 21:
[b8d3f6b]374    Board Support Packages: defines the functionality required of user-supplied
375    board support packages.
377Chapter 22:
[b8d3f6b]378    User Extensions: shows the user how to extend RTEMS to incorporate custom
379    features.
381Chapter 23:
[b8d3f6b]382    Configuring a System: details the process by which one tailors RTEMS for a
383    particular single-processor or multiprocessor application.
385Chapter 24:
[b8d3f6b]386    Multiprocessing Manager: presents a conceptual overview of the
387    multiprocessing capabilities provided by RTEMS as well as describing the
388    Multiprocessing Communications Interface Layer and Multiprocessing Manager
[fd6dc8c]389    directives.
391Chapter 25:
[b8d3f6b]392    Stack Bounds Checker: presents the capabilities of the RTEMS task stack
393    checker which can report stack usage as well as detect bounds violations.
395Chapter 26:
[b8d3f6b]396    CPU Usage Statistics: presents the capabilities of the CPU Usage statistics
397    gathered on a per task basis along with the mechanisms for reporting and
398    resetting the statistics.
400Chapter 27:
[b8d3f6b]401    Object Services: presents a collection of helper services useful when
402    manipulating RTEMS objects. These include methods to assist in obtaining an
403    object's name in printable form. Additional services are provided to
404    decompose an object Id and determine which API and object class it belongs
405    to.
407Chapter 28:
[b8d3f6b]408    Chains: presents the methods provided to build, iterate and manipulate
409    doubly-linked chains. This manager makes the chain implementation used
410    internally by RTEMS to user space applications.
412Chapter 29:
[b8d3f6b]413    Timespec Helpers: presents a set of helper services useful when
414    manipulating POSIX ``struct timespec`` instances.
416Chapter 30:
417    Constant Bandwidth Server Scheduler API.
419Chapter 31:
[b8d3f6b]420    Directive Status Codes: provides a definition of each of the directive
421    status codes referenced in this manual.
423Chapter 32:
424    Example Application: provides a template for simple RTEMS applications.
426Chapter 33:
427    Glossary: defines terms used throughout this manual.
Note: See TracBrowser for help on using the repository browser.