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