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