source: rtems/cpukit/include/rtems/rtems/mainpage.h @ 78bbe59

5
Last change on this file since 78bbe59 was 2afb22b, checked in by Chris Johns <chrisj@…>, on 12/23/17 at 07:18:56

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 48.3 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, TCB user extension
689 * pointer, scheduling control structures, as well as data required by a
690 * 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 no longer available.  In particular the
860 * rtems_task_variable_add(), rtems_task_variable_get() and
861 * rtems_task_variable_delete() functions are neither declared nor defined
862 * anymore.  Use thread local storage or POSIX Keys instead.
863 *
864 * @section ClassicTasksSecBuildingTaskAttributeSet Building a Task Attribute Set
865 *
866 * In general, an attribute set is built by a bitwise OR of the desired
867 * components. The set of valid task attribute components is listed below:
868 *
869 * - @ref RTEMS_NO_FLOATING_POINT - does not use coprocessor (default)
870 * - @ref RTEMS_FLOATING_POINT - uses numeric coprocessor
871 * - @ref RTEMS_LOCAL - local task (default)
872 * - @ref RTEMS_GLOBAL - global task
873 *
874 * Attribute values are specifically designed to be mutually exclusive,
875 * therefore bitwise OR and addition operations are equivalent as long as each
876 * attribute appears exactly once in the component list. A component listed as
877 * a default is not required to appear in the component list, although it is a
878 * good programming practice to specify default components. If all defaults are
879 * desired, then @ref RTEMS_DEFAULT_ATTRIBUTES should be used.  This example
880 * demonstrates the attribute_set parameter needed to create a local task which
881 * utilizes the numeric coprocessor. The attribute_set parameter could be @c
882 * RTEMS_FLOATING_POINT or @c RTEMS_LOCAL | @c RTEMS_FLOATING_POINT. The
883 * attribute_set parameter can be set to @c RTEMS_FLOATING_POINT because @c
884 * RTEMS_LOCAL is the default for all created tasks. If the task were global
885 * and used the numeric coprocessor, then the attribute_set parameter would be
886 * @c RTEMS_GLOBAL | @c RTEMS_FLOATING_POINT.
887 *
888 * @section ClassicTasksSecBuildingModeAndMask Building a Mode and Mask
889 *
890 * In general, a mode and its corresponding mask is built by a bitwise OR of
891 * the desired components. The set of valid mode constants and each mode's
892 * corresponding mask constant is listed below:
893 *
894 * <table>
895 * <tr><th>Mode Constant</th><th>Mask Constant</th><th>Description</th></tr>
896 * <tr><td>@ref RTEMS_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>enables preemption</td></tr>
897 * <tr><td>@ref RTEMS_NO_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>disables preemption</td></tr>
898 * <tr><td>@ref RTEMS_NO_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>disables timeslicing</td></tr>
899 * <tr><td>@ref RTEMS_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>enables timeslicing</td></tr>
900 * <tr><td>@ref RTEMS_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>enables ASR processing</td></tr>
901 * <tr><td>@ref RTEMS_NO_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>disables ASR processing</td></tr>
902 * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(0)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>enables all interrupts</td></tr>
903 * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(n)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>sets interrupts level n</td></tr>
904 * </table>
905 *
906 * Mode values are specifically designed to be mutually exclusive, therefore
907 * bitwise OR and addition operations are equivalent as long as each mode
908 * appears exactly once in the component list. A mode component listed as a
909 * default is not required to appear in the mode component list, although it is
910 * a good programming practice to specify default components. If all defaults
911 * are desired, the mode @ref RTEMS_DEFAULT_MODES and the mask @ref
912 * RTEMS_ALL_MODE_MASKS should be used.
913 *
914 * The following example demonstrates the mode and mask parameters used with
915 * the rtems_task_mode() directive to place a task at interrupt level 3 and
916 * make it non-preemptible. The mode should be set to @c
917 * RTEMS_INTERRUPT_LEVEL(3) | @c RTEMS_NO_PREEMPT to indicate the desired
918 * preemption mode and interrupt level, while the mask parameter should be set
919 * to @c RTEMS_INTERRUPT_MASK | @c RTEMS_PREEMPT_MASK to indicate that
920 * the calling task's interrupt level and preemption mode are being altered.
921 */
922
923 /**
924  * @defgroup LocalPackages Local Packages
925  *
926  * @brief Local packages.
927  */
Note: See TracBrowser for help on using the repository browser.