From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/overview.rst | 489 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 489 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..6b4d125 --- /dev/null +++ b/c_user/overview.rst @@ -0,0 +1,489 @@ +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. + +.. code:: c + + +-----------------------------------------------------------+ + | Application Dependent Software | + | +----------------------------------------+ | + | | Standard Application Components | | + | | +-------------+---+ | + | +---+-----------+ | | | + | | Board Support | | RTEMS | | + | | Package | | | | + +----+---------------+--------------+-----------------+-----| + | Target Hardware | + +-----------------------------------------------------------+ + +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: + +.. code:: c + + +-----------------------------------------------+ + | RTEMS Executive Interface | + +-----------------------------------------------+ + | RTEMS Core | + +-----------------------------------------------+ + | CPU Dependent Code | + +-----------------------------------------------+ + +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 `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. + +.. COMMENT: COPYRIGHT (c) 1988-2007. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + +.. COMMENT: The following figure was replaced with an ASCII equivalent. + +.. COMMENT: Figure 2-1 Object ID Composition + -- cgit v1.2.3