From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- c-user/overview.rst | 427 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 427 insertions(+) create mode 100644 c-user/overview.rst (limited to 'c-user/overview.rst') diff --git a/c-user/overview.rst b/c-user/overview.rst new file mode 100644 index 0000000..273e5ed --- /dev/null +++ b/c-user/overview.rst @@ -0,0 +1,427 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Overview +######## + +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: + +- multitasking capabilities + +- homogeneous and heterogeneous multiprocessor systems + +- event-driven, priority-based, preemptive scheduling + +- optional rate monotonic scheduling + +- intertask communication and synchronization + +- priority inheritance + +- responsive interrupt management + +- dynamic memory allocation + +- high level of user configurability + +This manual describes the usage of RTEMS for applications written in the C +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. + +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. + +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. + +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. + +.. figure:: ../images/c_user/rtemsarc.png + :width: 488 + :height: 100px + :align: center + :alt: RTEMS Application Architecture + +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. + +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: + +.. figure:: ../images/c_user/rtemspie.png + :width: 70% + :align: center + :alt: RTEMS Internal Architecture + +Subsequent chapters present a detailed description of the capabilities provided +by each of the following RTEMS managers: + +- initialization + +- task + +- interrupt + +- clock + +- timer + +- semaphore + +- message + +- event + +- signal + +- partition + +- region + +- dual ported memory + +- I/O + +- fatal error + +- rate monotonic + +- user extensions + +- multiprocessing + +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. + +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. + +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`. + +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. + +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 C, a basic understanding of the C 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. + +Conventions +=========== + +The following conventions are used in this manual: + +- Significant words or phrases as well as all directive names are printed in + bold type. + +- 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 structure definitions which can be incorporated + into the user application. + +- A number of type definitions are provided by RTEMS and can be found in + rtems.h. + +- The characters "0x" preceding a number indicates that the number is in + hexadecimal format. Any other numbers are assumed to be in decimal format. + +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: + +- Calling sequence + +- Directive status codes + +- Description + +- Notes + +The following provides an overview of the remainder of this manual: + +Chapter 2: + Key Concepts: presents an introduction to the ideas which are common across + multiple RTEMS managers. + +Chapter 3: + RTEMS Data Types: describes the fundamental data types shared by the + services in the RTEMS Classic API. + +Chapter 4: + Scheduling Concepts: details the various RTEMS scheduling algorithms and + task state transitions. + +Chapter 5: + Initialization Manager: describes the functionality and directives provided + by the Initialization Manager. + +Chapter 6: + Task Manager: describes the functionality and directives provided by the + Task Manager. + +Chapter 7: + Interrupt Manager: describes the functionality and directives provided by + the Interrupt Manager. + +Chapter 8: + Clock Manager: describes the functionality and directives provided by the + Clock Manager. + +Chapter 9: + Timer Manager: describes the functionality and directives provided by the + Timer Manager. + +Chapter 10: + Rate Monotonic Manager: describes the functionality and directives provided + by the Rate Monotonic Manager. + +Chapter 11: + Semaphore Manager: describes the functionality and directives provided by + the Semaphore Manager. + +Chapter 12: + Barrier Manager: describes the functionality and directives provided by the + Barrier Manager. + +Chapter 13: + Message Manager: describes the functionality and directives provided by the + Message Manager. + +Chapter 14: + Event Manager: describes the functionality and directives provided by the + Event Manager. + +Chapter 15: + Signal Manager: describes the functionality and directives provided by the + Signal Manager. + +Chapter 16: + Partition Manager: describes the functionality and directives provided by + the Partition Manager. + +Chapter 17: + Region Manager: describes the functionality and directives provided by the + Region Manager. + +Chapter 18: + Dual-Ported Memory Manager: describes the functionality and directives + provided by the Dual-Ported Memory Manager. + +Chapter 19: + I/O Manager: describes the functionality and directives provided by the I/O + Manager. + +Chapter 20: + Fatal Error Manager: describes the functionality and directives provided by + the Fatal Error Manager. + +Chapter 21: + Board Support Packages: defines the functionality required of user-supplied + board support packages. + +Chapter 22: + User Extensions: shows the user how to extend RTEMS to incorporate custom + features. + +Chapter 23: + Configuring a System: details the process by which one tailors RTEMS for a + particular single-processor or multiprocessor application. + +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. + +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. + +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. + +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. + +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. + +Chapter 29: + Timespec Helpers: presents a set of helper services useful when + manipulating POSIX ``struct timespec`` instances. + +Chapter 30: + Constant Bandwidth Server Scheduler API. + +Chapter 31: + Directive Status Codes: provides a definition of each of the directive + status codes referenced in this manual. + +Chapter 32: + Example Application: provides a template for simple RTEMS applications. + +Chapter 33: + Glossary: defines terms used throughout this manual. -- cgit v1.2.3