From 48a7fa31f918a6fc88719b3c9393a9ba2829f42a Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 15 Nov 2016 10:37:59 -0600 Subject: Remove texinfo format documentation. Replaced by Sphinx formatted documentation. closes #2812. --- doc/user/overview.t | 549 ---------------------------------------------------- 1 file changed, 549 deletions(-) delete mode 100644 doc/user/overview.t (limited to 'doc/user/overview.t') diff --git a/doc/user/overview.t b/doc/user/overview.t deleted file mode 100644 index 77770cd8ee..0000000000 --- a/doc/user/overview.t +++ /dev/null @@ -1,549 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2008. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@c -@c This chapter is missing the following figures: -@c -@c Figure 1-1 RTEMS Application Architecture -@c Figure 1-2 RTEMS Internal Architecture -@c - -@chapter Overview - -@section 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: - -@itemize @bullet -@item multitasking capabilities -@item homogeneous and heterogeneous multiprocessor systems -@item event-driven, priority-based, preemptive scheduling -@item optional rate monotonic scheduling -@item intertask communication and synchronization -@item priority inheritance -@item responsive interrupt management -@item dynamic memory allocation -@item high level of user configurability -@end itemize - -This manual describes the usage of RTEMS for -applications written in the @value{LANGUAGE} 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. - -@section 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. - -@section 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. - -@section 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. - -@float Figure,fig:RTEMS-App-Arch -@caption{RTEMS Application Architecture} - -@ifset use-ascii -@example -@group - +-----------------------------------------------------------+ - | Application Dependent Software | - | +----------------------------------------+ | - | | Standard Application Components | | - | | +-------------+---+ | - | +---+-----------+ | | | - | | Board Support | | RTEMS | | - | | Package | | | | - +----+---------------+--------------+-----------------+-----| - | Target Hardware | - +-----------------------------------------------------------+ -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 -@tex -\centerline{\vbox{\offinterlineskip\halign{ -\vrule#& -\hbox to 0.50in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.50in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.75in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.75in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.75in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.75in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.50in{\enskip\hfil#\hfil}& -\vrule#& -\hbox to 0.50in{\enskip\hfil#\hfil}& -\vrule#\cr -\multispan{17}\hrulefill\cr -% to force all columns to desired width -& \enskip && \enskip && \enskip && \enskip && - \enskip && \enskip &&\enskip &&\enskip &\cr -% For debugging columns -%& \enskip 0&& \enskip 1&& \enskip 2&& \enskip 3&& -% \enskip 4&& \enskip 5&&\enskip 6&&\enskip 7&\cr -\strut&\multispan{15}&\cr -&\multispan{15}\hfil Application Dependent Software\hfil&\cr -\strut&\multispan{15}&\cr -&\multispan{2}&&\multispan{8}\hrulefill &\multispan{2}&\cr -\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr -&\multispan{2}&&&\multispan{7}\hfil Standard Application Components\hfil& - &\multispan{2}&&\cr -\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr -&&\multispan{5}\hrulefill&&\multispan{7}\hrulefill&&\cr -\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr -&&&\multispan{3}\hfil Device\hfil&&&&\multispan{5}\hfil RTEMS\hfil&&&\cr -&&&\multispan{3}\hfil Drivers\hfil&&&&\multispan{5}&&&\cr -\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr -\multispan{17}\hrulefill\cr -\strut&\multispan{15}&\cr -&\multispan{15}\hfil Target Hardware\hfil&\cr -\strut&\multispan{15}&\cr -\multispan{17}\hrulefill\cr -}}\hfil} -@end tex -@end ifset - -@ifset use-html -@html -RTEMS Application Architecture -@end html -@end ifset -@end float - -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. - -@section 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: - -@float Figure,fig:rtems-layers -@caption{RTEMS Layered Architecture} - -@ifset use-ascii -@example -@group - +-----------------------------------------------+ - | RTEMS Executive Interface | - +-----------------------------------------------+ - | RTEMS Core | - +-----------------------------------------------+ - | CPU Dependent Code | - +-----------------------------------------------+ -@end group -@end example -@end ifset - -@ifset use-tex -@center{@image{rtemspie,4in,3in, RTEMS Layered Architecture}} -@tex -@end tex -@end ifset - -@ifset use-html -@html -RTEMS Layered Architecture -@end html -@end ifset -@end float - -Subsequent chapters present a detailed description of the capabilities -provided by each of the following RTEMS managers: - -@itemize @bullet -@item initialization -@item task -@item interrupt -@item clock -@item timer -@item semaphore -@item message -@item event -@item signal -@item partition -@item region -@item dual ported memory -@item I/O -@item fatal error -@item rate monotonic -@item user extensions -@item multiprocessing -@end itemize - -@section 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. - -@section 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. - -@section 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} for more details. - -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. - -@section 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 @value{LANGUAGE}, a basic -understanding of the @value{LANGUAGE} 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. - -@section Conventions - -The following conventions are used in this manual: - -@itemize @bullet -@item Significant words or phrases as well as all directive -names are printed in bold type. - -@item 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 -@value{STRUCTURE} definitions which can be incorporated into the user -application. - -@item A number of type definitions are provided by RTEMS and -can be found in rtems.h. - -@item The characters "0x" preceding a number indicates that -the number is in hexadecimal format. Any other numbers are -assumed to be in decimal format. -@end itemize - -@section 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: - -@itemize @bullet -@item Calling sequence -@item Directive status codes -@item Description -@item Notes -@end itemize - -The following provides an overview of the remainder -of this manual: - -@table @asis -@item Chapter 2: -Key Concepts: presents an introduction to the ideas which are common -across multiple RTEMS managers. - -@item Chapter 3: -RTEMS Data Types: describes the fundamental data types shared -by the services in the RTEMS Classic API. - -@item Chapter 4: -Scheduling Concepts: details the various RTEMS scheduling algorithms -and task state transitions. - -@item Chapter 5: -Initialization Manager: describes the functionality and directives -provided by the Initialization Manager. - -@item Chapter 6: -Task Manager: describes the functionality and directives provided -by the Task Manager. - -@item Chapter 7: -Interrupt Manager: describes the functionality and directives -provided by the Interrupt Manager. - -@item Chapter 8: -Clock Manager: describes the functionality and directives -provided by the Clock Manager. - -@item Chapter 9: -Timer Manager: describes the functionality and directives provided -by the Timer Manager. - -@item Chapter 10: -Rate Monotonic Manager: describes the functionality and directives -provided by the Rate Monotonic Manager. - -@item Chapter 11: -Semaphore Manager: describes the functionality and directives -provided by the Semaphore Manager. - -@item Chapter 12: -Barrier Manager: describes the functionality and directives -provided by the Barrier Manager. - -@item Chapter 13: -Message Manager: describes the functionality and directives -provided by the Message Manager. - -@item Chapter 14: -Event Manager: describes the -functionality and directives provided by the Event Manager. - -@item Chapter 15: -Signal Manager: describes the -functionality and directives provided by the Signal Manager. - -@item Chapter 16: -Partition Manager: describes the -functionality and directives provided by the Partition Manager. - -@item Chapter 17: -Region Manager: describes the -functionality and directives provided by the Region Manager. - -@item Chapter 18: -Dual-Ported Memory Manager: describes -the functionality and directives provided by the Dual-Ported -Memory Manager. - -@item Chapter 19: -I/O Manager: describes the -functionality and directives provided by the I/O Manager. - -@item Chapter 20: -Fatal Error Manager: describes the functionality and directives -provided by the Fatal Error Manager. - -@item Chapter 21: -Board Support Packages: defines the -functionality required of user-supplied board support packages. - -@item Chapter 22: -User Extensions: shows the user how to -extend RTEMS to incorporate custom features. - -@item Chapter 23: -Configuring a System: details the process by which one tailors RTEMS -for a particular single-processor or multiprocessor application. - -@item 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. - -@item 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. - -@item 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. - -@item 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. - -@item 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. - -@item Chapter 29: -Timespec Helpers: presents a set of helper services useful -when manipulating POSIX @code{struct timespec} instances. - -@item Chapter 30: -Constant Bandwidth Server Scheduler API:: - -@item Chapter 31: -Directive Status Codes: provides a definition of each of the -directive status codes referenced in this manual. - -@item Chapter 32: -Example Application: provides a template for simple RTEMS applications. - -@item Chapter 33: -Glossary: defines terms used throughout this manual. - -@end table - - -- cgit v1.2.3