source: rtems-docs/c_user/overview.rst @ 25d55d4

4.115am
Last change on this file since 25d55d4 was 25d55d4, checked in by Chris Johns <chrisj@…>, on 02/18/16 at 04:41:28

Change code to code-block.

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