[b8d3f6b] | 1 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
| 2 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
| 3 | .. COMMENT: All rights reserved. |
---|
| 4 | |
---|
[fd6dc8c8] | 5 | Overview |
---|
| 6 | ######## |
---|
| 7 | |
---|
| 8 | Introduction |
---|
| 9 | ============ |
---|
| 10 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 38 | |
---|
| 39 | Real-time Application Systems |
---|
| 40 | ============================= |
---|
| 41 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 73 | |
---|
| 74 | Real-time Executive |
---|
| 75 | =================== |
---|
| 76 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 113 | |
---|
| 114 | RTEMS Application Architecture |
---|
| 115 | ============================== |
---|
| 116 | |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 121 | localized to the low level device drivers. |
---|
| 122 | |
---|
[b8d3f6b] | 123 | .. figure:: rtemsarc.png |
---|
| 124 | :width: 488 |
---|
| 125 | :height: 100px |
---|
| 126 | :align: center |
---|
| 127 | :alt: RTEMS Application Architecture |
---|
[fd6dc8c8] | 128 | |
---|
| 129 | The RTEMS I/O interface manager provides an efficient tool for incorporating |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 134 | real-time projects. |
---|
| 135 | |
---|
| 136 | RTEMS Internal Architecture |
---|
| 137 | =========================== |
---|
| 138 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 207 | |
---|
| 208 | Portability |
---|
| 209 | =========== |
---|
| 210 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 217 | |
---|
| 218 | Memory Requirements |
---|
| 219 | =================== |
---|
| 220 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 229 | |
---|
[b8d3f6b] | 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_. |
---|
[fd6dc8c8] | 233 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 236 | |
---|
| 237 | Audience |
---|
| 238 | ======== |
---|
| 239 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 253 | |
---|
| 254 | Conventions |
---|
| 255 | =========== |
---|
| 256 | |
---|
| 257 | The following conventions are used in this manual: |
---|
| 258 | |
---|
[b8d3f6b] | 259 | - Significant words or phrases as well as all directive names are printed in |
---|
| 260 | bold type. |
---|
[fd6dc8c8] | 261 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 266 | |
---|
[b8d3f6b] | 267 | - A number of type definitions are provided by RTEMS and can be found in |
---|
| 268 | rtems.h. |
---|
[fd6dc8c8] | 269 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 272 | |
---|
| 273 | Manual Organization |
---|
| 274 | =================== |
---|
| 275 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 280 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 284 | |
---|
| 285 | - Calling sequence |
---|
| 286 | |
---|
| 287 | - Directive status codes |
---|
| 288 | |
---|
| 289 | - Description |
---|
| 290 | |
---|
| 291 | - Notes |
---|
| 292 | |
---|
[b8d3f6b] | 293 | The following provides an overview of the remainder of this manual: |
---|
[fd6dc8c8] | 294 | |
---|
| 295 | Chapter 2: |
---|
[b8d3f6b] | 296 | Key Concepts: presents an introduction to the ideas which are common across |
---|
| 297 | multiple RTEMS managers. |
---|
[fd6dc8c8] | 298 | |
---|
| 299 | Chapter 3: |
---|
[b8d3f6b] | 300 | RTEMS Data Types: describes the fundamental data types shared by the |
---|
| 301 | services in the RTEMS Classic API. |
---|
[fd6dc8c8] | 302 | |
---|
| 303 | Chapter 4: |
---|
[b8d3f6b] | 304 | Scheduling Concepts: details the various RTEMS scheduling algorithms and |
---|
| 305 | task state transitions. |
---|
[fd6dc8c8] | 306 | |
---|
| 307 | Chapter 5: |
---|
[b8d3f6b] | 308 | Initialization Manager: describes the functionality and directives provided |
---|
| 309 | by the Initialization Manager. |
---|
[fd6dc8c8] | 310 | |
---|
| 311 | Chapter 6: |
---|
[b8d3f6b] | 312 | Task Manager: describes the functionality and directives provided by the |
---|
| 313 | Task Manager. |
---|
[fd6dc8c8] | 314 | |
---|
| 315 | Chapter 7: |
---|
[b8d3f6b] | 316 | Interrupt Manager: describes the functionality and directives provided by |
---|
| 317 | the Interrupt Manager. |
---|
[fd6dc8c8] | 318 | |
---|
| 319 | Chapter 8: |
---|
[b8d3f6b] | 320 | Clock Manager: describes the functionality and directives provided by the |
---|
| 321 | Clock Manager. |
---|
[fd6dc8c8] | 322 | |
---|
| 323 | Chapter 9: |
---|
[b8d3f6b] | 324 | Timer Manager: describes the functionality and directives provided by the |
---|
| 325 | Timer Manager. |
---|
[fd6dc8c8] | 326 | |
---|
| 327 | Chapter 10: |
---|
[b8d3f6b] | 328 | Rate Monotonic Manager: describes the functionality and directives provided |
---|
| 329 | by the Rate Monotonic Manager. |
---|
[fd6dc8c8] | 330 | |
---|
| 331 | Chapter 11: |
---|
[b8d3f6b] | 332 | Semaphore Manager: describes the functionality and directives provided by |
---|
| 333 | the Semaphore Manager. |
---|
[fd6dc8c8] | 334 | |
---|
| 335 | Chapter 12: |
---|
[b8d3f6b] | 336 | Barrier Manager: describes the functionality and directives provided by the |
---|
| 337 | Barrier Manager. |
---|
[fd6dc8c8] | 338 | |
---|
| 339 | Chapter 13: |
---|
[b8d3f6b] | 340 | Message Manager: describes the functionality and directives provided by the |
---|
| 341 | Message Manager. |
---|
[fd6dc8c8] | 342 | |
---|
| 343 | Chapter 14: |
---|
[b8d3f6b] | 344 | Event Manager: describes the functionality and directives provided by the |
---|
| 345 | Event Manager. |
---|
[fd6dc8c8] | 346 | |
---|
| 347 | Chapter 15: |
---|
[b8d3f6b] | 348 | Signal Manager: describes the functionality and directives provided by the |
---|
| 349 | Signal Manager. |
---|
[fd6dc8c8] | 350 | |
---|
| 351 | Chapter 16: |
---|
[b8d3f6b] | 352 | Partition Manager: describes the functionality and directives provided by |
---|
| 353 | the Partition Manager. |
---|
[fd6dc8c8] | 354 | |
---|
| 355 | Chapter 17: |
---|
[b8d3f6b] | 356 | Region Manager: describes the functionality and directives provided by the |
---|
| 357 | Region Manager. |
---|
[fd6dc8c8] | 358 | |
---|
| 359 | Chapter 18: |
---|
[b8d3f6b] | 360 | Dual-Ported Memory Manager: describes the functionality and directives |
---|
| 361 | provided by the Dual-Ported Memory Manager. |
---|
[fd6dc8c8] | 362 | |
---|
| 363 | Chapter 19: |
---|
[b8d3f6b] | 364 | I/O Manager: describes the functionality and directives provided by the I/O |
---|
| 365 | Manager. |
---|
[fd6dc8c8] | 366 | |
---|
| 367 | Chapter 20: |
---|
[b8d3f6b] | 368 | Fatal Error Manager: describes the functionality and directives provided by |
---|
| 369 | the Fatal Error Manager. |
---|
[fd6dc8c8] | 370 | |
---|
| 371 | Chapter 21: |
---|
[b8d3f6b] | 372 | Board Support Packages: defines the functionality required of user-supplied |
---|
| 373 | board support packages. |
---|
[fd6dc8c8] | 374 | |
---|
| 375 | Chapter 22: |
---|
[b8d3f6b] | 376 | User Extensions: shows the user how to extend RTEMS to incorporate custom |
---|
| 377 | features. |
---|
[fd6dc8c8] | 378 | |
---|
| 379 | Chapter 23: |
---|
[b8d3f6b] | 380 | Configuring a System: details the process by which one tailors RTEMS for a |
---|
| 381 | particular single-processor or multiprocessor application. |
---|
[fd6dc8c8] | 382 | |
---|
| 383 | Chapter 24: |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 387 | directives. |
---|
| 388 | |
---|
| 389 | Chapter 25: |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 392 | |
---|
| 393 | Chapter 26: |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 397 | |
---|
| 398 | Chapter 27: |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 404 | |
---|
| 405 | Chapter 28: |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 409 | |
---|
| 410 | Chapter 29: |
---|
[b8d3f6b] | 411 | Timespec Helpers: presents a set of helper services useful when |
---|
| 412 | manipulating POSIX ``struct timespec`` instances. |
---|
[fd6dc8c8] | 413 | |
---|
| 414 | Chapter 30: |
---|
| 415 | Constant Bandwidth Server Scheduler API. |
---|
| 416 | |
---|
| 417 | Chapter 31: |
---|
[b8d3f6b] | 418 | Directive Status Codes: provides a definition of each of the directive |
---|
| 419 | status codes referenced in this manual. |
---|
[fd6dc8c8] | 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. |
---|