source: rtems/cpukit/rtems/mainpage.h @ cc69334f

4.115
Last change on this file since cc69334f was cc69334f, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 6, 2015 at 4:35:40 PM

Fix a number of minor Doxygen formatting issues

  • Property mode set to 100644
File size: 50.1 KB
Line 
1/**
2 * @file rtems/rtems/mainpage.h
3 *
4 * This file exists to provide a top level description of RTEMS for Doxygen.
5 */
6
7/*
8 *  COPYRIGHT (c) 1989-2014.
9 *  On-Line Applications Research Corporation (OAR).
10 *
11 *  The license and distribution terms for this file may be
12 *  found in the file LICENSE in this distribution or at
13 *  http://www.rtems.org/license/LICENSE.
14 */
15
16/**
17 * @mainpage
18 *
19 * The RTEMS real-time operating systems is a layered system with each of the
20 * public APIs implemented in terms of a common foundation layer called the
21 * SuperCore.  This is the Doxygen generated documentation for the RTEMS CPU
22 * Kit including the Classic API, POSIX API and SuperCore.
23 */
24
25/**
26 * @page RTEMSPreface RTEMS History and Introduction
27 *
28 * In recent years, the cost required to develop a software product has
29 * increased significantly while the target hardware costs have decreased. Now
30 * a larger portion of money is expended in developing, using, and maintaining
31 * software. The trend in computing costs is the complete dominance of software
32 * over hardware costs. Because of this, it is necessary that formal
33 * disciplines be established to increase the probability that software is
34 * characterized by a high degree of correctness, maintainability, and
35 * portability. In addition, these disciplines must promote practices that aid
36 * in the consistent and orderly development of a software system within
37 * schedule and budgetary constraints. To be effective, these disciplines must
38 * adopt standards which channel individual software efforts toward a common
39 * goal.
40 *
41 * The push for standards in the software development field has been met with
42 * various degrees of success. The Microprocessor Operating Systems Interfaces
43 * (MOSI) effort has experienced only limited success. As popular as the UNIX
44 * operating system has grown, the attempt to develop a standard interface
45 * definition to allow portable application development has only recently begun
46 * to produce the results needed in this area. Unfortunately, very little
47 * effort has been expended to provide standards addressing the needs of the
48 * real-time community. Several organizations have addressed this need during
49 * recent years.
50 *
51 * The Real Time Executive Interface Definition (RTEID) was developed by
52 * Motorola with technical input from Software Components Group. RTEID was
53 * adopted by the VMEbus International Trade Association (VITA) as a baseline
54 * draft for their proposed standard multiprocessor, real-time executive
55 * interface, Open Real-Time Kernel Interface Definition (ORKID). These two
56 * groups are currently working together with the IEEE P1003.4 committee to
57 * insure that the functionality of their proposed standards is adopted as the
58 * real-time extensions to POSIX.
59 *
60 * This emerging standard defines an interface for the development of real-time
61 * software to ease the writing of real-time application programs that are
62 * directly portable across multiple real-time executive implementations. This
63 * interface includes both the source code interfaces and run-time behavior as
64 * seen by a real-time application. It does not include the details of how a
65 * kernel implements these functions. The standard's goal is to serve as a
66 * complete definition of external interfaces so that application code that
67 * conforms to these interfaces will execute properly in all real-time
68 * executive environments. With the use of a standards compliant executive,
69 * routines that acquire memory blocks, create and manage message queues,
70 * establish and use semaphores, and send and receive signals need not be
71 * redeveloped for a different real-time environment as long as the new
72 * environment is compliant with the standard. Software developers need only
73 * concentrate on the hardware dependencies of the real-time system.
74 * Furthermore, most hardware dependencies for real-time applications can be
75 * localized to the device drivers.
76 *
77 * A compliant executive provides simple and flexible real-time
78 * multiprocessing. It easily lends itself to both tightly-coupled and
79 * loosely-coupled configurations (depending on the system hardware
80 * configuration). Objects such as tasks, queues, events, signals, semaphores,
81 * and memory blocks can be designated as global objects and accessed by any
82 * task regardless of which processor the object and the accessing task reside.
83 *
84 * The acceptance of a standard for real-time executives will produce the same
85 * advantages enjoyed from the push for UNIX standardization by AT&T's System V
86 * Interface Definition and IEEE's POSIX efforts. A compliant multiprocessing
87 * executive will allow close coupling between UNIX systems and real-time
88 * executives to provide the many benefits of the UNIX development environment
89 * to be applied to real-time software development. Together they provide the
90 * necessary laboratory environment to implement real-time, distributed,
91 * embedded systems using a wide variety of computer architectures.
92 *
93 * A study was completed in 1988, within the Research, Development, and
94 * Engineering Center, U.S. Army Missile Command, which compared the various
95 * aspects of the Ada programming language as they related to the application
96 * of Ada code in distributed and/or multiple processing systems. Several
97 * critical conclusions were derived from the study. These conclusions have a
98 * major impact on the way the Army develops application software for embedded
99 * applications. These impacts apply to both in-house software development and
100 * contractor developed software.
101 *
102 * A conclusion of the analysis, which has been previously recognized by other
103 * agencies attempting to utilize Ada in a distributed or multiprocessing
104 * environment, is that the Ada programming language does not adequately
105 * support multiprocessing. Ada does provide a mechanism for multi-tasking,
106 * however, this capability exists only for a single processor system. The
107 * language also does not have inherent capabilities to access global named
108 * variables, flags or program code. These critical features are essential in
109 * order for data to be shared between processors. However, these drawbacks do
110 * have workarounds which are sometimes awkward and defeat the intent of
111 * software maintainability and portability goals.
112 *
113 * Another conclusion drawn from the analysis, was that the run time executives
114 * being delivered with the Ada compilers were too slow and inefficient to be
115 * used in modern missile systems. A run time executive is the core part of the
116 * run time system code, or operating system code, that controls task
117 * scheduling, input/output management and memory management. Traditionally,
118 * whenever efficient executive (also known as kernel) code was required by the
119 * application, the user developed in-house software. This software was usually
120 * written in assembly language for optimization.
121 *
122 * Because of this shortcoming in the Ada programming language, software
123 * developers in research and development and contractors for project managed
124 * systems, are mandated by technology to purchase and utilize off-the-shelf
125 * third party kernel code. The contractor, and eventually the Government, must
126 * pay a licensing fee for every copy of the kernel code used in an embedded
127 * system.
128 *
129 * The main drawback to this development environment is that the Government
130 * does not own, nor has the right to modify code contained within the kernel.
131 * V&V techniques in this situation are more difficult than if the complete
132 * source code were available. Responsibility for system failures due to faulty
133 * software is yet another area to be resolved under this environment.
134 *
135 * The Guidance and Control Directorate began a software development effort to
136 * address these problems. A project to develop an experimental run time kernel
137 * was begun that will eliminate the major drawbacks of the Ada programming
138 * language mentioned above. The Real Time Executive for Multiprocessor Systems
139 * (RTEMS) provides full capabilities for management of tasks, interrupts,
140 * time, and multiple processors in addition to those features typical of
141 * generic operating systems. The code is Government owned, so no licensing
142 * fees are necessary. RTEMS has been implemented in both the Ada and C
143 * programming languages. It has been ported to the following processor
144 * families:
145 *
146 * - Altera NIOS II
147 * - Analog Devices Blackfin
148 * - ARM
149 * - Freescale (formerly Motorola) MC68xxx
150 * - Freescale (formerly Motorola) MC683xx
151 * - Freescale (formerly Motorola) ColdFire
152 * - Intel i386 and above
153 * - Lattice Semiconductor LM32
154 * - MIPS
155 * - PowerPC
156 * - Renesas (formerly Hitachi) SuperH
157 * - Renesas (formerly Hitachi) H8/300
158 * - SPARC
159 * - Texas Instruments C3x/C4x
160 * - UNIX
161 *
162 * Support for other processor families, including RISC, CISC, and DSP, is
163 * planned. Since almost all of RTEMS is written in a high level language,
164 * ports to additional processor families require minimal effort.
165 *
166 * RTEMS multiprocessor support is capable of handling either homogeneous or
167 * heterogeneous systems. The kernel automatically compensates for
168 * architectural differences (byte swapping, etc.) between processors. This
169 * allows a much easier transition from one processor family to another without
170 * a major system redesign.
171 *
172 * Since the proposed standards are still in draft form, RTEMS cannot and does
173 * not claim compliance. However, the status of the standard is being carefully
174 * monitored to guarantee that RTEMS provides the functionality specified in
175 * the standard. Once approved, RTEMS will be made compliant.
176 */
177
178/**
179 * @page RTEMSOverview RTEMS Overview
180 *
181 * @section RTEMSOverviewSecIntroduction Introduction
182 *
183 * RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time
184 * executive (kernel) which provides a high performance environment for
185 * embedded military applications including the following features:
186 *
187 * - multitasking capabilities
188 * - homogeneous and heterogeneous multiprocessor systems
189 * - event-driven, priority-based, preemptive scheduling
190 * - optional rate monotonic scheduling
191 * - intertask communication and synchronization
192 * - priority inheritance
193 * - responsive interrupt management
194 * - dynamic memory allocation
195 * - high level of user configurability
196 *
197 * This manual describes the usage of RTEMS for applications written in the C
198 * programming language. Those implementation details that are processor
199 * dependent are provided in the Applications Supplement documents. A
200 * supplement document which addresses specific architectural issues that
201 * affect RTEMS is provided for each processor type that is supported.
202 *
203 * @section RTEMSOverviewSecRealtimeApplicationSystems Real-time Application Systems
204 *
205 * Real-time application systems are a special class of computer applications.
206 * They have a complex set of characteristics that distinguish them from other
207 * software problems. Generally, they must adhere to more rigorous
208 * requirements. The correctness of the system depends not only on the results
209 * of computations, but also on the time at which the results are produced. The
210 * most important and complex characteristic of real-time application systems
211 * is that they must receive and respond to a set of external stimuli within
212 * rigid and critical time constraints referred to as deadlines. Systems can be
213 * buried by an avalanche of interdependent, asynchronous or cyclical event
214 * streams.
215 *
216 * Deadlines can be further characterized as either hard or soft based upon the
217 * value of the results when produced after the deadline has passed. A deadline
218 * is hard if the results have no value or if their use will result in a
219 * catastrophic event. In contrast, results which are produced after a soft
220 * deadline may have some value.
221 *
222 * Another distinguishing requirement of real-time application systems is the
223 * ability to coordinate or manage a large number of concurrent activities.
224 * Since software is a synchronous entity, this presents special problems. One
225 * instruction follows another in a repeating synchronous cycle. Even though
226 * mechanisms have been developed to allow for the processing of external
227 * asynchronous events, the software design efforts required to process and
228 * manage these events and tasks are growing more complicated.
229 *
230 * The design process is complicated further by spreading this activity over a
231 * set of processors instead of a single processor. The challenges associated
232 * with designing and building real-time application systems become very
233 * complex when multiple processors are involved. New requirements such as
234 * interprocessor communication channels and global resources that must be
235 * shared between competing processors are introduced. The ramifications of
236 * multiple processors complicate each and every characteristic of a real-time
237 * system.
238 *
239 * @section RTEMSOverviewSecRealtimeExecutive Real-time Executive
240 *
241 * Fortunately, real-time operating systems or real-time executives serve as a
242 * cornerstone on which to build the application system. A real-time
243 * multitasking executive allows an application to be cast into a set of
244 * logical, autonomous processes or tasks which become quite manageable. Each
245 * task is internally synchronous, but different tasks execute independently,
246 * resulting in an asynchronous processing stream. Tasks can be dynamically
247 * paused for many reasons resulting in a different task being allowed to
248 * execute for a period of time. The executive also provides an interface to
249 * other system components such as interrupt handlers and device drivers.
250 * System components may request the executive to allocate and coordinate
251 * resources, and to wait for and trigger synchronizing conditions. The
252 * executive system calls effectively extend the CPU instruction set to support
253 * efficient multitasking. By causing tasks to travel through well-defined
254 * state transitions, system calls permit an application to demand-switch
255 * between tasks in response to real-time events.
256 *
257 * By proper grouping of responses to stimuli into separate tasks, a system can
258 * now asynchronously switch between independent streams of execution, directly
259 * responding to external stimuli as they occur. This allows the system design
260 * to meet critical performance specifications which are typically measured by
261 * guaranteed response time and transaction throughput. The multiprocessor
262 * extensions of RTEMS provide the features necessary to manage the extra
263 * requirements introduced by a system distributed across several processors.
264 * It removes the physical barriers of processor boundaries from the world of
265 * the system designer, enabling more critical aspects of the system to receive
266 * the required attention. Such a system, based on an efficient real-time,
267 * multiprocessor executive, is a more realistic model of the outside world or
268 * environment for which it is designed. As a result, the system will always be
269 * more logical, efficient, and reliable.
270 *
271 * By using the directives provided by RTEMS, the real-time applications
272 * developer is freed from the problem of controlling and synchronizing
273 * multiple tasks and processors. In addition, one need not develop, test,
274 * debug, and document routines to manage memory, pass messages, or provide
275 * mutual exclusion. The developer is then able to concentrate solely on the
276 * application. By using standard software components, the time and cost
277 * required to develop sophisticated real-time applications is significantly
278 * reduced.
279 *
280 * @section RTEMSOverviewSecApplicationArchitecture RTEMS Application Architecture
281 *
282 * One important design goal of RTEMS was to provide a bridge between two
283 * critical layers of typical real-time systems. As shown in the following
284 * figure, RTEMS serves as a buffer between the project dependent application
285 * code and the target hardware. Most hardware dependencies for real-time
286 * applications can be localized to the low level device drivers.
287 *
288 * @todo Image RTEMS Application Architecture
289 *
290 * The RTEMS I/O interface manager provides an efficient tool for incorporating
291 * these hardware dependencies into the system while simultaneously providing a
292 * general mechanism to the application code that accesses them. A well
293 * designed real-time system can benefit from this architecture by building a
294 * rich library of standard application components which can be used repeatedly
295 * in other real-time projects.
296 *
297 * @section RTEMSOverviewSecInternalArchitecture RTEMS Internal Architecture
298 *
299 * RTEMS can be viewed as a set of layered components that work in harmony to
300 * provide a set of services to a real-time application system. The executive
301 * interface presented to the application is formed by grouping directives into
302 * logical sets called resource managers. Functions utilized by multiple
303 * managers such as scheduling, dispatching, and object management are provided
304 * in the executive core. The executive core depends on a small set of CPU
305 * dependent routines. Together these components provide a powerful run time
306 * environment that promotes the development of efficient real-time application
307 * systems. The following figure illustrates this organization:
308 *
309 * @todo Image RTEMS Architecture
310 *
311 * Subsequent chapters present a detailed description of the capabilities
312 * provided by each of the following RTEMS managers:
313 *
314 * - initialization
315 * - task
316 * - interrupt
317 * - clock
318 * - timer
319 * - semaphore
320 * - message
321 * - event
322 * - signal
323 * - partition
324 * - region
325 * - dual ported memory
326 * - I/O
327 * - fatal error
328 * - rate monotonic
329 * - user extensions
330 * - multiprocessing
331 *
332 * @section RTEMSOverviewSecUserCustomization User Customization and Extensibility
333 *
334 * As 32-bit microprocessors have decreased in cost, they have become
335 * increasingly common in a variety of embedded systems. A wide range of custom
336 * and general-purpose processor boards are based on various 32-bit
337 * processors. RTEMS was designed to make no assumptions concerning the
338 * characteristics of individual microprocessor families or of specific support
339 * hardware. In addition, RTEMS allows the system developer a high degree of
340 * freedom in customizing and extending its features.
341 *
342 * RTEMS assumes the existence of a supported microprocessor and sufficient
343 * memory for both RTEMS and the real-time application. Board dependent
344 * components such as clocks, interrupt controllers, or I/O devices can be
345 * easily integrated with RTEMS. The customization and extensibility features
346 * allow RTEMS to efficiently support as many environments as possible.
347 *
348 * @section RTEMSOverviewSecPortability Portability
349 *
350 * The issue of portability was the major factor in the creation of RTEMS.
351 * Since RTEMS is designed to isolate the hardware dependencies in the specific
352 * board support packages, the real-time application should be easily ported to
353 * any other processor. The use of RTEMS allows the development of real-time
354 * applications which can be completely independent of a particular
355 * microprocessor architecture.
356 *
357 * @section RTEMSOverviewSecMemoryRequirements Memory Requirements
358 *
359 * Since memory is a critical resource in many real-time embedded systems,
360 * RTEMS was specifically designed to automatically leave out all services that
361 * are not required from the run-time environment. Features such as networking,
362 * various fileystems, and many other features are completely optional. This
363 * allows the application designer the flexibility to tailor RTEMS to most
364 * efficiently meet system requirements while still satisfying even the most
365 * stringent memory constraints. As a result, the size of the RTEMS executive
366 * is application dependent.
367 *
368 * RTEMS requires RAM to manage each instance of an RTEMS object that is
369 * created. Thus the more RTEMS objects an application needs, the more memory
370 * that must be reserved. See Configuring a System Determining Memory
371 * Requirements for more details.
372 *
373 * @todo Link to Configuring a SystemDetermining Memory Requirements
374 *
375 * RTEMS utilizes memory for both code and data space. Although RTEMS' data
376 * space must be in RAM, its code space can be located in either ROM or RAM.
377 *
378 * @section RTEMSOverviewSecAudience Audience
379 *
380 * This manual was written for experienced real-time software developers.
381 * Although some background is provided, it is assumed that the reader is
382 * familiar with the concepts of task management as well as intertask
383 * communication and synchronization. Since directives, user related data
384 * structures, and examples are presented in C, a basic understanding of the C
385 * programming language is required to fully understand the material presented.
386 * However, because of the similarity of the Ada and C RTEMS implementations,
387 * users will find that the use and behavior of the two implementations is very
388 * similar. A working knowledge of the target processor is helpful in
389 * understanding some of RTEMS' features. A thorough understanding of the
390 * executive cannot be obtained without studying the entire manual because many
391 * of RTEMS' concepts and features are interrelated. Experienced RTEMS users
392 * will find that the manual organization facilitates its use as a reference
393 * document.
394 */
395
396/**
397 * @addtogroup ClassicAPI
398 *
399 * The facilities provided by RTEMS are built upon a foundation of very
400 * powerful concepts. These concepts must be understood before the application
401 * developer can efficiently utilize RTEMS. The purpose of this chapter is to
402 * familiarize one with these concepts.
403 *
404 * @section ClassicRTEMSSecObjects Objects
405 *
406 * RTEMS provides directives which can be used to dynamically create, delete,
407 * and manipulate a set of predefined object types. These types include tasks,
408 * message queues, semaphores, memory regions, memory partitions, timers,
409 * ports, and rate monotonic periods. The object-oriented nature of RTEMS
410 * encourages the creation of modular applications built upon re-usable
411 * "building block" routines.
412 *
413 * All objects are created on the local node as required by the application and
414 * have an RTEMS assigned ID. All objects have a user-assigned name. Although a
415 * relationship exists between an object's name and its RTEMS assigned ID, the
416 * name and ID are not identical. Object names are completely arbitrary and
417 * selected by the user as a meaningful "tag" which may commonly reflect the
418 * object's use in the application. Conversely, object IDs are designed to
419 * facilitate efficient object manipulation by the executive.
420 *
421 * @subsection ClassicRTEMSSubSecObjectNames Object Names
422 *
423 * An object name is an unsigned 32-bit entity associated with the
424 * object by the user. The data type @ref rtems_name is used to store object names.
425 *
426 * Although not required by RTEMS, object names are often composed of four
427 * ASCII characters which help identify that object. For example, a task which
428 * causes a light to blink might be called "LITE". The rtems_build_name()
429 * routine is provided to build an object name from four ASCII characters. The
430 * following example illustrates this:
431 *
432 * @code
433 * rtems_name my_name = rtems_build_name('L', 'I', 'T', 'E');
434 * @endcode
435 *
436 * However, it is not required that the application use ASCII characters to
437 * build object names. For example, if an application requires one-hundred
438 * tasks, it would be difficult to assign meaningful ASCII names to each task.
439 * A more convenient approach would be to name them the binary values one
440 * through one-hundred, respectively.
441 *
442 * RTEMS provides a helper routine, rtems_object_get_name(), which can be used to
443 * obtain the name of any RTEMS object using just its ID. This routine attempts
444 * to convert the name into a printable string.
445 *
446 * @subsection ClassicRTEMSSubSecObjectIdentifiers Object Identifiers
447 *
448 * An object ID is a unique unsigned integer value which uniquely identifies an
449 * object instance. Object IDs are passed as arguments to many directives in
450 * RTEMS and RTEMS translates the ID to an internal object pointer. The
451 * efficient manipulation of object IDs is critical to the performance of RTEMS
452 * services. Because of this, there are two object ID formats defined. Each
453 * target architecture specifies which format it will use. There is a 32-bit
454 * format which is used for most of the supported architectures and supports
455 * multiprocessor configurations. There is also a simpler 16-bit format which
456 * is appropriate for smaller target architectures and does not support
457 * multiprocessor configurations.
458 *
459 * @subsubsection ClassicRTEMSSubSec32BitObjectIdentifierFormat 32-Bit Object Identifier Format
460 *
461 * The 32-bit format for an object ID is composed of four parts: API,
462 * object class, node, and index. The data type @ref rtems_id is used to store
463 * object IDs.
464 *
465 * <table>
466 *   <tr>
467 *     <th>Bits</th>
468 *     <td>31</td><td>30</td><td>29</td><td>28</td><td>27</td><td>26</td><td>25</td><td>24</td>
469 *     <td>23</td><td>22</td><td>21</td><td>20</td><td>19</td><td>18</td><td>17</td><td>16</td>
470 *     <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td>
471 *     <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td>
472 *   </tr>
473 *   <tr>
474 *     <th>Contents</th>
475 *     <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Node</td><td colspan=16>Object Index</td>
476 *   </tr>
477 * </table>
478 *
479 * The most significant five bits are the object class. The next three bits
480 * indicate the API to which the object class belongs. The next eight bits
481 * (16 .. 23) are the number of the node on which this object was created. The
482 * node number is always one (1) in a single processor system. The least
483 * significant 16-bits form an identifier within a particular object type.
484 * This identifier, called the object index, ranges in value from one to the
485 * maximum number of objects configured for this object type.
486 *
487 * @subsubsection ClassicRTEMSSubSec16BitObjectIdentifierFormat 16-Bit Object Identifier Format
488 *
489 * The 16-bit format for an object ID is composed of three parts: API, object
490 * class, and index. The data type @ref rtems_id is used to store object IDs.
491 *
492 * <table>
493 *   <tr>
494 *     <th>Bits</th>
495 *     <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td>
496 *     <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td>
497 *   </tr>
498 *   <tr>
499 *     <th>Contents</th>
500 *     <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Object Index</td>
501 *   </tr>
502 * </table>
503 *
504 * The 16-bit format is designed to be as similar as possible to the 32-bit
505 * format. The differences are limited to the eliminatation of the node field
506 * and reduction of the index field from 16-bits to 8-bits.  Thus the 16-bit
507 * format only supports up to 255 object instances per API/Class combination
508 * and single processor systems. As this format is typically utilized by 16-bit
509 * processors with limited address space, this is more than enough object
510 * instances.
511 *
512 * @subsection ClassicRTEMSSubSecObjectIdentiferDescription Object Identifer Description
513 *
514 * The components of an object ID make it possible to quickly locate any object
515 * in even the most complicated multiprocessor system. Object ID's are
516 * associated with an object by RTEMS when the object is created and the
517 * corresponding ID is returned by the appropriate object create directive. The
518 * object ID is required as input to all directives involving objects, except
519 * those which create an object or obtain the ID of an object.
520 *
521 * The object identification directives can be used to dynamically obtain a
522 * particular object's ID given its name. This mapping is accomplished by
523 * searching the name table associated with this object type. If the name is
524 * non-unique, then the ID associated with the first occurrence of the name
525 * will be returned to the application. Since object IDs are returned when the
526 * object is created, the object identification directives are not necessary in
527 * a properly designed single processor application.
528 *
529 * In addition, services are provided to portably examine the subcomponents of
530 * an RTEMS ID. These services are described in detail later in this manual but
531 * are prototyped as follows:
532 *
533 * - rtems_object_id_get_api()
534 * - rtems_object_id_get_class()
535 * - rtems_object_id_get_node()
536 * - rtems_object_id_get_index()
537 *
538 * An object control block is a data structure defined by RTEMS which contains
539 * the information necessary to manage a particular object type. For efficiency
540 * reasons, the format of each object type's control block is different.
541 * However, many of the fields are similar in function. The number of each type
542 * of control block is application dependent and determined by the values
543 * specified in the user's Configuration Table. An object control block is
544 * allocated at object create time and freed when the object is deleted. With
545 * the exception of user extension routines, object control blocks are not
546 * directly manipulated by user applications.
547 *
548 * @section ClassicRTEMSSecComSync Communication and Synchronization
549 *
550 * In real-time multitasking applications, the ability for cooperating
551 * execution threads to communicate and synchronize with each other is
552 * imperative. A real-time executive should provide an application with the
553 * following capabilities
554 *
555 * - data transfer between cooperating tasks,
556 * - data transfer between tasks and ISRs,
557 * - synchronization of cooperating tasks, and
558 * - synchronization of tasks and ISRs.
559 *
560 * Most RTEMS managers can be used to provide some form of communication and/or
561 * synchronization. However, managers dedicated specifically to communication
562 * and synchronization provide well established mechanisms which directly map
563 * to the application's varying needs. This level of flexibility allows the
564 * application designer to match the features of a particular manager with the
565 * complexity of communication and synchronization required. The following
566 * managers were specifically designed for communication and synchronization:
567 *
568 * - @ref ClassicSem
569 * - @ref ClassicMessageQueue
570 * - @ref ClassicEvent
571 * - @ref ClassicSignal
572 *
573 * The semaphore manager supports mutual exclusion involving the
574 * synchronization of access to one or more shared user resources. Binary
575 * semaphores may utilize the optional priority inheritance algorithm to avoid
576 * the problem of priority inversion. The message manager supports both
577 * communication and synchronization, while the event manager primarily
578 * provides a high performance synchronization mechanism. The signal manager
579 * supports only asynchronous communication and is typically used for exception
580 * handling.
581 *
582 * @section ClassicRTEMSSecTime Time
583 *
584 * The development of responsive real-time applications requires an
585 * understanding of how RTEMS maintains and supports time-related operations.
586 * The basic unit of time in RTEMS is known as a tick. The frequency of clock
587 * ticks is completely application dependent and determines the granularity and
588 * accuracy of all interval and calendar time operations.
589 *
590 * By tracking time in units of ticks, RTEMS is capable of supporting interval
591 * timing functions such as task delays, timeouts, timeslicing, the delayed
592 * execution of timer service routines, and the rate monotonic scheduling of
593 * tasks. An interval is defined as a number of ticks relative to the current
594 * time. For example, when a task delays for an interval of ten ticks, it is
595 * implied that the task will not execute until ten clock ticks have occurred.
596 * All intervals are specified using data type @ref rtems_interval.
597 *
598 * A characteristic of interval timing is that the actual interval period may
599 * be a fraction of a tick less than the interval requested. This occurs
600 * because the time at which the delay timer is set up occurs at some time
601 * between two clock ticks. Therefore, the first countdown tick occurs in less
602 * than the complete time interval for a tick. This can be a problem if the
603 * clock granularity is large.
604 *
605 * The rate monotonic scheduling algorithm is a hard real-time scheduling
606 * methodology. This methodology provides rules which allows one to guarantee
607 * that a set of independent periodic tasks will always meet their deadlines --
608 * even under transient overload conditions. The rate monotonic manager
609 * provides directives built upon the Clock Manager's interval timer support
610 * routines.
611 *
612 * Interval timing is not sufficient for the many applications which require
613 * that time be kept in wall time or true calendar form. Consequently, RTEMS
614 * maintains the current date and time. This allows selected time operations to
615 * be scheduled at an actual calendar date and time. For example, a task could
616 * request to delay until midnight on New Year's Eve before lowering the ball
617 * at Times Square. The data type @ref rtems_time_of_day is used to specify
618 * calendar time in RTEMS services. See Clock Manager Time and Date Data
619 * Structures.
620 *
621 * @todo Link to Clock Manager Time and Date Data Structures
622 *
623 * Obviously, the directives which use intervals or wall time cannot operate
624 * without some external mechanism which provides a periodic clock tick. This
625 * clock tick is typically provided by a real time clock or counter/timer
626 * device.
627 *
628 * @section ClassicRTEMSSecMemoryManagement Memory Management
629 *
630 * RTEMS memory management facilities can be grouped into two classes: dynamic
631 * memory allocation and address translation. Dynamic memory allocation is
632 * required by applications whose memory requirements vary through the
633 * application's course of execution. Address translation is needed by
634 * applications which share memory with another CPU or an intelligent
635 * Input/Output processor. The following RTEMS managers provide facilities to
636 * manage memory:
637 *
638 * - @ref ClassicRegion
639 * - @ref ClassicPart
640 * - @ref ClassicDPMEM
641 *
642 * RTEMS memory management features allow an application to create simple
643 * memory pools of fixed size buffers and/or more complex memory pools of
644 * variable size segments. The partition manager provides directives to manage
645 * and maintain pools of fixed size entities such as resource control blocks.
646 * Alternatively, the region manager provides a more general purpose memory
647 * allocation scheme that supports variable size blocks of memory which are
648 * dynamically obtained and freed by the application. The dual-ported memory
649 * manager provides executive support for address translation between internal
650 * and external dual-ported RAM address space.
651 */
652
653/**
654 * @addtogroup ClassicTasks
655 *
656 * @section ClassicTasksSecTaskDefinition Task Definition
657 *
658 * Many definitions of a task have been proposed in computer literature.
659 * Unfortunately, none of these definitions encompasses all facets of the
660 * concept in a manner which is operating system independent. Several of the
661 * more common definitions are provided to enable each user to select a
662 * definition which best matches their own experience and understanding of the
663 * task concept:
664 *
665 * - a "dispatchable" unit.
666 * - an entity to which the processor is allocated.
667 * - an atomic unit of a real-time, multiprocessor system.
668 * - single threads of execution which concurrently compete for resources.
669 * - a sequence of closely related computations which can execute concurrently
670 *   with other computational sequences.
671 *
672 * From RTEMS' perspective, a task is the smallest thread of execution which
673 * can compete on its own for system resources. A task is manifested by the
674 * existence of a task control block (TCB).
675 *
676 * @section ClassicTasksSecTaskControlBlock Task Control Block
677 *
678 * The Task Control Block (TCB) is an RTEMS defined data structure which
679 * contains all the information that is pertinent to the execution of a task.
680 * During system initialization, RTEMS reserves a TCB for each task configured.
681 * A TCB is allocated upon creation of the task and is returned to the TCB free
682 * list upon deletion of the task.
683 *
684 * The TCB's elements are modified as a result of system calls made by the
685 * application in response to external and internal stimuli. TCBs are the only
686 * RTEMS internal data structure that can be accessed by an application via
687 * user extension routines. The TCB contains a task's name, ID, current
688 * priority, current and starting states, execution mode, set of notepad
689 * locations, TCB user extension pointer, scheduling control structures, as
690 * well as data required by a blocked task.
691 *
692 * A task's context is stored in the TCB when a task switch occurs. When the
693 * task regains control of the processor, its context is restored from the TCB.
694 * When a task is restarted, the initial state of the task is restored from the
695 * starting context area in the task's TCB.
696 *
697 * @section ClassicTasksSecTaskStates Task States
698 *
699 * A task may exist in one of the following five states:
700 *
701 * - executing - Currently scheduled to the CPU
702 * - ready - May be scheduled to the CPU
703 * - blocked - Unable to be scheduled to the CPU
704 * - dormant - Created task that is not started
705 * - non-existent - Uncreated or deleted task
706 *
707 * An active task may occupy the executing, ready, blocked or dormant state,
708 * otherwise the task is considered non-existent. One or more tasks may be
709 * active in the system simultaneously. Multiple tasks communicate,
710 * synchronize, and compete for system resources with each other via system
711 * calls. The multiple tasks appear to execute in parallel, but actually each
712 * is dispatched to the CPU for periods of time determined by the RTEMS
713 * scheduling algorithm. The scheduling of a task is based on its current state
714 * and priority.
715 *
716 * @section ClassicTasksSecTaskPriority Task Priority
717 *
718 * A task's priority determines its importance in relation to the other tasks
719 * executing on the same processor. RTEMS supports 255 levels of priority
720 * ranging from 1 to 255. The data type rtems_task_priority() is used to store
721 * task priorities.
722 *
723 * Tasks of numerically smaller priority values are more important tasks than
724 * tasks of numerically larger priority values. For example, a task at priority
725 * level 5 is of higher privilege than a task at priority level 10. There is no
726 * limit to the number of tasks assigned to the same priority.
727 *
728 * Each task has a priority associated with it at all times. The initial value
729 * of this priority is assigned at task creation time. The priority of a task
730 * may be changed at any subsequent time.
731 *
732 * Priorities are used by the scheduler to determine which ready task will be
733 * allowed to execute. In general, the higher the logical priority of a task,
734 * the more likely it is to receive processor execution time.
735 *
736 * @section ClassicTasksSecTaskMode Task Mode
737 *
738 * A task's execution mode is a combination of the following four components:
739 *
740 * - preemption
741 * - ASR processing
742 * - timeslicing
743 * - interrupt level
744 *
745 * It is used to modify RTEMS' scheduling process and to alter the execution
746 * environment of the task. The data type rtems_task_mode() is used to manage
747 * the task execution mode.
748 *
749 * The preemption component allows a task to determine when control of the
750 * processor is relinquished. If preemption is disabled (@c
751 * RTEMS_NO_PREEMPT), the task will retain control of the
752 * processor as long as it is in the executing state -- even if a higher
753 * priority task is made ready. If preemption is enabled (@c RTEMS_PREEMPT)
754 * and a higher priority task is made ready, then the processor will be
755 * taken away from the current task immediately and given to the higher
756 * priority task.
757 *
758 * The timeslicing component is used by the RTEMS scheduler to determine how
759 * the processor is allocated to tasks of equal priority. If timeslicing is
760 * enabled (@c RTEMS_TIMESLICE), then RTEMS will limit the amount of time the
761 * task can execute before the processor is allocated to another ready task of
762 * equal priority. The length of the timeslice is application dependent and
763 * specified in the Configuration Table. If timeslicing is disabled (@c
764 * RTEMS_NO_TIMESLICE), then the task will be allowed to
765 * execute until a task of higher priority is made ready. If @c
766 * RTEMS_NO_PREEMPT is selected, then the timeslicing component is ignored by
767 * the scheduler.
768 *
769 * The asynchronous signal processing component is used to determine when
770 * received signals are to be processed by the task. If signal processing is
771 * enabled (@c RTEMS_ASR), then signals sent to the task will be processed
772 * the next time the task executes. If signal processing is disabled (@c
773 * RTEMS_NO_ASR), then all signals received by the task will
774 * remain posted until signal processing is enabled. This component affects
775 * only tasks which have established a routine to process asynchronous signals.
776 *
777 * The interrupt level component is used to determine which interrupts will be
778 * enabled when the task is executing. @c RTEMS_INTERRUPT_LEVEL(n) specifies
779 * that the task will execute at interrupt level n.
780 *
781 * - @ref RTEMS_PREEMPT - enable preemption (default)
782 * - @ref RTEMS_NO_PREEMPT - disable preemption
783 * - @ref RTEMS_NO_TIMESLICE - disable timeslicing (default)
784 * - @ref RTEMS_TIMESLICE - enable timeslicing
785 * - @ref RTEMS_ASR - enable ASR processing (default)
786 * - @ref RTEMS_NO_ASR - disable ASR processing
787 * - @ref RTEMS_INTERRUPT_LEVEL(0) - enable all interrupts (default)
788 * - @ref RTEMS_INTERRUPT_LEVEL(n) - execute at interrupt level n
789 *
790 * The set of default modes may be selected by specifying the @ref
791 * RTEMS_DEFAULT_MODES constant.
792 *
793 * @section ClassicTasksSecAccessingTaskArguments Accessing Task Arguments
794 *
795 * All RTEMS tasks are invoked with a single argument which is specified when
796 * they are started or restarted. The argument is commonly used to communicate
797 * startup information to the task. The simplest manner in which to define a
798 * task which accesses it argument is:
799 *
800 * @code
801 *  rtems_task user_task(
802 *      rtems_task_argument argument
803 *  );
804 * @endcode
805 *
806 * Application tasks requiring more information may view this single argument
807 * as an index into an array of parameter blocks.
808 *
809 * @section ClassicTasksSecFloatingPointConsiderations Floating Point Considerations
810 *
811 * Creating a task with the @ref RTEMS_FLOATING_POINT attribute flag results in
812 * additional memory being allocated for the TCB to store the state of the
813 * numeric coprocessor during task switches. This additional memory is NOT
814 * allocated for @ref RTEMS_NO_FLOATING_POINT tasks. Saving and restoring the
815 * context of a @c RTEMS_FLOATING_POINT task takes longer than that of a @c
816 * RTEMS_NO_FLOATING_POINT task because of the relatively large amount of time
817 * required for the numeric coprocessor to save or restore its computational
818 * state.
819 *
820 * Since RTEMS was designed specifically for embedded military applications
821 * which are floating point intensive, the executive is optimized to avoid
822 * unnecessarily saving and restoring the state of the numeric coprocessor. The
823 * state of the numeric coprocessor is only saved when a @c
824 * RTEMS_FLOATING_POINT task is dispatched and that task was not the last task
825 * to utilize the coprocessor. In a system with only one @c
826 * RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will never
827 * be saved or restored.
828 *
829 * Although the overhead imposed by @c RTEMS_FLOATING_POINT tasks is minimal,
830 * some applications may wish to completely avoid the overhead associated with
831 * @c RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor. By
832 * preventing a task from being preempted while performing a sequence of
833 * floating point operations, a @c RTEMS_NO_FLOATING_POINT task can utilize
834 * the numeric coprocessor without incurring the overhead of a @c
835 * RTEMS_FLOATING_POINT context switch. This approach also avoids the
836 * allocation of a floating point context area. However, if this approach is
837 * taken by the application designer, NO tasks should be created as @c
838 * RTEMS_FLOATING_POINT tasks.  Otherwise, the floating point context will not
839 * be correctly maintained because RTEMS assumes that the state of the numeric
840 * coprocessor will not be altered by @c RTEMS_NO_FLOATING_POINT tasks.
841 *
842 * If the supported processor type does not have hardware floating capabilities
843 * or a standard numeric coprocessor, RTEMS will not provide built-in support
844 * for hardware floating point on that processor. In this case, all tasks are
845 * considered @c RTEMS_NO_FLOATING_POINT whether created as @c
846 * RTEMS_FLOATING_POINT or @c RTEMS_NO_FLOATING_POINT tasks. A floating point
847 * emulation software library must be utilized for floating point operations.
848 *
849 * On some processors, it is possible to disable the floating point unit
850 * dynamically. If this capability is supported by the target processor, then
851 * RTEMS will utilize this capability to enable the floating point unit only
852 * for tasks which are created with the @c RTEMS_FLOATING_POINT attribute.
853 * The consequence of a @c RTEMS_NO_FLOATING_POINT task attempting to access
854 * the floating point unit is CPU dependent but will generally result in an
855 * exception condition.
856 *
857 * @section ClassicTasksSecPerTaskVariables Per Task Variables
858 *
859 * Per task variables are used to support global variables whose value may be
860 * unique to a task. After indicating that a variable should be treated as
861 * private (i.e. per-task) the task can access and modify the variable, but the
862 * modifications will not appear to other tasks, and other tasks' modifications
863 * to that variable will not affect the value seen by the task. This is
864 * accomplished by saving and restoring the variable's value each time a task
865 * switch occurs to or from the calling task.
866 *
867 * The value seen by other tasks, including those which have not added the
868 * variable to their set and are thus accessing the variable as a common
869 * location shared among tasks, can not be affected by a task once it has added
870 * a variable to its local set. Changes made to the variable by other tasks
871 * will not affect the value seen by a task which has added the variable to its
872 * private set.
873 *
874 * This feature can be used when a routine is to be spawned repeatedly as
875 * several independent tasks. Although each task will have its own stack, and
876 * thus separate stack variables, they will all share the same static and
877 * global variables. To make a variable not shareable (i.e. a "global" variable
878 * that is specific to a single task), the tasks can call
879 * rtems_task_variable_add() to make a separate copy of the variable for each
880 * task, but all at the same physical address.
881 *
882 * Task variables increase the context switch time to and from the tasks that
883 * own them so it is desirable to minimize the number of task variables. One
884 * efficient method is to have a single task variable that is a pointer to a
885 * dynamically allocated structure containing the task's private "global" data.
886 *
887 * A critical point with per-task variables is that each task must separately
888 * request that the same global variable is per-task private.
889 *
890 * @b {WARNING}: Per-task variables are fundamentally incorrect in SMP
891 *               systems and should not be used in SMP applications. They
892 *               are disabled.
893 *
894 * @section ClassicTasksSecBuildingTaskAttributeSet Building a Task Attribute Set
895 *
896 * In general, an attribute set is built by a bitwise OR of the desired
897 * components. The set of valid task attribute components is listed below:
898 *
899 * - @ref RTEMS_NO_FLOATING_POINT - does not use coprocessor (default)
900 * - @ref RTEMS_FLOATING_POINT - uses numeric coprocessor
901 * - @ref RTEMS_LOCAL - local task (default)
902 * - @ref RTEMS_GLOBAL - global task
903 *
904 * Attribute values are specifically designed to be mutually exclusive,
905 * therefore bitwise OR and addition operations are equivalent as long as each
906 * attribute appears exactly once in the component list. A component listed as
907 * a default is not required to appear in the component list, although it is a
908 * good programming practice to specify default components. If all defaults are
909 * desired, then @ref RTEMS_DEFAULT_ATTRIBUTES should be used.  This example
910 * demonstrates the attribute_set parameter needed to create a local task which
911 * utilizes the numeric coprocessor. The attribute_set parameter could be @c
912 * RTEMS_FLOATING_POINT or @c RTEMS_LOCAL | @c RTEMS_FLOATING_POINT. The
913 * attribute_set parameter can be set to @c RTEMS_FLOATING_POINT because @c
914 * RTEMS_LOCAL is the default for all created tasks. If the task were global
915 * and used the numeric coprocessor, then the attribute_set parameter would be
916 * @c RTEMS_GLOBAL | @c RTEMS_FLOATING_POINT.
917 *
918 * @section ClassicTasksSecBuildingModeAndMask Building a Mode and Mask
919 *
920 * In general, a mode and its corresponding mask is built by a bitwise OR of
921 * the desired components. The set of valid mode constants and each mode's
922 * corresponding mask constant is listed below:
923 *
924 * <table>
925 * <tr><th>Mode Constant</th><th>Mask Constant</th><th>Description</th></tr>
926 * <tr><td>@ref RTEMS_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>enables preemption</td></tr>
927 * <tr><td>@ref RTEMS_NO_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>disables preemption</td></tr>
928 * <tr><td>@ref RTEMS_NO_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>disables timeslicing</td></tr>
929 * <tr><td>@ref RTEMS_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>enables timeslicing</td></tr>
930 * <tr><td>@ref RTEMS_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>enables ASR processing</td></tr>
931 * <tr><td>@ref RTEMS_NO_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>disables ASR processing</td></tr>
932 * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(0)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>enables all interrupts</td></tr>
933 * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(n)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>sets interrupts level n</td></tr>
934 * </table>
935 *
936 * Mode values are specifically designed to be mutually exclusive, therefore
937 * bitwise OR and addition operations are equivalent as long as each mode
938 * appears exactly once in the component list. A mode component listed as a
939 * default is not required to appear in the mode component list, although it is
940 * a good programming practice to specify default components. If all defaults
941 * are desired, the mode @ref RTEMS_DEFAULT_MODES and the mask @ref
942 * RTEMS_ALL_MODE_MASKS should be used.
943 *
944 * The following example demonstrates the mode and mask parameters used with
945 * the rtems_task_mode() directive to place a task at interrupt level 3 and
946 * make it non-preemptible. The mode should be set to @c
947 * RTEMS_INTERRUPT_LEVEL(3) | @c RTEMS_NO_PREEMPT to indicate the desired
948 * preemption mode and interrupt level, while the mask parameter should be set
949 * to @c RTEMS_INTERRUPT_MASK | @c RTEMS_PREEMPT_MASK to indicate that
950 * the calling task's interrupt level and preemption mode are being altered.
951 */
952
953 /**
954  * @defgroup LocalPackages Local Packages
955  *
956  * @brief Local packages.
957  */
Note: See TracBrowser for help on using the repository browser.