summaryrefslogtreecommitdiffstats
path: root/doc/user/overview.t
blob: 77770cd8ee34308f9db3a73e574edf689d5a5925 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
@c
@c  COPYRIGHT (c) 1988-2008.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.

@c
@c  This chapter is missing the following figures:
@c
@c     Figure 1-1  RTEMS Application Architecture
@c     Figure 1-2  RTEMS Internal Architecture
@c

@chapter Overview

@section 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:

@itemize @bullet
@item multitasking capabilities
@item homogeneous and heterogeneous multiprocessor systems
@item event-driven, priority-based, preemptive scheduling
@item optional rate monotonic scheduling
@item intertask communication and synchronization
@item priority inheritance
@item responsive interrupt management
@item dynamic memory allocation
@item high level of user configurability
@end itemize

This manual describes the usage of RTEMS for
applications written in the @value{LANGUAGE} 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.

@section 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.

@section 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.

@section 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.

@float Figure,fig:RTEMS-App-Arch
@caption{RTEMS Application Architecture}

@ifset use-ascii
@example
@group
      +-----------------------------------------------------------+
      |             Application Dependent Software                |
      |        +----------------------------------------+         |
      |        |    Standard Application Components     |         |
      |        |                          +-------------+---+     |
      |    +---+-----------+              |                 |     |
      |    | Board Support |              |      RTEMS      |     |
      |    |    Package    |              |                 |     |
      +----+---------------+--------------+-----------------+-----|
      |                      Target Hardware                      |
      +-----------------------------------------------------------+
@end group
@end example
@end ifset

@ifset use-tex
@sp 1
@tex
\centerline{\vbox{\offinterlineskip\halign{
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.75in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.75in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.75in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.75in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}&
\vrule#\cr
\multispan{17}\hrulefill\cr
% to force all columns to desired width
& \enskip && \enskip && \enskip && \enskip &&
    \enskip && \enskip &&\enskip &&\enskip &\cr
% For debugging columns
%& \enskip 0&& \enskip 1&& \enskip 2&& \enskip 3&&
%    \enskip 4&& \enskip 5&&\enskip 6&&\enskip 7&\cr
\strut&\multispan{15}&\cr
&\multispan{15}\hfil Application Dependent Software\hfil&\cr
\strut&\multispan{15}&\cr
&\multispan{2}&&\multispan{8}\hrulefill &\multispan{2}&\cr
\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr
&\multispan{2}&&&\multispan{7}\hfil Standard Application Components\hfil&
    &\multispan{2}&&\cr
\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr
&&\multispan{5}\hrulefill&&\multispan{7}\hrulefill&&\cr
\strut&&&\multispan{3}                  &&&&\multispan{5}&&&\cr
&&&\multispan{3}\hfil Device\hfil&&&&\multispan{5}\hfil RTEMS\hfil&&&\cr
&&&\multispan{3}\hfil Drivers\hfil&&&&\multispan{5}&&&\cr
\strut&&&\multispan{3}                  &&&&\multispan{5}&&&\cr
\multispan{17}\hrulefill\cr
\strut&\multispan{15}&\cr
&\multispan{15}\hfil Target Hardware\hfil&\cr
\strut&\multispan{15}&\cr
\multispan{17}\hrulefill\cr
}}\hfil}
@end tex
@end ifset

@ifset use-html
@html
<IMG SRC="rtemsarc.png" WIDTH=500 HEIGHT=300 ALT="RTEMS Application Architecture">
@end html
@end ifset
@end float

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.

@section 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:

@float Figure,fig:rtems-layers
@caption{RTEMS Layered Architecture}

@ifset use-ascii
@example
@group
           +-----------------------------------------------+
           |          RTEMS Executive Interface            |
           +-----------------------------------------------+
           |                 RTEMS Core                    |
           +-----------------------------------------------+
           |              CPU Dependent Code               |
           +-----------------------------------------------+
@end group
@end example
@end ifset

@ifset use-tex
@center{@image{rtemspie,4in,3in, RTEMS Layered Architecture}}
@tex
@end tex
@end ifset

@ifset use-html
@html
<IMG SRC="rtemspie.png" WIDTH=500 HEIGHT=300 ALT="RTEMS Layered Architecture">
@end html
@end ifset
@end float

Subsequent chapters present a detailed description of the capabilities
provided by each of the following RTEMS managers:

@itemize @bullet
@item initialization
@item task
@item interrupt
@item clock
@item timer
@item semaphore
@item message
@item event
@item signal
@item partition
@item region
@item dual ported memory
@item I/O
@item fatal error
@item rate monotonic
@item user extensions
@item multiprocessing
@end itemize

@section 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.

@section 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.

@section 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} for more details.

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.

@section 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 @value{LANGUAGE}, a basic
understanding of the @value{LANGUAGE} 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.

@section Conventions

The following conventions are used in this manual:

@itemize @bullet
@item Significant words or phrases as well as all directive
names are printed in bold type.

@item 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
@value{STRUCTURE} definitions which can be incorporated into the user
application.

@item A number of type definitions are provided by RTEMS and
can be found in rtems.h.

@item The characters "0x" preceding a number indicates that
the number is in hexadecimal format.  Any other numbers are
assumed to be in decimal format.
@end itemize

@section 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:

@itemize @bullet
@item Calling sequence
@item Directive status codes
@item Description
@item Notes
@end itemize

The following provides an overview of the remainder
of this manual:

@table @asis
@item Chapter 2:
Key Concepts: presents an introduction to the ideas which are common
across multiple RTEMS managers.

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

@item Chapter 4:
Scheduling Concepts: details the various RTEMS scheduling algorithms
and task state transitions.

@item Chapter 5:
Initialization Manager: describes the functionality and directives
provided by the Initialization Manager.

@item Chapter 6:
Task Manager: describes the functionality and directives provided
by the Task Manager.

@item Chapter 7:
Interrupt Manager: describes the functionality and directives
provided by the Interrupt Manager.

@item Chapter 8:
Clock Manager: describes the functionality and directives
provided by the Clock Manager.

@item Chapter 9:
Timer Manager: describes the functionality and directives provided
by the Timer Manager.

@item Chapter 10:
Rate Monotonic Manager: describes the functionality and directives
provided by the Rate Monotonic Manager.

@item Chapter 11:
Semaphore Manager: describes the functionality and directives
provided by the Semaphore Manager.

@item Chapter 12:
Barrier Manager: describes the functionality and directives
provided by the Barrier Manager.

@item Chapter 13:
Message Manager: describes the functionality and directives
provided by the Message Manager.

@item Chapter 14:
Event Manager: describes the
functionality and directives provided by the Event Manager.

@item Chapter 15:
Signal Manager: describes the
functionality and directives provided by the Signal Manager.

@item Chapter 16:
Partition Manager: describes the
functionality and directives provided by the Partition Manager.

@item Chapter 17:
Region Manager: describes the
functionality and directives provided by the Region Manager.

@item Chapter 18:
Dual-Ported Memory Manager: describes
the functionality and directives provided by the Dual-Ported
Memory Manager.

@item Chapter 19:
I/O Manager: describes the
functionality and directives provided by the I/O Manager.

@item Chapter 20:
Fatal Error Manager: describes the functionality and directives
provided by the Fatal Error Manager.

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

@item Chapter 22:
User Extensions: shows the user how to
extend RTEMS to incorporate custom features.

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

@item 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.

@item 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.

@item 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.

@item 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.

@item 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.

@item Chapter 29:
Timespec Helpers: presents a set of helper services useful
when manipulating POSIX @code{struct timespec} instances.

@item Chapter 30:
Constant Bandwidth Server Scheduler API::

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

@item Chapter 32:
Example Application: provides a template for simple RTEMS applications.

@item Chapter 33:
Glossary: defines terms used throughout this manual.

@end table