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