<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jul 26, 2023 at 12:50 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Replace the main page with a high level description of the RTEMS feature<br>
set similar to:<br>
<br>
<a href="https://docs.rtems.org/branches/master/user/overview/index.html#features" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/user/overview/index.html#features</a><br>
<br>
The replaced content can be found in the RTEMS Classic API Guide:<br>
<br>
<a href="https://docs.rtems.org/branches/master/c-user/overview.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/c-user/overview.html</a><br>
<br>
<a href="https://docs.rtems.org/branches/master/c-user/key_concepts.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/c-user/key_concepts.html</a><br>
<br>
Update #3705.<br>
---<br>
 cpukit/include/rtems/rtems/mainpage.h | 1078 ++++---------------------<br>
 1 file changed, 166 insertions(+), 912 deletions(-)<br>
<br>
diff --git a/cpukit/include/rtems/rtems/mainpage.h b/cpukit/include/rtems/rtems/mainpage.h<br>
index f168cc3395..d284429d20 100644<br>
--- a/cpukit/include/rtems/rtems/mainpage.h<br>
+++ b/cpukit/include/rtems/rtems/mainpage.h<br>
@@ -10,8 +10,7 @@<br>
  */<br>
<br>
 /*<br>
- *  COPYRIGHT (c) 1989-2014.<br>
- *  On-Line Applications Research Corporation (OAR).<br>
+ * Copyright (C) 2021 embedded brains GmbH & Co. KG<br></blockquote><div><br></div><div>No. You are reformatting this. This text dates back to the beginnings of</div><div>RTEMS. You should NOT remove the OAR copyright.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
  *<br>
  * Redistribution and use in source and binary forms, with or without<br>
  * modification, are permitted provided that the following conditions<br>
@@ -38,914 +37,169 @@<br>
 /**<br>
  * @mainpage<br>
  *<br>
- * The RTEMS real-time operating systems is a layered system with each of the<br>
- * public APIs implemented in terms of a common foundation layer called the<br>
- * SuperCore.  This is the Doxygen generated documentation for the RTEMS CPU<br>
- * Kit including the Classic API, POSIX API and SuperCore.<br>
- */<br>
-<br>
-/**<br>
- * @page RTEMSPreface RTEMS History and Introduction<br>
- *<br>
- * In recent years, the cost required to develop a software product has<br>
- * increased significantly while the target hardware costs have decreased. Now<br>
- * a larger portion of money is expended in developing, using, and maintaining<br>
- * software. The trend in computing costs is the complete dominance of software<br>
- * over hardware costs. Because of this, it is necessary that formal<br>
- * disciplines be established to increase the probability that software is<br>
- * characterized by a high degree of correctness, maintainability, and<br>
- * portability. In addition, these disciplines must promote practices that aid<br>
- * in the consistent and orderly development of a software system within<br>
- * schedule and budgetary constraints. To be effective, these disciplines must<br>
- * adopt standards which channel individual software efforts toward a common<br>
- * goal.<br>
- *<br>
- * The push for standards in the software development field has been met with<br>
- * various degrees of success. The Microprocessor Operating Systems Interfaces<br>
- * (MOSI) effort has experienced only limited success. As popular as the UNIX<br>
- * operating system has grown, the attempt to develop a standard interface<br>
- * definition to allow portable application development has only recently begun<br>
- * to produce the results needed in this area. Unfortunately, very little<br>
- * effort has been expended to provide standards addressing the needs of the<br>
- * real-time community. Several organizations have addressed this need during<br>
- * recent years.<br>
- *<br>
- * The Real Time Executive Interface Definition (RTEID) was developed by<br>
- * Motorola with technical input from Software Components Group. RTEID was<br>
- * adopted by the VMEbus International Trade Association (VITA) as a baseline<br>
- * draft for their proposed standard multiprocessor, real-time executive<br>
- * interface, Open Real-Time Kernel Interface Definition (ORKID). These two<br>
- * groups are currently working together with the IEEE P1003.4 committee to<br>
- * insure that the functionality of their proposed standards is adopted as the<br>
- * real-time extensions to POSIX.<br>
- *<br>
- * This emerging standard defines an interface for the development of real-time<br>
- * software to ease the writing of real-time application programs that are<br>
- * directly portable across multiple real-time executive implementations. This<br>
- * interface includes both the source code interfaces and run-time behavior as<br>
- * seen by a real-time application. It does not include the details of how a<br>
- * kernel implements these functions. The standard's goal is to serve as a<br>
- * complete definition of external interfaces so that application code that<br>
- * conforms to these interfaces will execute properly in all real-time<br>
- * executive environments. With the use of a standards compliant executive,<br>
- * routines that acquire memory blocks, create and manage message queues,<br>
- * establish and use semaphores, and send and receive signals need not be<br>
- * redeveloped for a different real-time environment as long as the new<br>
- * environment is compliant with the standard. Software developers need only<br>
- * concentrate on the hardware dependencies of the real-time system.<br>
- * Furthermore, most hardware dependencies for real-time applications can be<br>
- * localized to the device drivers.<br>
- *<br>
- * A compliant executive provides simple and flexible real-time<br>
- * multiprocessing. It easily lends itself to both tightly-coupled and<br>
- * loosely-coupled configurations (depending on the system hardware<br>
- * configuration). Objects such as tasks, queues, events, signals, semaphores,<br>
- * and memory blocks can be designated as global objects and accessed by any<br>
- * task regardless of which processor the object and the accessing task reside.<br>
- *<br>
- * The acceptance of a standard for real-time executives will produce the same<br>
- * advantages enjoyed from the push for UNIX standardization by AT&T's System V<br>
- * Interface Definition and IEEE's POSIX efforts. A compliant multiprocessing<br>
- * executive will allow close coupling between UNIX systems and real-time<br>
- * executives to provide the many benefits of the UNIX development environment<br>
- * to be applied to real-time software development. Together they provide the<br>
- * necessary laboratory environment to implement real-time, distributed,<br>
- * embedded systems using a wide variety of computer architectures.<br>
- *<br>
- * A study was completed in 1988, within the Research, Development, and<br>
- * Engineering Center, U.S. Army Missile Command, which compared the various<br>
- * aspects of the Ada programming language as they related to the application<br>
- * of Ada code in distributed and/or multiple processing systems. Several<br>
- * critical conclusions were derived from the study. These conclusions have a<br>
- * major impact on the way the Army develops application software for embedded<br>
- * applications. These impacts apply to both in-house software development and<br>
- * contractor developed software.<br>
- *<br>
- * A conclusion of the analysis, which has been previously recognized by other<br>
- * agencies attempting to utilize Ada in a distributed or multiprocessing<br>
- * environment, is that the Ada programming language does not adequately<br>
- * support multiprocessing. Ada does provide a mechanism for multi-tasking,<br>
- * however, this capability exists only for a single processor system. The<br>
- * language also does not have inherent capabilities to access global named<br>
- * variables, flags or program code. These critical features are essential in<br>
- * order for data to be shared between processors. However, these drawbacks do<br>
- * have workarounds which are sometimes awkward and defeat the intent of<br>
- * software maintainability and portability goals.<br>
- *<br>
- * Another conclusion drawn from the analysis, was that the run time executives<br>
- * being delivered with the Ada compilers were too slow and inefficient to be<br>
- * used in modern missile systems. A run time executive is the core part of the<br>
- * run time system code, or operating system code, that controls task<br>
- * scheduling, input/output management and memory management. Traditionally,<br>
- * whenever efficient executive (also known as kernel) code was required by the<br>
- * application, the user developed in-house software. This software was usually<br>
- * written in assembly language for optimization.<br>
- *<br>
- * Because of this shortcoming in the Ada programming language, software<br>
- * developers in research and development and contractors for project managed<br>
- * systems, are mandated by technology to purchase and utilize off-the-shelf<br>
- * third party kernel code. The contractor, and eventually the Government, must<br>
- * pay a licensing fee for every copy of the kernel code used in an embedded<br>
- * system.<br>
- *<br>
- * The main drawback to this development environment is that the Government<br>
- * does not own, nor has the right to modify code contained within the kernel.<br>
- * V&V techniques in this situation are more difficult than if the complete<br>
- * source code were available. Responsibility for system failures due to faulty<br>
- * software is yet another area to be resolved under this environment.<br>
- *<br>
- * The Guidance and Control Directorate began a software development effort to<br>
- * address these problems. A project to develop an experimental run time kernel<br>
- * was begun that will eliminate the major drawbacks of the Ada programming<br>
- * language mentioned above. The Real Time Executive for Multiprocessor Systems<br>
- * (RTEMS) provides full capabilities for management of tasks, interrupts,<br>
- * time, and multiple processors in addition to those features typical of<br>
- * generic operating systems. The code is Government owned, so no licensing<br>
- * fees are necessary. RTEMS has been implemented in both the Ada and C<br>
- * programming languages. It has been ported to the following processor<br>
- * families:<br>
- *<br>
- * - Altera NIOS II<br>
- * - Analog Devices Blackfin<br>
- * - ARM<br>
- * - Freescale (formerly Motorola) MC68xxx<br>
- * - Freescale (formerly Motorola) MC683xx<br>
- * - Freescale (formerly Motorola) ColdFire<br>
- * - Intel i386 and above<br>
- * - Lattice Semiconductor LM32<br>
- * - MIPS<br>
- * - PowerPC<br>
- * - Renesas (formerly Hitachi) SuperH<br>
- * - Renesas (formerly Hitachi) H8/300<br>
- * - SPARC<br>
- * - Texas Instruments C3x/C4x<br>
- * - UNIX <br>
- *<br>
- * Support for other processor families, including RISC, CISC, and DSP, is<br>
- * planned. Since almost all of RTEMS is written in a high level language,<br>
- * ports to additional processor families require minimal effort.<br>
- *<br>
- * RTEMS multiprocessor support is capable of handling either homogeneous or<br>
- * heterogeneous systems. The kernel automatically compensates for<br>
- * architectural differences (byte swapping, etc.) between processors. This<br>
- * allows a much easier transition from one processor family to another without<br>
- * a major system redesign.<br>
- *<br>
- * Since the proposed standards are still in draft form, RTEMS cannot and does<br>
- * not claim compliance. However, the status of the standard is being carefully<br>
- * monitored to guarantee that RTEMS provides the functionality specified in<br>
- * the standard. Once approved, RTEMS will be made compliant.<br>
- */<br>
-<br>
-/**<br>
- * @page RTEMSOverview RTEMS Overview<br>
- *<br>
- * @section RTEMSOverviewSecIntroduction Introduction<br>
- *<br>
- * RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time<br>
- * executive (kernel) which provides a high performance environment for<br>
- * embedded military applications including the following features:<br>
- *<br>
- * - multitasking capabilities<br>
- * - homogeneous and heterogeneous multiprocessor systems<br>
- * - event-driven, priority-based, preemptive scheduling<br>
- * - optional rate monotonic scheduling<br>
- * - intertask communication and synchronization<br>
- * - priority inheritance<br>
- * - responsive interrupt management<br>
- * - dynamic memory allocation<br>
- * - high level of user configurability<br>
- *<br>
- * This manual describes the usage of RTEMS for applications written in the C<br>
- * programming language. Those implementation details that are processor<br>
- * dependent are provided in the Applications Supplement documents. A<br>
- * supplement document which addresses specific architectural issues that<br>
- * affect RTEMS is provided for each processor type that is supported.<br>
- *<br>
- * @section RTEMSOverviewSecRealtimeApplicationSystems Real-time Application Systems<br>
- *<br>
- * Real-time application systems are a special class of computer applications.<br>
- * They have a complex set of characteristics that distinguish them from other<br>
- * software problems. Generally, they must adhere to more rigorous<br>
- * requirements. The correctness of the system depends not only on the results<br>
- * of computations, but also on the time at which the results are produced. The<br>
- * most important and complex characteristic of real-time application systems<br>
- * is that they must receive and respond to a set of external stimuli within<br>
- * rigid and critical time constraints referred to as deadlines. Systems can be<br>
- * buried by an avalanche of interdependent, asynchronous or cyclical event<br>
- * streams.<br>
- *<br>
- * Deadlines can be further characterized as either hard or soft based upon the<br>
- * value of the results when produced after the deadline has passed. A deadline<br>
- * is hard if the results have no value or if their use will result in a<br>
- * catastrophic event. In contrast, results which are produced after a soft<br>
- * deadline may have some value.<br>
- *<br>
- * Another distinguishing requirement of real-time application systems is the<br>
- * ability to coordinate or manage a large number of concurrent activities.<br>
- * Since software is a synchronous entity, this presents special problems. One<br>
- * instruction follows another in a repeating synchronous cycle. Even though<br>
- * mechanisms have been developed to allow for the processing of external<br>
- * asynchronous events, the software design efforts required to process and<br>
- * manage these events and tasks are growing more complicated.<br>
- *<br>
- * The design process is complicated further by spreading this activity over a<br>
- * set of processors instead of a single processor. The challenges associated<br>
- * with designing and building real-time application systems become very<br>
- * complex when multiple processors are involved. New requirements such as<br>
- * interprocessor communication channels and global resources that must be<br>
- * shared between competing processors are introduced. The ramifications of<br>
- * multiple processors complicate each and every characteristic of a real-time<br>
- * system.<br>
- *<br>
- * @section RTEMSOverviewSecRealtimeExecutive Real-time Executive<br>
- *<br>
- * Fortunately, real-time operating systems or real-time executives serve as a<br>
- * cornerstone on which to build the application system. A real-time<br>
- * multitasking executive allows an application to be cast into a set of<br>
- * logical, autonomous processes or tasks which become quite manageable. Each<br>
- * task is internally synchronous, but different tasks execute independently,<br>
- * resulting in an asynchronous processing stream. Tasks can be dynamically<br>
- * paused for many reasons resulting in a different task being allowed to<br>
- * execute for a period of time. The executive also provides an interface to<br>
- * other system components such as interrupt handlers and device drivers.<br>
- * System components may request the executive to allocate and coordinate<br>
- * resources, and to wait for and trigger synchronizing conditions. The<br>
- * executive system calls effectively extend the CPU instruction set to support<br>
- * efficient multitasking. By causing tasks to travel through well-defined<br>
- * state transitions, system calls permit an application to demand-switch<br>
- * between tasks in response to real-time events.<br>
- *<br>
- * By proper grouping of responses to stimuli into separate tasks, a system can<br>
- * now asynchronously switch between independent streams of execution, directly<br>
- * responding to external stimuli as they occur. This allows the system design<br>
- * to meet critical performance specifications which are typically measured by<br>
- * guaranteed response time and transaction throughput. The multiprocessor<br>
- * extensions of RTEMS provide the features necessary to manage the extra<br>
- * requirements introduced by a system distributed across several processors.<br>
- * It removes the physical barriers of processor boundaries from the world of<br>
- * the system designer, enabling more critical aspects of the system to receive<br>
- * the required attention. Such a system, based on an efficient real-time,<br>
- * multiprocessor executive, is a more realistic model of the outside world or<br>
- * environment for which it is designed. As a result, the system will always be<br>
- * more logical, efficient, and reliable.<br>
- *<br>
- * By using the directives provided by RTEMS, the real-time applications<br>
- * developer is freed from the problem of controlling and synchronizing<br>
- * multiple tasks and processors. In addition, one need not develop, test,<br>
- * debug, and document routines to manage memory, pass messages, or provide<br>
- * mutual exclusion. The developer is then able to concentrate solely on the<br>
- * application. By using standard software components, the time and cost<br>
- * required to develop sophisticated real-time applications is significantly<br>
- * reduced.<br>
- *<br>
- * @section RTEMSOverviewSecApplicationArchitecture RTEMS Application Architecture<br>
- *<br>
- * One important design goal of RTEMS was to provide a bridge between two<br>
- * critical layers of typical real-time systems. As shown in the following<br>
- * figure, RTEMS serves as a buffer between the project dependent application<br>
- * code and the target hardware. Most hardware dependencies for real-time<br>
- * applications can be localized to the low level device drivers.<br>
- *<br>
- * @todo Image RTEMS Application Architecture<br>
- *<br>
- * The RTEMS I/O interface manager provides an efficient tool for incorporating<br>
- * these hardware dependencies into the system while simultaneously providing a<br>
- * general mechanism to the application code that accesses them. A well<br>
- * designed real-time system can benefit from this architecture by building a<br>
- * rich library of standard application components which can be used repeatedly<br>
- * in other real-time projects.<br>
- *<br>
- * @section RTEMSOverviewSecInternalArchitecture RTEMS Internal Architecture<br>
- *<br>
- * RTEMS can be viewed as a set of layered components that work in harmony to<br>
- * provide a set of services to a real-time application system. The executive<br>
- * interface presented to the application is formed by grouping directives into<br>
- * logical sets called resource managers. Functions utilized by multiple<br>
- * managers such as scheduling, dispatching, and object management are provided<br>
- * in the executive core. The executive core depends on a small set of CPU<br>
- * dependent routines. Together these components provide a powerful run time<br>
- * environment that promotes the development of efficient real-time application<br>
- * systems. The following figure illustrates this organization:<br>
- *<br>
- * @todo Image RTEMS Architecture<br>
- *<br>
- * Subsequent chapters present a detailed description of the capabilities<br>
- * provided by each of the following RTEMS managers:<br>
- *<br>
- * - initialization<br>
- * - task<br>
- * - interrupt<br>
- * - clock<br>
- * - timer<br>
- * - semaphore<br>
- * - message<br>
- * - event<br>
- * - signal<br>
- * - partition<br>
- * - region<br>
- * - dual ported memory<br>
- * - I/O<br>
- * - fatal error<br>
- * - rate monotonic<br>
- * - user extensions<br>
- * - multiprocessing<br>
- *<br>
- * @section RTEMSOverviewSecUserCustomization User Customization and Extensibility<br>
- *<br>
- * As 32-bit microprocessors have decreased in cost, they have become<br>
- * increasingly common in a variety of embedded systems. A wide range of custom<br>
- * and general-purpose processor boards are based on various 32-bit<br>
- * processors. RTEMS was designed to make no assumptions concerning the<br>
- * characteristics of individual microprocessor families or of specific support<br>
- * hardware. In addition, RTEMS allows the system developer a high degree of<br>
- * freedom in customizing and extending its features.<br>
- *<br>
- * RTEMS assumes the existence of a supported microprocessor and sufficient<br>
- * memory for both RTEMS and the real-time application. Board dependent<br>
- * components such as clocks, interrupt controllers, or I/O devices can be<br>
- * easily integrated with RTEMS. The customization and extensibility features<br>
- * allow RTEMS to efficiently support as many environments as possible.<br>
- *<br>
- * @section RTEMSOverviewSecPortability Portability<br>
- *<br>
- * The issue of portability was the major factor in the creation of RTEMS.<br>
- * Since RTEMS is designed to isolate the hardware dependencies in the specific<br>
- * board support packages, the real-time application should be easily ported to<br>
- * any other processor. The use of RTEMS allows the development of real-time<br>
- * applications which can be completely independent of a particular<br>
- * microprocessor architecture.<br>
- *<br>
- * @section RTEMSOverviewSecMemoryRequirements Memory Requirements<br>
- *<br>
- * Since memory is a critical resource in many real-time embedded systems,<br>
- * RTEMS was specifically designed to automatically leave out all services that<br>
- * are not required from the run-time environment. Features such as networking,<br>
- * various filesystems, and many other features are completely optional. This<br>
- * allows the application designer the flexibility to tailor RTEMS to most<br>
- * efficiently meet system requirements while still satisfying even the most<br>
- * stringent memory constraints. As a result, the size of the RTEMS executive<br>
- * is application dependent.<br>
- *<br>
- * RTEMS requires RAM to manage each instance of an RTEMS object that is<br>
- * created. Thus the more RTEMS objects an application needs, the more memory<br>
- * that must be reserved. See Configuring a System Determining Memory<br>
- * Requirements for more details.<br>
- *<br>
- * @todo Link to Configuring a SystemDetermining Memory Requirements<br>
- *<br>
- * RTEMS utilizes memory for both code and data space. Although RTEMS' data<br>
- * space must be in RAM, its code space can be located in either ROM or RAM.<br>
- *<br>
- * @section RTEMSOverviewSecAudience Audience<br>
- *<br>
- * This manual was written for experienced real-time software developers.<br>
- * Although some background is provided, it is assumed that the reader is<br>
- * familiar with the concepts of task management as well as intertask<br>
- * communication and synchronization. Since directives, user related data<br>
- * structures, and examples are presented in C, a basic understanding of the C<br>
- * programming language is required to fully understand the material presented.<br>
- * However, because of the similarity of the Ada and C RTEMS implementations,<br>
- * users will find that the use and behavior of the two implementations is very<br>
- * similar. A working knowledge of the target processor is helpful in<br>
- * understanding some of RTEMS' features. A thorough understanding of the<br>
- * executive cannot be obtained without studying the entire manual because many<br>
- * of RTEMS' concepts and features are interrelated. Experienced RTEMS users<br>
- * will find that the manual organization facilitates its use as a reference<br>
- * document.<br>
- */<br>
-<br>
-/**<br>
- * @addtogroup RTEMSAPIClassic<br>
- *<br>
- * The facilities provided by RTEMS are built upon a foundation of very<br>
- * powerful concepts. These concepts must be understood before the application<br>
- * developer can efficiently utilize RTEMS. The purpose of this chapter is to<br>
- * familiarize one with these concepts.<br>
- *<br>
- * @section ClassicRTEMSSecObjects Objects<br>
- *<br>
- * RTEMS provides directives which can be used to dynamically create, delete,<br>
- * and manipulate a set of predefined object types. These types include tasks,<br>
- * message queues, semaphores, memory regions, memory partitions, timers,<br>
- * ports, and rate monotonic periods. The object-oriented nature of RTEMS<br>
- * encourages the creation of modular applications built upon re-usable<br>
- * "building block" routines.<br>
- *<br>
- * All objects are created on the local node as required by the application and<br>
- * have an RTEMS assigned ID. All objects have a user-assigned name. Although a<br>
- * relationship exists between an object's name and its RTEMS assigned ID, the<br>
- * name and ID are not identical. Object names are completely arbitrary and<br>
- * selected by the user as a meaningful "tag" which may commonly reflect the<br>
- * object's use in the application. Conversely, object IDs are designed to<br>
- * facilitate efficient object manipulation by the executive.<br>
- * <br>
- * @subsection ClassicRTEMSSubSecObjectNames Object Names<br>
- *<br>
- * An object name is an unsigned 32-bit entity associated with the<br>
- * object by the user. The data type @ref rtems_name is used to store object names.<br>
- *<br>
- * Although not required by RTEMS, object names are often composed of four<br>
- * ASCII characters which help identify that object. For example, a task which<br>
- * causes a light to blink might be called "LITE". The rtems_build_name()<br>
- * routine is provided to build an object name from four ASCII characters. The<br>
- * following example illustrates this:<br>
- * <br>
- * @code<br>
- * rtems_name my_name = rtems_build_name('L', 'I', 'T', 'E');<br>
- * @endcode<br>
- *<br>
- * However, it is not required that the application use ASCII characters to<br>
- * build object names. For example, if an application requires one-hundred<br>
- * tasks, it would be difficult to assign meaningful ASCII names to each task.<br>
- * A more convenient approach would be to name them the binary values one<br>
- * through one-hundred, respectively.<br>
- *<br>
- * RTEMS provides a helper routine, rtems_object_get_name(), which can be used to<br>
- * obtain the name of any RTEMS object using just its ID. This routine attempts<br>
- * to convert the name into a printable string.<br>
- * <br>
- * @subsection ClassicRTEMSSubSecObjectIdentifiers Object Identifiers<br>
- *<br>
- * An object ID is a unique unsigned integer value which uniquely identifies an<br>
- * object instance. Object IDs are passed as arguments to many directives in<br>
- * RTEMS and RTEMS translates the ID to an internal object pointer. The<br>
- * efficient manipulation of object IDs is critical to the performance of RTEMS<br>
- * services. Because of this, there are two object ID formats defined. Each<br>
- * target architecture specifies which format it will use. There is a 32-bit<br>
- * format which is used for most of the supported architectures and supports<br>
- * multiprocessor configurations. There is also a simpler 16-bit format which<br>
- * is appropriate for smaller target architectures and does not support<br>
- * multiprocessor configurations.<br>
- *<br>
- * @subsubsection ClassicRTEMSSubSec32BitObjectIdentifierFormat 32-Bit Object Identifier Format<br>
- *<br>
- * The 32-bit format for an object ID is composed of four parts: API,<br>
- * object class, node, and index. The data type @ref rtems_id is used to store<br>
- * object IDs.<br>
- *<br>
- * <table><br>
- *   <tr><br>
- *     <th>Bits</th><br>
- *     <td>31</td><td>30</td><td>29</td><td>28</td><td>27</td><td>26</td><td>25</td><td>24</td><br>
- *     <td>23</td><td>22</td><td>21</td><td>20</td><td>19</td><td>18</td><td>17</td><td>16</td><br>
- *     <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td><br>
- *     <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td><br>
- *   </tr><br>
- *   <tr><br>
- *     <th>Contents</th><br>
- *     <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Node</td><td colspan=16>Object Index</td><br>
- *   </tr><br>
- * </table><br>
- *<br>
- * The most significant five bits are the object class. The next three bits<br>
- * indicate the API to which the object class belongs. The next eight bits<br>
- * (16 .. 23) are the number of the node on which this object was created. The<br>
- * node number is always one (1) in a single processor system. The least<br>
- * significant 16-bits form an identifier within a particular object type.<br>
- * This identifier, called the object index, ranges in value from one to the<br>
- * maximum number of objects configured for this object type.<br>
- *<br>
- * @subsubsection ClassicRTEMSSubSec16BitObjectIdentifierFormat 16-Bit Object Identifier Format<br>
- *<br>
- * The 16-bit format for an object ID is composed of three parts: API, object<br>
- * class, and index. The data type @ref rtems_id is used to store object IDs.<br>
- *<br>
- * <table><br>
- *   <tr><br>
- *     <th>Bits</th><br>
- *     <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td><br>
- *     <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td><br>
- *   </tr><br>
- *   <tr><br>
- *     <th>Contents</th><br>
- *     <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Object Index</td><br>
- *   </tr><br>
- * </table><br>
- *<br>
- * The 16-bit format is designed to be as similar as possible to the 32-bit<br>
- * format. The differences are limited to the elimination of the node field<br>
- * and reduction of the index field from 16-bits to 8-bits.  Thus the 16-bit<br>
- * format only supports up to 255 object instances per API/Class combination<br>
- * and single processor systems. As this format is typically utilized by 16-bit<br>
- * processors with limited address space, this is more than enough object<br>
- * instances.<br>
- *<br>
- * @subsection ClassicRTEMSSubSecObjectIdentiferDescription Object Identifer Description<br>
- *<br>
- * The components of an object ID make it possible to quickly locate any object<br>
- * in even the most complicated multiprocessor system. Object ID's are<br>
- * associated with an object by RTEMS when the object is created and the<br>
- * corresponding ID is returned by the appropriate object create directive. The<br>
- * object ID is required as input to all directives involving objects, except<br>
- * those which create an object or obtain the ID of an object.<br>
- *<br>
- * The object identification directives can be used to dynamically obtain a<br>
- * particular object's ID given its name. This mapping is accomplished by<br>
- * searching the name table associated with this object type. If the name is<br>
- * non-unique, then the ID associated with the first occurrence of the name<br>
- * will be returned to the application. Since object IDs are returned when the<br>
- * object is created, the object identification directives are not necessary in<br>
- * a properly designed single processor application.<br>
- *<br>
- * In addition, services are provided to portably examine the subcomponents of<br>
- * an RTEMS ID. These services are described in detail later in this manual but<br>
- * are prototyped as follows:<br>
- *<br>
- * - rtems_object_id_get_api()<br>
- * - rtems_object_id_get_class()<br>
- * - rtems_object_id_get_node()<br>
- * - rtems_object_id_get_index()<br>
- *<br>
- * An object control block is a data structure defined by RTEMS which contains<br>
- * the information necessary to manage a particular object type. For efficiency<br>
- * reasons, the format of each object type's control block is different.<br>
- * However, many of the fields are similar in function. The number of each type<br>
- * of control block is application dependent and determined by the values<br>
- * specified in the user's Configuration Table. An object control block is<br>
- * allocated at object create time and freed when the object is deleted. With<br>
- * the exception of user extension routines, object control blocks are not<br>
- * directly manipulated by user applications.<br>
- *<br>
- * @section ClassicRTEMSSecComSync Communication and Synchronization<br>
- *<br>
- * In real-time multitasking applications, the ability for cooperating<br>
- * execution threads to communicate and synchronize with each other is<br>
- * imperative. A real-time executive should provide an application with the<br>
- * following capabilities<br>
- *<br>
- * - data transfer between cooperating tasks,<br>
- * - data transfer between tasks and ISRs,<br>
- * - synchronization of cooperating tasks, and<br>
- * - synchronization of tasks and ISRs.<br>
- *<br>
- * Most RTEMS managers can be used to provide some form of communication and/or<br>
- * synchronization. However, managers dedicated specifically to communication<br>
- * and synchronization provide well established mechanisms which directly map<br>
- * to the application's varying needs. This level of flexibility allows the<br>
- * application designer to match the features of a particular manager with the<br>
- * complexity of communication and synchronization required. The following<br>
- * managers were specifically designed for communication and synchronization:<br>
- *<br>
- * - @ref ClassicSem<br>
- * - @ref ClassicMessageQueue<br>
- * - @ref ClassicEvent<br>
- * - @ref ClassicSignal<br>
- *<br>
- * The semaphore manager supports mutual exclusion involving the<br>
- * synchronization of access to one or more shared user resources. Binary<br>
- * semaphores may utilize the optional priority inheritance algorithm to avoid<br>
- * the problem of priority inversion. The message manager supports both<br>
- * communication and synchronization, while the event manager primarily<br>
- * provides a high performance synchronization mechanism. The signal manager<br>
- * supports only asynchronous communication and is typically used for exception<br>
- * handling.<br>
- *<br>
- * @section ClassicRTEMSSecTime Time<br>
- *<br>
- * The development of responsive real-time applications requires an<br>
- * understanding of how RTEMS maintains and supports time-related operations.<br>
- * The basic unit of time in RTEMS is known as a tick. The frequency of clock<br>
- * ticks is completely application dependent and determines the granularity and<br>
- * accuracy of all interval and calendar time operations.<br>
- *<br>
- * By tracking time in units of ticks, RTEMS is capable of supporting interval<br>
- * timing functions such as task delays, timeouts, timeslicing, the delayed<br>
- * execution of timer service routines, and the rate monotonic scheduling of<br>
- * tasks. An interval is defined as a number of ticks relative to the current<br>
- * time. For example, when a task delays for an interval of ten ticks, it is<br>
- * implied that the task will not execute until ten clock ticks have occurred.<br>
- * All intervals are specified using data type @ref rtems_interval.<br>
- *<br>
- * A characteristic of interval timing is that the actual interval period may<br>
- * be a fraction of a tick less than the interval requested. This occurs<br>
- * because the time at which the delay timer is set up occurs at some time<br>
- * between two clock ticks. Therefore, the first countdown tick occurs in less<br>
- * than the complete time interval for a tick. This can be a problem if the<br>
- * clock granularity is large.<br>
- *<br>
- * The rate monotonic scheduling algorithm is a hard real-time scheduling<br>
- * methodology. This methodology provides rules which allows one to guarantee<br>
- * that a set of independent periodic tasks will always meet their deadlines --<br>
- * even under transient overload conditions. The rate monotonic manager<br>
- * provides directives built upon the Clock Manager's interval timer support<br>
- * routines.<br>
- *<br>
- * Interval timing is not sufficient for the many applications which require<br>
- * that time be kept in wall time or true calendar form. Consequently, RTEMS<br>
- * maintains the current date and time. This allows selected time operations to<br>
- * be scheduled at an actual calendar date and time. For example, a task could<br>
- * request to delay until midnight on New Year's Eve before lowering the ball<br>
- * at Times Square. The data type @ref rtems_time_of_day is used to specify<br>
- * calendar time in RTEMS services. See Clock Manager Time and Date Data<br>
- * Structures.<br>
- *<br>
- * @todo Link to Clock Manager Time and Date Data Structures<br>
- *<br>
- * Obviously, the directives which use intervals or wall time cannot operate<br>
- * without some external mechanism which provides a periodic clock tick. This<br>
- * clock tick is typically provided by a real time clock or counter/timer<br>
- * device.<br>
- *<br>
- * @section ClassicRTEMSSecMemoryManagement Memory Management<br>
- *<br>
- * RTEMS memory management facilities can be grouped into two classes: dynamic<br>
- * memory allocation and address translation. Dynamic memory allocation is<br>
- * required by applications whose memory requirements vary through the<br>
- * application's course of execution. Address translation is needed by<br>
- * applications which share memory with another CPU or an intelligent<br>
- * Input/Output processor. The following RTEMS managers provide facilities to<br>
- * manage memory:<br>
- *<br>
- * - @ref ClassicRegion<br>
- * - @ref ClassicPart<br>
- * - @ref ClassicDPMEM <br>
- *<br>
- * RTEMS memory management features allow an application to create simple<br>
- * memory pools of fixed size buffers and/or more complex memory pools of<br>
- * variable size segments. The partition manager provides directives to manage<br>
- * and maintain pools of fixed size entities such as resource control blocks.<br>
- * Alternatively, the region manager provides a more general purpose memory<br>
- * allocation scheme that supports variable size blocks of memory which are<br>
- * dynamically obtained and freed by the application. The dual-ported memory<br>
- * manager provides executive support for address translation between internal<br>
- * and external dual-ported RAM address space.<br>
- */<br>
-<br>
-/**<br>
- * @addtogroup RTEMSAPIClassicTasks<br>
- *<br>
- * @section ClassicTasksSecTaskDefinition Task Definition<br>
- *<br>
- * Many definitions of a task have been proposed in computer literature.<br>
- * Unfortunately, none of these definitions encompasses all facets of the<br>
- * concept in a manner which is operating system independent. Several of the<br>
- * more common definitions are provided to enable each user to select a<br>
- * definition which best matches their own experience and understanding of the<br>
- * task concept:<br>
- *<br>
- * - a "dispatchable" unit.<br>
- * - an entity to which the processor is allocated.<br>
- * - an atomic unit of a real-time, multiprocessor system.<br>
- * - single threads of execution which concurrently compete for resources.<br>
- * - a sequence of closely related computations which can execute concurrently<br>
- *   with other computational sequences. <br>
- *<br>
- * From RTEMS' perspective, a task is the smallest thread of execution which<br>
- * can compete on its own for system resources. A task is manifested by the<br>
- * existence of a task control block (TCB). <br>
- *<br>
- * @section ClassicTasksSecTaskControlBlock Task Control Block<br>
- *<br>
- * The Task Control Block (TCB) is an RTEMS defined data structure which<br>
- * contains all the information that is pertinent to the execution of a task.<br>
- * During system initialization, RTEMS reserves a TCB for each task configured.<br>
- * A TCB is allocated upon creation of the task and is returned to the TCB free<br>
- * list upon deletion of the task.<br>
- * <br>
- * The TCB's elements are modified as a result of system calls made by the<br>
- * application in response to external and internal stimuli. TCBs are the only<br>
- * RTEMS internal data structure that can be accessed by an application via<br>
- * user extension routines. The TCB contains a task's name, ID, current<br>
- * priority, current and starting states, execution mode, TCB user extension<br>
- * pointer, scheduling control structures, as well as data required by a<br>
- * blocked task.<br>
- *<br>
- * A task's context is stored in the TCB when a task switch occurs. When the<br>
- * task regains control of the processor, its context is restored from the TCB.<br>
- * When a task is restarted, the initial state of the task is restored from the<br>
- * starting context area in the task's TCB.<br>
- *<br>
- * @section ClassicTasksSecTaskStates Task States<br>
- *<br>
- * A task may exist in one of the following five states:<br>
- *<br>
- * - executing - Currently scheduled to the CPU<br>
- * - ready - May be scheduled to the CPU<br>
- * - blocked - Unable to be scheduled to the CPU<br>
- * - dormant - Created task that is not started<br>
- * - non-existent - Uncreated or deleted task<br>
- * <br>
- * An active task may occupy the executing, ready, blocked or dormant state,<br>
- * otherwise the task is considered non-existent. One or more tasks may be<br>
- * active in the system simultaneously. Multiple tasks communicate,<br>
- * synchronize, and compete for system resources with each other via system<br>
- * calls. The multiple tasks appear to execute in parallel, but actually each<br>
- * is dispatched to the CPU for periods of time determined by the RTEMS<br>
- * scheduling algorithm. The scheduling of a task is based on its current state<br>
- * and priority.<br>
- *<br>
- * @section ClassicTasksSecTaskPriority Task Priority<br>
- *<br>
- * A task's priority determines its importance in relation to the other tasks<br>
- * executing on the same processor. RTEMS supports 255 levels of priority<br>
- * ranging from 1 to 255. The data type rtems_task_priority() is used to store<br>
- * task priorities.<br>
- *<br>
- * Tasks of numerically smaller priority values are more important tasks than<br>
- * tasks of numerically larger priority values. For example, a task at priority<br>
- * level 5 is of higher privilege than a task at priority level 10. There is no<br>
- * limit to the number of tasks assigned to the same priority.<br>
- *<br>
- * Each task has a priority associated with it at all times. The initial value<br>
- * of this priority is assigned at task creation time. The priority of a task<br>
- * may be changed at any subsequent time.<br>
- *<br>
- * Priorities are used by the scheduler to determine which ready task will be<br>
- * allowed to execute. In general, the higher the logical priority of a task,<br>
- * the more likely it is to receive processor execution time.<br>
- *<br>
- * @section ClassicTasksSecTaskMode Task Mode<br>
- *<br>
- * A task's execution mode is a combination of the following four components:<br>
- *<br>
- * - preemption<br>
- * - ASR processing<br>
- * - timeslicing<br>
- * - interrupt level <br>
- *<br>
- * It is used to modify RTEMS' scheduling process and to alter the execution<br>
- * environment of the task. The data type rtems_task_mode() is used to manage<br>
- * the task execution mode.<br>
- *<br>
- * The preemption component allows a task to determine when control of the<br>
- * processor is relinquished. If preemption is disabled (@c<br>
- * RTEMS_NO_PREEMPT), the task will retain control of the<br>
- * processor as long as it is in the executing state -- even if a higher<br>
- * priority task is made ready. If preemption is enabled (@c RTEMS_PREEMPT)<br>
- * and a higher priority task is made ready, then the processor will be<br>
- * taken away from the current task immediately and given to the higher<br>
- * priority task.<br>
- *<br>
- * The timeslicing component is used by the RTEMS scheduler to determine how<br>
- * the processor is allocated to tasks of equal priority. If timeslicing is<br>
- * enabled (@c RTEMS_TIMESLICE), then RTEMS will limit the amount of time the<br>
- * task can execute before the processor is allocated to another ready task of<br>
- * equal priority. The length of the timeslice is application dependent and<br>
- * specified in the Configuration Table. If timeslicing is disabled (@c<br>
- * RTEMS_NO_TIMESLICE), then the task will be allowed to<br>
- * execute until a task of higher priority is made ready. If @c<br>
- * RTEMS_NO_PREEMPT is selected, then the timeslicing component is ignored by<br>
- * the scheduler.<br>
- *<br>
- * The asynchronous signal processing component is used to determine when<br>
- * received signals are to be processed by the task. If signal processing is<br>
- * enabled (@c RTEMS_ASR), then signals sent to the task will be processed<br>
- * the next time the task executes. If signal processing is disabled (@c<br>
- * RTEMS_NO_ASR), then all signals received by the task will<br>
- * remain posted until signal processing is enabled. This component affects<br>
- * only tasks which have established a routine to process asynchronous signals.<br>
- *<br>
- * The interrupt level component is used to determine which interrupts will be<br>
- * enabled when the task is executing. @c RTEMS_INTERRUPT_LEVEL(n) specifies<br>
- * that the task will execute at interrupt level n.<br>
- *<br>
- * - @ref RTEMS_PREEMPT - enable preemption (default)<br>
- * - @ref RTEMS_NO_PREEMPT - disable preemption<br>
- * - @ref RTEMS_NO_TIMESLICE - disable timeslicing (default)<br>
- * - @ref RTEMS_TIMESLICE - enable timeslicing<br>
- * - @ref RTEMS_ASR - enable ASR processing (default)<br>
- * - @ref RTEMS_NO_ASR - disable ASR processing<br>
- * - @ref RTEMS_INTERRUPT_LEVEL(0) - enable all interrupts (default)<br>
- * - @ref RTEMS_INTERRUPT_LEVEL(n) - execute at interrupt level n<br>
- *<br>
- * The set of default modes may be selected by specifying the @ref<br>
- * RTEMS_DEFAULT_MODES constant.<br>
- *<br>
- * @section ClassicTasksSecAccessingTaskArguments Accessing Task Arguments<br>
- *<br>
- * All RTEMS tasks are invoked with a single argument which is specified when<br>
- * they are started or restarted. The argument is commonly used to communicate<br>
- * startup information to the task. The simplest manner in which to define a<br>
- * task which accesses it argument is:<br>
- *<br>
- * @code<br>
- *  rtems_task user_task(<br>
- *     rtems_task_argument argument<br>
- *  );<br>
- * @endcode<br>
- *<br>
- * Application tasks requiring more information may view this single argument<br>
- * as an index into an array of parameter blocks.<br>
- *<br>
- * @section ClassicTasksSecFloatingPointConsiderations Floating Point Considerations<br>
- *<br>
- * Creating a task with the @ref RTEMS_FLOATING_POINT attribute flag results in<br>
- * additional memory being allocated for the TCB to store the state of the<br>
- * numeric coprocessor during task switches. This additional memory is NOT<br>
- * allocated for @ref RTEMS_NO_FLOATING_POINT tasks. Saving and restoring the<br>
- * context of a @c RTEMS_FLOATING_POINT task takes longer than that of a @c<br>
- * RTEMS_NO_FLOATING_POINT task because of the relatively large amount of time<br>
- * required for the numeric coprocessor to save or restore its computational<br>
- * state.<br>
- *<br>
- * Since RTEMS was designed specifically for embedded military applications<br>
- * which are floating point intensive, the executive is optimized to avoid<br>
- * unnecessarily saving and restoring the state of the numeric coprocessor. The<br>
- * state of the numeric coprocessor is only saved when a @c<br>
- * RTEMS_FLOATING_POINT task is dispatched and that task was not the last task<br>
- * to utilize the coprocessor. In a system with only one @c<br>
- * RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will never<br>
- * be saved or restored.<br>
- *<br>
- * Although the overhead imposed by @c RTEMS_FLOATING_POINT tasks is minimal,<br>
- * some applications may wish to completely avoid the overhead associated with<br>
- * @c RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor. By<br>
- * preventing a task from being preempted while performing a sequence of<br>
- * floating point operations, a @c RTEMS_NO_FLOATING_POINT task can utilize<br>
- * the numeric coprocessor without incurring the overhead of a @c<br>
- * RTEMS_FLOATING_POINT context switch. This approach also avoids the<br>
- * allocation of a floating point context area. However, if this approach is<br>
- * taken by the application designer, NO tasks should be created as @c<br>
- * RTEMS_FLOATING_POINT tasks.  Otherwise, the floating point context will not<br>
- * be correctly maintained because RTEMS assumes that the state of the numeric<br>
- * coprocessor will not be altered by @c RTEMS_NO_FLOATING_POINT tasks.<br>
- *<br>
- * If the supported processor type does not have hardware floating capabilities<br>
- * or a standard numeric coprocessor, RTEMS will not provide built-in support<br>
- * for hardware floating point on that processor. In this case, all tasks are<br>
- * considered @c RTEMS_NO_FLOATING_POINT whether created as @c<br>
- * RTEMS_FLOATING_POINT or @c RTEMS_NO_FLOATING_POINT tasks. A floating point<br>
- * emulation software library must be utilized for floating point operations.<br>
- *<br>
- * On some processors, it is possible to disable the floating point unit<br>
- * dynamically. If this capability is supported by the target processor, then<br>
- * RTEMS will utilize this capability to enable the floating point unit only<br>
- * for tasks which are created with the @c RTEMS_FLOATING_POINT attribute.<br>
- * The consequence of a @c RTEMS_NO_FLOATING_POINT task attempting to access<br>
- * the floating point unit is CPU dependent but will generally result in an<br>
- * exception condition.<br>
- *<br>
- * @section ClassicTasksSecPerTaskVariables Per Task Variables<br>
- *<br>
- * Per task variables are no longer available.  In particular the<br>
- * rtems_task_variable_add(), rtems_task_variable_get() and<br>
- * rtems_task_variable_delete() functions are neither declared nor defined<br>
- * anymore.  Use thread local storage or POSIX Keys instead.<br>
- *<br>
- * @section ClassicTasksSecBuildingTaskAttributeSet Building a Task Attribute Set<br>
- *<br>
- * In general, an attribute set is built by a bitwise OR of the desired<br>
- * components. The set of valid task attribute components is listed below:<br>
- *<br>
- * - @ref RTEMS_NO_FLOATING_POINT - does not use coprocessor (default)<br>
- * - @ref RTEMS_FLOATING_POINT - uses numeric coprocessor<br>
- * - @ref RTEMS_LOCAL - local task (default)<br>
- * - @ref RTEMS_GLOBAL - global task <br>
- *<br>
- * Attribute values are specifically designed to be mutually exclusive,<br>
- * therefore bitwise OR and addition operations are equivalent as long as each<br>
- * attribute appears exactly once in the component list. A component listed as<br>
- * a default is not required to appear in the component list, although it is a<br>
- * good programming practice to specify default components. If all defaults are<br>
- * desired, then @ref RTEMS_DEFAULT_ATTRIBUTES should be used.  This example<br>
- * demonstrates the attribute_set parameter needed to create a local task which<br>
- * utilizes the numeric coprocessor. The attribute_set parameter could be @c<br>
- * RTEMS_FLOATING_POINT or @c RTEMS_LOCAL | @c RTEMS_FLOATING_POINT. The<br>
- * attribute_set parameter can be set to @c RTEMS_FLOATING_POINT because @c<br>
- * RTEMS_LOCAL is the default for all created tasks. If the task were global<br>
- * and used the numeric coprocessor, then the attribute_set parameter would be<br>
- * @c RTEMS_GLOBAL | @c RTEMS_FLOATING_POINT.<br>
- *<br>
- * @section ClassicTasksSecBuildingModeAndMask Building a Mode and Mask<br>
- *<br>
- * In general, a mode and its corresponding mask is built by a bitwise OR of<br>
- * the desired components. The set of valid mode constants and each mode's<br>
- * corresponding mask constant is listed below:<br>
- *<br>
- * <table><br>
- * <tr><th>Mode Constant</th><th>Mask Constant</th><th>Description</th></tr><br>
- * <tr><td>@ref RTEMS_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>enables preemption</td></tr><br>
- * <tr><td>@ref RTEMS_NO_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>disables preemption</td></tr><br>
- * <tr><td>@ref RTEMS_NO_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>disables timeslicing</td></tr><br>
- * <tr><td>@ref RTEMS_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>enables timeslicing</td></tr><br>
- * <tr><td>@ref RTEMS_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>enables ASR processing</td></tr><br>
- * <tr><td>@ref RTEMS_NO_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>disables ASR processing</td></tr><br>
- * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(0)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>enables all interrupts</td></tr><br>
- * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(n)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>sets interrupts level n</td></tr><br>
- * </table><br>
- * <br>
- * Mode values are specifically designed to be mutually exclusive, therefore<br>
- * bitwise OR and addition operations are equivalent as long as each mode<br>
- * appears exactly once in the component list. A mode component listed as a<br>
- * default is not required to appear in the mode component list, although it is<br>
- * a good programming practice to specify default components. If all defaults<br>
- * are desired, the mode @ref RTEMS_DEFAULT_MODES and the mask @ref<br>
- * RTEMS_ALL_MODE_MASKS should be used.<br>
- * <br>
- * The following example demonstrates the mode and mask parameters used with<br>
- * the rtems_task_mode() directive to place a task at interrupt level 3 and<br>
- * make it non-preemptible. The mode should be set to @c<br>
- * RTEMS_INTERRUPT_LEVEL(3) | @c RTEMS_NO_PREEMPT to indicate the desired<br>
- * preemption mode and interrupt level, while the mask parameter should be set<br>
- * to @c RTEMS_INTERRUPT_MASK | @c RTEMS_PREEMPT_MASK to indicate that<br>
- * the calling task's interrupt level and preemption mode are being altered.<br>
+ * The Real-Time Executive for Multiprocessor Systems (RTEMS) is a<br>
+ * multi-threaded, single address-space, real-time operating system with no<br>
+ * kernel-space/user-space separation.  It is capable to operate in an SMP<br>
+ * configuration providing a state of the art feature set.<br>
+ *<br>
+ * RTEMS is licensed under a [modified GPL 2.0 or later license with an<br>
+ * exception for static linking](<a href="https://git.rtems.org/rtems/tree/LICENSE" rel="noreferrer" target="_blank">https://git.rtems.org/rtems/tree/LICENSE</a>>).<br>
+ * It exposes no license requirements on application code.  The third-party<br>
+ * software used and distributed by RTEMS which may be linked to the<br>
+ * application is licensed under permissive open source licenses.  Everything<br>
+ * necessary to build RTEMS applications is available as open source software.<br>
+ * This makes you completely vendor independent.<br>
+ *<br>
+ * The goal is to use the [BSD 2-Clause<br>
+ * license](<a href="https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause" rel="noreferrer" target="_blank">https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause</a>) for new code<br>
+ * or code those copyright holder agreed to a license change, see<br>
+ * [#3053](<a href="https://devel.rtems.org/ticket/3053" rel="noreferrer" target="_blank">https://devel.rtems.org/ticket/3053</a>) for the details.<br></blockquote><div><br></div><div>This is true but out of date. The bulk of the target and BSP independent code</div><div>is BSD-2 and we state that first. There are older submissions -- primarily around</div><div>BSPs and a couple of architectures where GPL code is present. </div><div><br></div><div>We state now that we are BSD-2 with remnants of GPLv2 + exception and will</div><div>NOT accept code under the old license.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+ *<br>
+ * RTEMS provides the following basic feature set:<br>
+ *<br>
+ * - @ref RTEMSAPI<br>
+ *<br>
+ *     - POSIX with<br>
+ *       [pthreads](<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html" rel="noreferrer" target="_blank">http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html</a>)<br>
+ *       (enables a broad range of standard software to run on RTEMS)<br>
+ *<br>
+ *     - @ref RTEMSAPIClassic<br>
+ *<br>
+ *     - C11 (including<br>
+ *       [thread](<a href="https://en.cppreference.com/w/c/thread" rel="noreferrer" target="_blank">https://en.cppreference.com/w/c/thread</a>) support)<br>
+ *<br>
+ *     - C++11 (including<br>
+ *       [thread](<a href="https://en.cppreference.com/w/cpp/thread" rel="noreferrer" target="_blank">https://en.cppreference.com/w/cpp/thread</a>>) support)<br>
+ *<br>
+ *     - Newlib and GCC internal<br>
+ *<br>
+ * - Programming languages<br>
+ *<br>
+ *     - C/C++/OpenMP (RTEMS Source Builder, RSB)<br>
+ *<br>
+ *     - Ada (RSB, ``--with-ada``)<br>
+ *<br>
+ *     - Erlang<br>
+ *<br>
+ *     - Fortran (RSB, ``--with-fortran``)<br>
+ *<br>
+ *     - Python and MicroPython<br>
+ *<br>
+ * - Parallel languages<br>
+ *<br>
+ *     - [Embedded Multicore Building Blocks](<a href="https://embb.io/" rel="noreferrer" target="_blank">https://embb.io/</a>)<br>
+ *<br>
+ *     - [OpenMP](<a href="https://www.openmp.org/" rel="noreferrer" target="_blank">https://www.openmp.org/</a>)<br>
+ *<br>
+ * - Thread synchronization and communication<br>
+ *<br>
+ *     - Mutexes with and without locking protocols<br>
+ *<br>
+ *     - Counting semaphores<br>
+ *<br>
+ *     - Binary semaphores<br>
+ *<br>
+ *     - Condition variables<br>
+ *<br>
+ *     - Events<br>
+ *<br>
+ *     - Message queues<br>
+ *<br>
+ *     - Barriers<br>
+ *<br>
+ *     - [Futex](@ref RTEMSScoreFutex) (used by OpenMP barriers)<br>
+ *<br>
+ *     - Epoch Based Reclamation (libbsd)<br>
+ *<br>
+ * - Locking protocols<br>
+ *<br>
+ *     - Transitive Priority Inheritance<br>
+ *<br>
+ *     - OMIP (SMP feature)<br>
+ *<br>
+ *     - Priority Ceiling<br>
+ *<br>
+ *     - MrsP (SMP feature)<br>
+ *<br>
+ * - Scalable timer and timeout support<br>
+ *<br>
+ * - Lock-free timestamps (FreeBSD timecounters)<br>
+ *<br>
+ * - Responsive interrupt management<br>
+ *<br>
+ * - C11/C++11 Thread-Local Storage (TLS)<br>
+ *<br>
+ * - Link-time configurable schedulers<br>
+ *<br>
+ *     - Fixed-priority<br>
+ *<br>
+ *     - Job-level fixed-priority (EDF)<br>
+ *<br>
+ *     - Constant Bandwidth Server (experimental)<br>
+ *<br>
+ * - Clustered scheduling (SMP feature)<br>
+ *<br>
+ *     - Flexible link-time configuration<br>
+ *<br>
+ *     - Job-level fixed-priority scheduler (EDF) with support for one-to-one<br>
+ *        and one-to-all thread to processor affinities (default SMP scheduler)<br>
+ *<br>
+ *     - Fixed-priority scheduler<br>
+ *<br>
+ *     - Proof-of-concept strong APA scheduler<br>
+ *<br>
+ * - Focus on link-time application-specific configuration<br>
+ *<br>
+ * - Linker-set based initialization (similar to global C++ constructors)<br>
+ *<br>
+ * - Operating system uses fine-grained locking (SMP feature)<br>
+ *<br>
+ * - Dynamic memory allocators<br>
+ *<br>
+ *     - First-fit (default)<br>
+ *<br>
+ *     - Universal Memory Allocator<br>
+ *       ([UMA](<a href="https://www.freebsd.org/cgi/man.cgi?query=uma&sektion=9" rel="noreferrer" target="_blank">https://www.freebsd.org/cgi/man.cgi?query=uma&sektion=9</a>),<br>
+ *       libbsd)<br>
+ *<br>
+ * - File systems<br>
+ *<br>
+ *     - IMFS<br>
+ *<br>
+ *     - FAT<br>
+ *<br>
+ *     - RFS<br>
+ *<br>
+ *     - NFSv2<br>
+ *<br>
+ *     - JFFS2 (NOR flashes)<br>
+ *<br>
+ *     - [YAFFS2](<a href="https://git.rtems.org/sebh/rtems-yaffs2.git/" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-yaffs2.git/</a>)<br>
+ *       (NAND flashes, GPL or commercial license required)<br>
+ *<br>
+ * - Device drivers<br>
+ *<br>
+ *     - Termios (serial interfaces)<br>
+ *<br>
+ *     - I2C (Linux user-space API compatible)<br>
+ *<br>
+ *     - SPI (Linux user-space API compatible)<br>
+ *<br>
+ *     - Network stacks (legacy, libbsd, lwIP)<br>
+ *<br>
+ *     - USB stack (libbsd)<br>
+ *<br>
+ *     - SD/MMC card stack (libbsd)<br>
+ *<br>
+ *     - Framebuffer (Linux user-space API compatible, Qt)<br>
+ *<br>
+ *     - Application runs in kernel-space and can access hardware directly<br>
+ *<br>
+ * - [libbsd](<a href="https://git.rtems.org/rtems-libbsd/" rel="noreferrer" target="_blank">https://git.rtems.org/rtems-libbsd/</a>)<br>
+ *<br>
+ *     - Port of FreeBSD user-space and kernel-space components to RTEMS<br>
+ *<br>
+ *     - Easy access to FreeBSD software for RTEMS<br>
+ *<br>
+ *     - Support to stay in synchronization with FreeBSD<br>
  */<br>
-<br>
- /**<br>
-  * @defgroup LocalPackages Local Packages<br>
-  * <br>
-  * @ingroup RTEMSAPIClassic<br>
-  *<br>
-  * @brief Local packages.<br>
-  */<br>
-- <br>
2.35.3<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>