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 | */ |
---|