[PATCH] doxygen: Replace and move main page

[Joel Sherrill]

Sorry. Not sure how this kept slipping through the cracks.  The 13
September ping did coincide with me being on a trip and then sick.

This is the only revision I see in my inbox. There is an email which says
"how about this version?" but I don't see anything on it.

A few comments inline.

On Fri, Jul 28, 2023 at 9:37 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> Replace the main page with a high level description of the RTEMS feature
> set similar to:
>
> https://docs.rtems.org/branches/master/user/overview/index.html#features
>
> The replaced content can be found in the RTEMS Classic API Guide:
>
> https://docs.rtems.org/branches/master/c-user/overview.html
>
> https://docs.rtems.org/branches/master/c-user/key_concepts.html
>
> Update #3705.
> ---
> v2:
>
> * Add OAR copyright.
>
> * Move to cpukit/doxygen/mainpage.h
>
> * Not not install
>
>  cpukit/doxygen/mainpage.h             | 204 ++++++
>  cpukit/include/rtems/rtems/mainpage.h | 951 --------------------------
>  spec/build/cpukit/librtemscpu.yml     |   1 -
>  3 files changed, 204 insertions(+), 952 deletions(-)
>  create mode 100644 cpukit/doxygen/mainpage.h
>  delete mode 100644 cpukit/include/rtems/rtems/mainpage.h
>
> diff --git a/cpukit/doxygen/mainpage.h b/cpukit/doxygen/mainpage.h
> new file mode 100644
> index 0000000000..ce341e0ffd
> --- /dev/null
> +++ b/cpukit/doxygen/mainpage.h
> @@ -0,0 +1,204 @@
> +/* SPDX-License-Identifier: BSD-2-Clause */
> +
> +/**
> + * @file
> + *
> + * @ingroup RTEMSImplDoxygen
> + *
> + * @brief This file exists to provide a top level description of RTEMS for
> + *   Doxygen.
> + */
> +
> +/*
> + * Copyright (C) 2021 embedded brains GmbH & Co. KG
> + * Copyright (C) 1989, 2014 On-Line Applications Research Corporation
> (OAR)
> + *
> + * Redistribution and use in source and binary forms, with or without
> + * modification, are permitted provided that the following conditions
> + * are met:
> + * 1. Redistributions of source code must retain the above copyright
> + *    notice, this list of conditions and the following disclaimer.
> + * 2. Redistributions in binary form must reproduce the above copyright
> + *    notice, this list of conditions and the following disclaimer in the
> + *    documentation and/or other materials provided with the distribution.
> + *
> + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
> "AS IS"
> + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
> THE
> + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
> PURPOSE
> + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
> BE
> + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
> + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
> + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
> BUSINESS
> + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
> + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
> + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
> THE
> + * POSSIBILITY OF SUCH DAMAGE.
> + */
> +
> +/**
> + * @mainpage
> + *
> + * The Real-Time Executive for Multiprocessor Systems (RTEMS) is a
> + * multi-threaded, single address-space, real-time operating system with
> no
> + * kernel-space/user-space separation.  It is capable to operate in an SMP
> + * configuration providing a state of the art feature set.
> + *
> + * RTEMS and all third-party software distributed with RTEMS which may be
> + * linked to the application is licensed under permissive open source
> licenses.
> + * This means that the licenses do not properagate to the application
> software.
>

properagate -> propagate


> + * Most of the original RTEMS code is now under the [BSD 2-Clause
> + * license](https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause).
> Legacy
>

GPLv2 does not imply legacy. Some code in RTEMS is under a legacy license.


> + * code of RTEMS is under a [modified GPL 2.0 or later license with an
> + * exception for static linking](https://git.rtems.org/rtems/tree/LICENSE
> >).
> + * It exposes no license requirements on application code.  Everything
> + * necessary to build RTEMS applications is available as open source
> software.
> + * This makes you completely vendor independent.
> + *
> + * RTEMS provides the following basic feature set:
> + *
> + * - @ref RTEMSAPI
> + *
> + *     - POSIX with
> + *       [pthreads](
> http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html)
> + *       (enables a broad range of standard software to run on RTEMS)
> + *
> + *     - @ref RTEMSAPIClassic
> + *
> + *     - C11 (including
> + *       [thread](https://en.cppreference.com/w/c/thread) support)
> + *
> + *     - C++11 (including
> + *       [thread](https://en.cppreference.com/w/cpp/thread>) support)
> + *
> + *     - Newlib and GCC internal
> + *
> + * - Programming languages
> + *
> + *     - C/C++/OpenMP (RTEMS Source Builder, RSB)
> + *
> + *     - Ada (RSB, ``--with-ada``)
> + *
> + *     - Erlang
> + *
> + *     - Fortran (RSB, ``--with-fortran``)
>

FWIW I have a Fortran RTEMS hello world and need to add it to
rtems-examples.


> + *
> + *     - Python and MicroPython
> + *
> + * - Parallel languages
> + *
> + *     - [Embedded Multicore Building Blocks](https://embb.io/)
> + *
> + *     - [OpenMP](https://www.openmp.org/)
> + *
> + * - Thread synchronization and communication
> + *
> + *     - Mutexes with and without locking protocols
> + *
> + *     - Counting semaphores
> + *
> + *     - Binary semaphores
> + *
> + *     - Condition variables
> + *
> + *     - Events
> + *
> + *     - Message queues
> + *
> + *     - Barriers
> + *
> + *     - [Futex](@ref RTEMSScoreFutex) (used by OpenMP barriers)
> + *
> + *     - Epoch Based Reclamation (libbsd)
> + *
> + * - Locking protocols
> + *
> + *     - Transitive Priority Inheritance
> + *
> + *     - OMIP (SMP feature)
> + *
> + *     - Priority Ceiling
> + *
> + *     - MrsP (SMP feature)
> + *
> + * - Scalable timer and timeout support
> + *
> + * - Lock-free timestamps (FreeBSD timecounters)
> + *
> + * - Responsive interrupt management
> + *
> + * - C11/C++11 Thread-Local Storage (TLS)
>

TLS is also in newer versions of both languages so how about rephrasing to
include C17, C++14, etc


> + *
> + * - Link-time configurable schedulers
> + *
> + *     - Fixed-priority
> + *
> + *     - Job-level fixed-priority (EDF)
> + *
> + *     - Constant Bandwidth Server (experimental)
> + *
> + * - Clustered scheduling (SMP feature)
> + *
> + *     - Flexible link-time configuration
> + *
> + *     - Job-level fixed-priority scheduler (EDF) with support for
> one-to-one
> + *        and one-to-all thread to processor affinities (default SMP
> scheduler)
> + *
> + *     - Fixed-priority scheduler
> + *
> + *     - Proof-of-concept strong APA scheduler
> + *
> + * - Focus on link-time application-specific configuration
> + *
> + * - Linker-set based initialization (similar to global C++ constructors)
> + *
> + * - Operating system uses fine-grained locking (SMP feature)
> + *
> + * - Dynamic memory allocators
> + *
> + *     - First-fit (default)
> + *
> + *     - Universal Memory Allocator
> + *       ([UMA](https://www.freebsd.org/cgi/man.cgi?query=uma&sektion=9),
> + *       libbsd)
> + *
> + * - File systems
> + *
> + *     - IMFS
> + *
> + *     - FAT
> + *
> + *     - RFS
> + *
> + *     - NFSv2
>

NFSv4 in libbsd.


> + *
> + *     - JFFS2 (NOR flashes)
>

Kinsey just enabled NAND I think.


> + *
> + *     - [YAFFS2](https://git.rtems.org/sebh/rtems-yaffs2.git/)
> + *       (NAND flashes, GPL or commercial license required)
> + *
> + * - Device drivers
> + *
> + *     - Termios (serial interfaces)
> + *
> + *     - I2C (Linux user-space API compatible)
> + *
> + *     - SPI (Linux user-space API compatible)
> + *
> + *     - Network stacks (legacy, libbsd, lwIP)
> + *
> + *     - USB stack (libbsd)
> + *
> + *     - SD/MMC card stack (libbsd)
> + *
> + *     - Framebuffer (Linux user-space API compatible, Qt)
> + *
> + *     - Application runs in kernel-space and can access hardware directly
> + *
> + * - [libbsd](https://git.rtems.org/rtems-libbsd/)
> + *
> + *     - Port of FreeBSD user-space and kernel-space components to RTEMS
> + *
> + *     - Easy access to FreeBSD software for RTEMS
> + *
> + *     - Support to stay in synchronization with FreeBSD
>

Does lwip rate a bit like that?


> + */
> diff --git a/cpukit/include/rtems/rtems/mainpage.h
> b/cpukit/include/rtems/rtems/mainpage.h
> deleted file mode 100644
> index f168cc3395..0000000000
> --- a/cpukit/include/rtems/rtems/mainpage.h
> +++ /dev/null
> @@ -1,951 +0,0 @@
> -/* SPDX-License-Identifier: BSD-2-Clause */
> -
> -/**
> - * @file
> - *
> - * @ingroup RTEMSImplDoxygen
> - *
> - * @brief This file exists to provide a top level description of RTEMS for
> - *   Doxygen.
> - */
> -
> -/*
> - *  COPYRIGHT (c) 1989-2014.
> - *  On-Line Applications Research Corporation (OAR).
> - *
> - * Redistribution and use in source and binary forms, with or without
> - * modification, are permitted provided that the following conditions
> - * are met:
> - * 1. Redistributions of source code must retain the above copyright
> - *    notice, this list of conditions and the following disclaimer.
> - * 2. Redistributions in binary form must reproduce the above copyright
> - *    notice, this list of conditions and the following disclaimer in the
> - *    documentation and/or other materials provided with the distribution.
> - *
> - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
> "AS IS"
> - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
> THE
> - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
> PURPOSE
> - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
> BE
> - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
> - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
> - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
> BUSINESS
> - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
> - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
> - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
> THE
> - * POSSIBILITY OF SUCH DAMAGE.
> - */
> -
> -/**
> - * @mainpage
> - *
> - * The RTEMS real-time operating systems is a layered system with each of
> the
> - * public APIs implemented in terms of a common foundation layer called
> the
> - * SuperCore.  This is the Doxygen generated documentation for the RTEMS
> CPU
> - * Kit including the Classic API, POSIX API and SuperCore.
> - */
> -
> -/**
> - * @page RTEMSPreface RTEMS History and Introduction
> - *
> - * In recent years, the cost required to develop a software product has
> - * increased significantly while the target hardware costs have
> decreased. Now
> - * a larger portion of money is expended in developing, using, and
> maintaining
> - * software. The trend in computing costs is the complete dominance of
> software
> - * over hardware costs. Because of this, it is necessary that formal
> - * disciplines be established to increase the probability that software is
> - * characterized by a high degree of correctness, maintainability, and
> - * portability. In addition, these disciplines must promote practices
> that aid
> - * in the consistent and orderly development of a software system within
> - * schedule and budgetary constraints. To be effective, these disciplines
> must
> - * adopt standards which channel individual software efforts toward a
> common
> - * goal.
> - *
> - * The push for standards in the software development field has been met
> with
> - * various degrees of success. The Microprocessor Operating Systems
> Interfaces
> - * (MOSI) effort has experienced only limited success. As popular as the
> UNIX
> - * operating system has grown, the attempt to develop a standard interface
> - * definition to allow portable application development has only recently
> begun
> - * to produce the results needed in this area. Unfortunately, very little
> - * effort has been expended to provide standards addressing the needs of
> the
> - * real-time community. Several organizations have addressed this need
> during
> - * recent years.
> - *
> - * The Real Time Executive Interface Definition (RTEID) was developed by
> - * Motorola with technical input from Software Components Group. RTEID was
> - * adopted by the VMEbus International Trade Association (VITA) as a
> baseline
> - * draft for their proposed standard multiprocessor, real-time executive
> - * interface, Open Real-Time Kernel Interface Definition (ORKID). These
> two
> - * groups are currently working together with the IEEE P1003.4 committee
> to
> - * insure that the functionality of their proposed standards is adopted
> as the
> - * real-time extensions to POSIX.
> - *
> - * This emerging standard defines an interface for the development of
> real-time
> - * software to ease the writing of real-time application programs that are
> - * directly portable across multiple real-time executive implementations.
> This
> - * interface includes both the source code interfaces and run-time
> behavior as
> - * seen by a real-time application. It does not include the details of
> how a
> - * kernel implements these functions. The standard's goal is to serve as a
> - * complete definition of external interfaces so that application code
> that
> - * conforms to these interfaces will execute properly in all real-time
> - * executive environments. With the use of a standards compliant
> executive,
> - * routines that acquire memory blocks, create and manage message queues,
> - * establish and use semaphores, and send and receive signals need not be
> - * redeveloped for a different real-time environment as long as the new
> - * environment is compliant with the standard. Software developers need
> only
> - * concentrate on the hardware dependencies of the real-time system.
> - * Furthermore, most hardware dependencies for real-time applications can
> be
> - * localized to the device drivers.
> - *
> - * A compliant executive provides simple and flexible real-time
> - * multiprocessing. It easily lends itself to both tightly-coupled and
> - * loosely-coupled configurations (depending on the system hardware
> - * configuration). Objects such as tasks, queues, events, signals,
> semaphores,
> - * and memory blocks can be designated as global objects and accessed by
> any
> - * task regardless of which processor the object and the accessing task
> reside.
> - *
> - * The acceptance of a standard for real-time executives will produce the
> same
> - * advantages enjoyed from the push for UNIX standardization by AT&T's
> System V
> - * Interface Definition and IEEE's POSIX efforts. A compliant
> multiprocessing
> - * executive will allow close coupling between UNIX systems and real-time
> - * executives to provide the many benefits of the UNIX development
> environment
> - * to be applied to real-time software development. Together they provide
> the
> - * necessary laboratory environment to implement real-time, distributed,
> - * embedded systems using a wide variety of computer architectures.
> - *
> - * A study was completed in 1988, within the Research, Development, and
> - * Engineering Center, U.S. Army Missile Command, which compared the
> various
> - * aspects of the Ada programming language as they related to the
> application
> - * of Ada code in distributed and/or multiple processing systems. Several
> - * critical conclusions were derived from the study. These conclusions
> have a
> - * major impact on the way the Army develops application software for
> embedded
> - * applications. These impacts apply to both in-house software
> development and
> - * contractor developed software.
> - *
> - * A conclusion of the analysis, which has been previously recognized by
> other
> - * agencies attempting to utilize Ada in a distributed or multiprocessing
> - * environment, is that the Ada programming language does not adequately
> - * support multiprocessing. Ada does provide a mechanism for
> multi-tasking,
> - * however, this capability exists only for a single processor system. The
> - * language also does not have inherent capabilities to access global
> named
> - * variables, flags or program code. These critical features are
> essential in
> - * order for data to be shared between processors. However, these
> drawbacks do
> - * have workarounds which are sometimes awkward and defeat the intent of
> - * software maintainability and portability goals.
> - *
> - * Another conclusion drawn from the analysis, was that the run time
> executives
> - * being delivered with the Ada compilers were too slow and inefficient
> to be
> - * used in modern missile systems. A run time executive is the core part
> of the
> - * run time system code, or operating system code, that controls task
> - * scheduling, input/output management and memory management.
> Traditionally,
> - * whenever efficient executive (also known as kernel) code was required
> by the
> - * application, the user developed in-house software. This software was
> usually
> - * written in assembly language for optimization.
> - *
> - * Because of this shortcoming in the Ada programming language, software
> - * developers in research and development and contractors for project
> managed
> - * systems, are mandated by technology to purchase and utilize
> off-the-shelf
> - * third party kernel code. The contractor, and eventually the
> Government, must
> - * pay a licensing fee for every copy of the kernel code used in an
> embedded
> - * system.
> - *
> - * The main drawback to this development environment is that the
> Government
> - * does not own, nor has the right to modify code contained within the
> kernel.
> - * V&V techniques in this situation are more difficult than if the
> complete
> - * source code were available. Responsibility for system failures due to
> faulty
> - * software is yet another area to be resolved under this environment.
> - *
> - * The Guidance and Control Directorate began a software development
> effort to
> - * address these problems. A project to develop an experimental run time
> kernel
> - * was begun that will eliminate the major drawbacks of the Ada
> programming
> - * language mentioned above. The Real Time Executive for Multiprocessor
> Systems
> - * (RTEMS) provides full capabilities for management of tasks, interrupts,
> - * time, and multiple processors in addition to those features typical of
> - * generic operating systems. The code is Government owned, so no
> licensing
> - * fees are necessary. RTEMS has been implemented in both the Ada and C
> - * programming languages. It has been ported to the following processor
> - * families:
> - *
> - * - Altera NIOS II
> - * - Analog Devices Blackfin
> - * - ARM
> - * - Freescale (formerly Motorola) MC68xxx
> - * - Freescale (formerly Motorola) MC683xx
> - * - Freescale (formerly Motorola) ColdFire
> - * - Intel i386 and above
> - * - Lattice Semiconductor LM32
> - * - MIPS
> - * - PowerPC
> - * - Renesas (formerly Hitachi) SuperH
> - * - Renesas (formerly Hitachi) H8/300
> - * - SPARC
> - * - Texas Instruments C3x/C4x
> - * - UNIX


If this list still exists somewhere, it is out of date.

Nothing below here.

>
> - *
> - * Support for other processor families, including RISC, CISC, and DSP, is
> - * planned. Since almost all of RTEMS is written in a high level language,
> - * ports to additional processor families require minimal effort.
> - *
> - * RTEMS multiprocessor support is capable of handling either homogeneous
> or
> - * heterogeneous systems. The kernel automatically compensates for
> - * architectural differences (byte swapping, etc.) between processors.
> This
> - * allows a much easier transition from one processor family to another
> without
> - * a major system redesign.
> - *
> - * Since the proposed standards are still in draft form, RTEMS cannot and
> does
> - * not claim compliance. However, the status of the standard is being
> carefully
> - * monitored to guarantee that RTEMS provides the functionality specified
> in
> - * the standard. Once approved, RTEMS will be made compliant.
> - */
> -
> -/**
> - * @page RTEMSOverview RTEMS Overview
> - *
> - * @section RTEMSOverviewSecIntroduction Introduction
> - *
> - * RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time
> - * executive (kernel) which provides a high performance environment for
> - * embedded military applications including the following features:
> - *
> - * - multitasking capabilities
> - * - homogeneous and heterogeneous multiprocessor systems
> - * - event-driven, priority-based, preemptive scheduling
> - * - optional rate monotonic scheduling
> - * - intertask communication and synchronization
> - * - priority inheritance
> - * - responsive interrupt management
> - * - dynamic memory allocation
> - * - high level of user configurability
> - *
> - * This manual describes the usage of RTEMS for applications written in
> the C
> - * programming language. Those implementation details that are processor
> - * dependent are provided in the Applications Supplement documents. A
> - * supplement document which addresses specific architectural issues that
> - * affect RTEMS is provided for each processor type that is supported.
> - *
> - * @section RTEMSOverviewSecRealtimeApplicationSystems Real-time
> Application Systems
> - *
> - * Real-time application systems are a special class of computer
> applications.
> - * They have a complex set of characteristics that distinguish them from
> other
> - * software problems. Generally, they must adhere to more rigorous
> - * requirements. The correctness of the system depends not only on the
> results
> - * of computations, but also on the time at which the results are
> produced. The
> - * most important and complex characteristic of real-time application
> systems
> - * is that they must receive and respond to a set of external stimuli
> within
> - * rigid and critical time constraints referred to as deadlines. Systems
> can be
> - * buried by an avalanche of interdependent, asynchronous or cyclical
> event
> - * streams.
> - *
> - * Deadlines can be further characterized as either hard or soft based
> upon the
> - * value of the results when produced after the deadline has passed. A
> deadline
> - * is hard if the results have no value or if their use will result in a
> - * catastrophic event. In contrast, results which are produced after a
> soft
> - * deadline may have some value.
> - *
> - * Another distinguishing requirement of real-time application systems is
> the
> - * ability to coordinate or manage a large number of concurrent
> activities.
> - * Since software is a synchronous entity, this presents special
> problems. One
> - * instruction follows another in a repeating synchronous cycle. Even
> though
> - * mechanisms have been developed to allow for the processing of external
> - * asynchronous events, the software design efforts required to process
> and
> - * manage these events and tasks are growing more complicated.
> - *
> - * The design process is complicated further by spreading this activity
> over a
> - * set of processors instead of a single processor. The challenges
> associated
> - * with designing and building real-time application systems become very
> - * complex when multiple processors are involved. New requirements such as
> - * interprocessor communication channels and global resources that must be
> - * shared between competing processors are introduced. The ramifications
> of
> - * multiple processors complicate each and every characteristic of a
> real-time
> - * system.
> - *
> - * @section RTEMSOverviewSecRealtimeExecutive Real-time Executive
> - *
> - * Fortunately, real-time operating systems or real-time executives serve
> as a
> - * cornerstone on which to build the application system. A real-time
> - * multitasking executive allows an application to be cast into a set of
> - * logical, autonomous processes or tasks which become quite manageable.
> Each
> - * task is internally synchronous, but different tasks execute
> independently,
> - * resulting in an asynchronous processing stream. Tasks can be
> dynamically
> - * paused for many reasons resulting in a different task being allowed to
> - * execute for a period of time. The executive also provides an interface
> to
> - * other system components such as interrupt handlers and device drivers.
> - * System components may request the executive to allocate and coordinate
> - * resources, and to wait for and trigger synchronizing conditions. The
> - * executive system calls effectively extend the CPU instruction set to
> support
> - * efficient multitasking. By causing tasks to travel through well-defined
> - * state transitions, system calls permit an application to demand-switch
> - * between tasks in response to real-time events.
> - *
> - * By proper grouping of responses to stimuli into separate tasks, a
> system can
> - * now asynchronously switch between independent streams of execution,
> directly
> - * responding to external stimuli as they occur. This allows the system
> design
> - * to meet critical performance specifications which are typically
> measured by
> - * guaranteed response time and transaction throughput. The multiprocessor
> - * extensions of RTEMS provide the features necessary to manage the extra
> - * requirements introduced by a system distributed across several
> processors.
> - * It removes the physical barriers of processor boundaries from the
> world of
> - * the system designer, enabling more critical aspects of the system to
> receive
> - * the required attention. Such a system, based on an efficient real-time,
> - * multiprocessor executive, is a more realistic model of the outside
> world or
> - * environment for which it is designed. As a result, the system will
> always be
> - * more logical, efficient, and reliable.
> - *
> - * By using the directives provided by RTEMS, the real-time applications
> - * developer is freed from the problem of controlling and synchronizing
> - * multiple tasks and processors. In addition, one need not develop, test,
> - * debug, and document routines to manage memory, pass messages, or
> provide
> - * mutual exclusion. The developer is then able to concentrate solely on
> the
> - * application. By using standard software components, the time and cost
> - * required to develop sophisticated real-time applications is
> significantly
> - * reduced.
> - *
> - * @section RTEMSOverviewSecApplicationArchitecture RTEMS Application
> Architecture
> - *
> - * One important design goal of RTEMS was to provide a bridge between two
> - * critical layers of typical real-time systems. As shown in the following
> - * figure, RTEMS serves as a buffer between the project dependent
> application
> - * code and the target hardware. Most hardware dependencies for real-time
> - * applications can be localized to the low level device drivers.
> - *
> - * @todo Image RTEMS Application Architecture
> - *
> - * The RTEMS I/O interface manager provides an efficient tool for
> incorporating
> - * these hardware dependencies into the system while simultaneously
> providing a
> - * general mechanism to the application code that accesses them. A well
> - * designed real-time system can benefit from this architecture by
> building a
> - * rich library of standard application components which can be used
> repeatedly
> - * in other real-time projects.
> - *
> - * @section RTEMSOverviewSecInternalArchitecture RTEMS Internal
> Architecture
> - *
> - * RTEMS can be viewed as a set of layered components that work in
> harmony to
> - * provide a set of services to a real-time application system. The
> executive
> - * interface presented to the application is formed by grouping
> directives into
> - * logical sets called resource managers. Functions utilized by multiple
> - * managers such as scheduling, dispatching, and object management are
> provided
> - * in the executive core. The executive core depends on a small set of CPU
> - * dependent routines. Together these components provide a powerful run
> time
> - * environment that promotes the development of efficient real-time
> application
> - * systems. The following figure illustrates this organization:
> - *
> - * @todo Image RTEMS Architecture
> - *
> - * Subsequent chapters present a detailed description of the capabilities
> - * provided by each of the following RTEMS managers:
> - *
> - * - initialization
> - * - task
> - * - interrupt
> - * - clock
> - * - timer
> - * - semaphore
> - * - message
> - * - event
> - * - signal
> - * - partition
> - * - region
> - * - dual ported memory
> - * - I/O
> - * - fatal error
> - * - rate monotonic
> - * - user extensions
> - * - multiprocessing
> - *
> - * @section RTEMSOverviewSecUserCustomization User Customization and
> Extensibility
> - *
> - * As 32-bit microprocessors have decreased in cost, they have become
> - * increasingly common in a variety of embedded systems. A wide range of
> custom
> - * and general-purpose processor boards are based on various 32-bit
> - * processors. RTEMS was designed to make no assumptions concerning the
> - * characteristics of individual microprocessor families or of specific
> support
> - * hardware. In addition, RTEMS allows the system developer a high degree
> of
> - * freedom in customizing and extending its features.
> - *
> - * RTEMS assumes the existence of a supported microprocessor and
> sufficient
> - * memory for both RTEMS and the real-time application. Board dependent
> - * components such as clocks, interrupt controllers, or I/O devices can be
> - * easily integrated with RTEMS. The customization and extensibility
> features
> - * allow RTEMS to efficiently support as many environments as possible.
> - *
> - * @section RTEMSOverviewSecPortability Portability
> - *
> - * The issue of portability was the major factor in the creation of RTEMS.
> - * Since RTEMS is designed to isolate the hardware dependencies in the
> specific
> - * board support packages, the real-time application should be easily
> ported to
> - * any other processor. The use of RTEMS allows the development of
> real-time
> - * applications which can be completely independent of a particular
> - * microprocessor architecture.
> - *
> - * @section RTEMSOverviewSecMemoryRequirements Memory Requirements
> - *
> - * Since memory is a critical resource in many real-time embedded systems,
> - * RTEMS was specifically designed to automatically leave out all
> services that
> - * are not required from the run-time environment. Features such as
> networking,
> - * various filesystems, and many other features are completely optional.
> This
> - * allows the application designer the flexibility to tailor RTEMS to most
> - * efficiently meet system requirements while still satisfying even the
> most
> - * stringent memory constraints. As a result, the size of the RTEMS
> executive
> - * is application dependent.
> - *
> - * RTEMS requires RAM to manage each instance of an RTEMS object that is
> - * created. Thus the more RTEMS objects an application needs, the more
> memory
> - * that must be reserved. See Configuring a System Determining Memory
> - * Requirements for more details.
> - *
> - * @todo Link to Configuring a SystemDetermining Memory Requirements
> - *
> - * RTEMS utilizes memory for both code and data space. Although RTEMS'
> data
> - * space must be in RAM, its code space can be located in either ROM or
> RAM.
> - *
> - * @section RTEMSOverviewSecAudience Audience
> - *
> - * This manual was written for experienced real-time software developers.
> - * Although some background is provided, it is assumed that the reader is
> - * familiar with the concepts of task management as well as intertask
> - * communication and synchronization. Since directives, user related data
> - * structures, and examples are presented in C, a basic understanding of
> the C
> - * programming language is required to fully understand the material
> presented.
> - * However, because of the similarity of the Ada and C RTEMS
> implementations,
> - * users will find that the use and behavior of the two implementations
> is very
> - * similar. A working knowledge of the target processor is helpful in
> - * understanding some of RTEMS' features. A thorough understanding of the
> - * executive cannot be obtained without studying the entire manual
> because many
> - * of RTEMS' concepts and features are interrelated. Experienced RTEMS
> users
> - * will find that the manual organization facilitates its use as a
> reference
> - * document.
> - */
> -
> -/**
> - * @addtogroup RTEMSAPIClassic
> - *
> - * The facilities provided by RTEMS are built upon a foundation of very
> - * powerful concepts. These concepts must be understood before the
> application
> - * developer can efficiently utilize RTEMS. The purpose of this chapter
> is to
> - * familiarize one with these concepts.
> - *
> - * @section ClassicRTEMSSecObjects Objects
> - *
> - * RTEMS provides directives which can be used to dynamically create,
> delete,
> - * and manipulate a set of predefined object types. These types include
> tasks,
> - * message queues, semaphores, memory regions, memory partitions, timers,
> - * ports, and rate monotonic periods. The object-oriented nature of RTEMS
> - * encourages the creation of modular applications built upon re-usable
> - * "building block" routines.
> - *
> - * All objects are created on the local node as required by the
> application and
> - * have an RTEMS assigned ID. All objects have a user-assigned name.
> Although a
> - * relationship exists between an object's name and its RTEMS assigned
> ID, the
> - * name and ID are not identical. Object names are completely arbitrary
> and
> - * selected by the user as a meaningful "tag" which may commonly reflect
> the
> - * object's use in the application. Conversely, object IDs are designed to
> - * facilitate efficient object manipulation by the executive.
> - *
> - * @subsection ClassicRTEMSSubSecObjectNames Object Names
> - *
> - * An object name is an unsigned 32-bit entity associated with the
> - * object by the user. The data type @ref rtems_name is used to store
> object names.
> - *
> - * Although not required by RTEMS, object names are often composed of four
> - * ASCII characters which help identify that object. For example, a task
> which
> - * causes a light to blink might be called "LITE". The rtems_build_name()
> - * routine is provided to build an object name from four ASCII
> characters. The
> - * following example illustrates this:
> - *
> - * @code
> - * rtems_name my_name = rtems_build_name('L', 'I', 'T', 'E');
> - * @endcode
> - *
> - * However, it is not required that the application use ASCII characters
> to
> - * build object names. For example, if an application requires one-hundred
> - * tasks, it would be difficult to assign meaningful ASCII names to each
> task.
> - * A more convenient approach would be to name them the binary values one
> - * through one-hundred, respectively.
> - *
> - * RTEMS provides a helper routine, rtems_object_get_name(), which can be
> used to
> - * obtain the name of any RTEMS object using just its ID. This routine
> attempts
> - * to convert the name into a printable string.
> - *
> - * @subsection ClassicRTEMSSubSecObjectIdentifiers Object Identifiers
> - *
> - * An object ID is a unique unsigned integer value which uniquely
> identifies an
> - * object instance. Object IDs are passed as arguments to many directives
> in
> - * RTEMS and RTEMS translates the ID to an internal object pointer. The
> - * efficient manipulation of object IDs is critical to the performance of
> RTEMS
> - * services. Because of this, there are two object ID formats defined.
> Each
> - * target architecture specifies which format it will use. There is a
> 32-bit
> - * format which is used for most of the supported architectures and
> supports
> - * multiprocessor configurations. There is also a simpler 16-bit format
> which
> - * is appropriate for smaller target architectures and does not support
> - * multiprocessor configurations.
> - *
> - * @subsubsection ClassicRTEMSSubSec32BitObjectIdentifierFormat 32-Bit
> Object Identifier Format
> - *
> - * The 32-bit format for an object ID is composed of four parts: API,
> - * object class, node, and index. The data type @ref rtems_id is used to
> store
> - * object IDs.
> - *
> - * <table>
> - *   <tr>
> - *     <th>Bits</th>
> - *
>  <td>31</td><td>30</td><td>29</td><td>28</td><td>27</td><td>26</td><td>25</td><td>24</td>
> - *
>  <td>23</td><td>22</td><td>21</td><td>20</td><td>19</td><td>18</td><td>17</td><td>16</td>
> - *
>  <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td>
> - *
>  <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td>
> - *   </tr>
> - *   <tr>
> - *     <th>Contents</th>
> - *     <td colspan=5>Class</td><td colspan=3>API</td><td
> colspan=8>Node</td><td colspan=16>Object Index</td>
> - *   </tr>
> - * </table>
> - *
> - * The most significant five bits are the object class. The next three
> bits
> - * indicate the API to which the object class belongs. The next eight bits
> - * (16 .. 23) are the number of the node on which this object was
> created. The
> - * node number is always one (1) in a single processor system. The least
> - * significant 16-bits form an identifier within a particular object type.
> - * This identifier, called the object index, ranges in value from one to
> the
> - * maximum number of objects configured for this object type.
> - *
> - * @subsubsection ClassicRTEMSSubSec16BitObjectIdentifierFormat 16-Bit
> Object Identifier Format
> - *
> - * The 16-bit format for an object ID is composed of three parts: API,
> object
> - * class, and index. The data type @ref rtems_id is used to store object
> IDs.
> - *
> - * <table>
> - *   <tr>
> - *     <th>Bits</th>
> - *
>  <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td>
> - *
>  <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td>
> - *   </tr>
> - *   <tr>
> - *     <th>Contents</th>
> - *     <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Object
> Index</td>
> - *   </tr>
> - * </table>
> - *
> - * The 16-bit format is designed to be as similar as possible to the
> 32-bit
> - * format. The differences are limited to the elimination of the node
> field
> - * and reduction of the index field from 16-bits to 8-bits.  Thus the
> 16-bit
> - * format only supports up to 255 object instances per API/Class
> combination
> - * and single processor systems. As this format is typically utilized by
> 16-bit
> - * processors with limited address space, this is more than enough object
> - * instances.
> - *
> - * @subsection ClassicRTEMSSubSecObjectIdentiferDescription Object
> Identifer Description
> - *
> - * The components of an object ID make it possible to quickly locate any
> object
> - * in even the most complicated multiprocessor system. Object ID's are
> - * associated with an object by RTEMS when the object is created and the
> - * corresponding ID is returned by the appropriate object create
> directive. The
> - * object ID is required as input to all directives involving objects,
> except
> - * those which create an object or obtain the ID of an object.
> - *
> - * The object identification directives can be used to dynamically obtain
> a
> - * particular object's ID given its name. This mapping is accomplished by
> - * searching the name table associated with this object type. If the name
> is
> - * non-unique, then the ID associated with the first occurrence of the
> name
> - * will be returned to the application. Since object IDs are returned
> when the
> - * object is created, the object identification directives are not
> necessary in
> - * a properly designed single processor application.
> - *
> - * In addition, services are provided to portably examine the
> subcomponents of
> - * an RTEMS ID. These services are described in detail later in this
> manual but
> - * are prototyped as follows:
> - *
> - * - rtems_object_id_get_api()
> - * - rtems_object_id_get_class()
> - * - rtems_object_id_get_node()
> - * - rtems_object_id_get_index()
> - *
> - * An object control block is a data structure defined by RTEMS which
> contains
> - * the information necessary to manage a particular object type. For
> efficiency
> - * reasons, the format of each object type's control block is different.
> - * However, many of the fields are similar in function. The number of
> each type
> - * of control block is application dependent and determined by the values
> - * specified in the user's Configuration Table. An object control block is
> - * allocated at object create time and freed when the object is deleted.
> With
> - * the exception of user extension routines, object control blocks are not
> - * directly manipulated by user applications.
> - *
> - * @section ClassicRTEMSSecComSync Communication and Synchronization
> - *
> - * In real-time multitasking applications, the ability for cooperating
> - * execution threads to communicate and synchronize with each other is
> - * imperative. A real-time executive should provide an application with
> the
> - * following capabilities
> - *
> - * - data transfer between cooperating tasks,
> - * - data transfer between tasks and ISRs,
> - * - synchronization of cooperating tasks, and
> - * - synchronization of tasks and ISRs.
> - *
> - * Most RTEMS managers can be used to provide some form of communication
> and/or
> - * synchronization. However, managers dedicated specifically to
> communication
> - * and synchronization provide well established mechanisms which directly
> map
> - * to the application's varying needs. This level of flexibility allows
> the
> - * application designer to match the features of a particular manager
> with the
> - * complexity of communication and synchronization required. The following
> - * managers were specifically designed for communication and
> synchronization:
> - *
> - * - @ref ClassicSem
> - * - @ref ClassicMessageQueue
> - * - @ref ClassicEvent
> - * - @ref ClassicSignal
> - *
> - * The semaphore manager supports mutual exclusion involving the
> - * synchronization of access to one or more shared user resources. Binary
> - * semaphores may utilize the optional priority inheritance algorithm to
> avoid
> - * the problem of priority inversion. The message manager supports both
> - * communication and synchronization, while the event manager primarily
> - * provides a high performance synchronization mechanism. The signal
> manager
> - * supports only asynchronous communication and is typically used for
> exception
> - * handling.
> - *
> - * @section ClassicRTEMSSecTime Time
> - *
> - * The development of responsive real-time applications requires an
> - * understanding of how RTEMS maintains and supports time-related
> operations.
> - * The basic unit of time in RTEMS is known as a tick. The frequency of
> clock
> - * ticks is completely application dependent and determines the
> granularity and
> - * accuracy of all interval and calendar time operations.
> - *
> - * By tracking time in units of ticks, RTEMS is capable of supporting
> interval
> - * timing functions such as task delays, timeouts, timeslicing, the
> delayed
> - * execution of timer service routines, and the rate monotonic scheduling
> of
> - * tasks. An interval is defined as a number of ticks relative to the
> current
> - * time. For example, when a task delays for an interval of ten ticks, it
> is
> - * implied that the task will not execute until ten clock ticks have
> occurred.
> - * All intervals are specified using data type @ref rtems_interval.
> - *
> - * A characteristic of interval timing is that the actual interval period
> may
> - * be a fraction of a tick less than the interval requested. This occurs
> - * because the time at which the delay timer is set up occurs at some time
> - * between two clock ticks. Therefore, the first countdown tick occurs in
> less
> - * than the complete time interval for a tick. This can be a problem if
> the
> - * clock granularity is large.
> - *
> - * The rate monotonic scheduling algorithm is a hard real-time scheduling
> - * methodology. This methodology provides rules which allows one to
> guarantee
> - * that a set of independent periodic tasks will always meet their
> deadlines --
> - * even under transient overload conditions. The rate monotonic manager
> - * provides directives built upon the Clock Manager's interval timer
> support
> - * routines.
> - *
> - * Interval timing is not sufficient for the many applications which
> require
> - * that time be kept in wall time or true calendar form. Consequently,
> RTEMS
> - * maintains the current date and time. This allows selected time
> operations to
> - * be scheduled at an actual calendar date and time. For example, a task
> could
> - * request to delay until midnight on New Year's Eve before lowering the
> ball
> - * at Times Square. The data type @ref rtems_time_of_day is used to
> specify
> - * calendar time in RTEMS services. See Clock Manager Time and Date Data
> - * Structures.
> - *
> - * @todo Link to Clock Manager Time and Date Data Structures
> - *
> - * Obviously, the directives which use intervals or wall time cannot
> operate
> - * without some external mechanism which provides a periodic clock tick.
> This
> - * clock tick is typically provided by a real time clock or counter/timer
> - * device.
> - *
> - * @section ClassicRTEMSSecMemoryManagement Memory Management
> - *
> - * RTEMS memory management facilities can be grouped into two classes:
> dynamic
> - * memory allocation and address translation. Dynamic memory allocation is
> - * required by applications whose memory requirements vary through the
> - * application's course of execution. Address translation is needed by
> - * applications which share memory with another CPU or an intelligent
> - * Input/Output processor. The following RTEMS managers provide
> facilities to
> - * manage memory:
> - *
> - * - @ref ClassicRegion
> - * - @ref ClassicPart
> - * - @ref ClassicDPMEM
> - *
> - * RTEMS memory management features allow an application to create simple
> - * memory pools of fixed size buffers and/or more complex memory pools of
> - * variable size segments. The partition manager provides directives to
> manage
> - * and maintain pools of fixed size entities such as resource control
> blocks.
> - * Alternatively, the region manager provides a more general purpose
> memory
> - * allocation scheme that supports variable size blocks of memory which
> are
> - * dynamically obtained and freed by the application. The dual-ported
> memory
> - * manager provides executive support for address translation between
> internal
> - * and external dual-ported RAM address space.
> - */
> -
> -/**
> - * @addtogroup RTEMSAPIClassicTasks
> - *
> - * @section ClassicTasksSecTaskDefinition Task Definition
> - *
> - * Many definitions of a task have been proposed in computer literature.
> - * Unfortunately, none of these definitions encompasses all facets of the
> - * concept in a manner which is operating system independent. Several of
> the
> - * more common definitions are provided to enable each user to select a
> - * definition which best matches their own experience and understanding
> of the
> - * task concept:
> - *
> - * - a "dispatchable" unit.
> - * - an entity to which the processor is allocated.
> - * - an atomic unit of a real-time, multiprocessor system.
> - * - single threads of execution which concurrently compete for resources.
> - * - a sequence of closely related computations which can execute
> concurrently
> - *   with other computational sequences.
> - *
> - * From RTEMS' perspective, a task is the smallest thread of execution
> which
> - * can compete on its own for system resources. A task is manifested by
> the
> - * existence of a task control block (TCB).
> - *
> - * @section ClassicTasksSecTaskControlBlock Task Control Block
> - *
> - * The Task Control Block (TCB) is an RTEMS defined data structure which
> - * contains all the information that is pertinent to the execution of a
> task.
> - * During system initialization, RTEMS reserves a TCB for each task
> configured.
> - * A TCB is allocated upon creation of the task and is returned to the
> TCB free
> - * list upon deletion of the task.
> - *
> - * The TCB's elements are modified as a result of system calls made by the
> - * application in response to external and internal stimuli. TCBs are the
> only
> - * RTEMS internal data structure that can be accessed by an application
> via
> - * user extension routines. The TCB contains a task's name, ID, current
> - * priority, current and starting states, execution mode, TCB user
> extension
> - * pointer, scheduling control structures, as well as data required by a
> - * blocked task.
> - *
> - * A task's context is stored in the TCB when a task switch occurs. When
> the
> - * task regains control of the processor, its context is restored from
> the TCB.
> - * When a task is restarted, the initial state of the task is restored
> from the
> - * starting context area in the task's TCB.
> - *
> - * @section ClassicTasksSecTaskStates Task States
> - *
> - * A task may exist in one of the following five states:
> - *
> - * - executing - Currently scheduled to the CPU
> - * - ready - May be scheduled to the CPU
> - * - blocked - Unable to be scheduled to the CPU
> - * - dormant - Created task that is not started
> - * - non-existent - Uncreated or deleted task
> - *
> - * An active task may occupy the executing, ready, blocked or dormant
> state,
> - * otherwise the task is considered non-existent. One or more tasks may be
> - * active in the system simultaneously. Multiple tasks communicate,
> - * synchronize, and compete for system resources with each other via
> system
> - * calls. The multiple tasks appear to execute in parallel, but actually
> each
> - * is dispatched to the CPU for periods of time determined by the RTEMS
> - * scheduling algorithm. The scheduling of a task is based on its current
> state
> - * and priority.
> - *
> - * @section ClassicTasksSecTaskPriority Task Priority
> - *
> - * A task's priority determines its importance in relation to the other
> tasks
> - * executing on the same processor. RTEMS supports 255 levels of priority
> - * ranging from 1 to 255. The data type rtems_task_priority() is used to
> store
> - * task priorities.
> - *
> - * Tasks of numerically smaller priority values are more important tasks
> than
> - * tasks of numerically larger priority values. For example, a task at
> priority
> - * level 5 is of higher privilege than a task at priority level 10. There
> is no
> - * limit to the number of tasks assigned to the same priority.
> - *
> - * Each task has a priority associated with it at all times. The initial
> value
> - * of this priority is assigned at task creation time. The priority of a
> task
> - * may be changed at any subsequent time.
> - *
> - * Priorities are used by the scheduler to determine which ready task
> will be
> - * allowed to execute. In general, the higher the logical priority of a
> task,
> - * the more likely it is to receive processor execution time.
> - *
> - * @section ClassicTasksSecTaskMode Task Mode
> - *
> - * A task's execution mode is a combination of the following four
> components:
> - *
> - * - preemption
> - * - ASR processing
> - * - timeslicing
> - * - interrupt level
> - *
> - * It is used to modify RTEMS' scheduling process and to alter the
> execution
> - * environment of the task. The data type rtems_task_mode() is used to
> manage
> - * the task execution mode.
> - *
> - * The preemption component allows a task to determine when control of the
> - * processor is relinquished. If preemption is disabled (@c
> - * RTEMS_NO_PREEMPT), the task will retain control of the
> - * processor as long as it is in the executing state -- even if a higher
> - * priority task is made ready. If preemption is enabled (@c
> RTEMS_PREEMPT)
> - * and a higher priority task is made ready, then the processor will be
> - * taken away from the current task immediately and given to the higher
> - * priority task.
> - *
> - * The timeslicing component is used by the RTEMS scheduler to determine
> how
> - * the processor is allocated to tasks of equal priority. If timeslicing
> is
> - * enabled (@c RTEMS_TIMESLICE), then RTEMS will limit the amount of time
> the
> - * task can execute before the processor is allocated to another ready
> task of
> - * equal priority. The length of the timeslice is application dependent
> and
> - * specified in the Configuration Table. If timeslicing is disabled (@c
> - * RTEMS_NO_TIMESLICE), then the task will be allowed to
> - * execute until a task of higher priority is made ready. If @c
> - * RTEMS_NO_PREEMPT is selected, then the timeslicing component is
> ignored by
> - * the scheduler.
> - *
> - * The asynchronous signal processing component is used to determine when
> - * received signals are to be processed by the task. If signal processing
> is
> - * enabled (@c RTEMS_ASR), then signals sent to the task will be processed
> - * the next time the task executes. If signal processing is disabled (@c
> - * RTEMS_NO_ASR), then all signals received by the task will
> - * remain posted until signal processing is enabled. This component
> affects
> - * only tasks which have established a routine to process asynchronous
> signals.
> - *
> - * The interrupt level component is used to determine which interrupts
> will be
> - * enabled when the task is executing. @c RTEMS_INTERRUPT_LEVEL(n)
> specifies
> - * that the task will execute at interrupt level n.
> - *
> - * - @ref RTEMS_PREEMPT - enable preemption (default)
> - * - @ref RTEMS_NO_PREEMPT - disable preemption
> - * - @ref RTEMS_NO_TIMESLICE - disable timeslicing (default)
> - * - @ref RTEMS_TIMESLICE - enable timeslicing
> - * - @ref RTEMS_ASR - enable ASR processing (default)
> - * - @ref RTEMS_NO_ASR - disable ASR processing
> - * - @ref RTEMS_INTERRUPT_LEVEL(0) - enable all interrupts (default)
> - * - @ref RTEMS_INTERRUPT_LEVEL(n) - execute at interrupt level n
> - *
> - * The set of default modes may be selected by specifying the @ref
> - * RTEMS_DEFAULT_MODES constant.
> - *
> - * @section ClassicTasksSecAccessingTaskArguments Accessing Task Arguments
> - *
> - * All RTEMS tasks are invoked with a single argument which is specified
> when
> - * they are started or restarted. The argument is commonly used to
> communicate
> - * startup information to the task. The simplest manner in which to
> define a
> - * task which accesses it argument is:
> - *
> - * @code
> - *  rtems_task user_task(
> - *     rtems_task_argument argument
> - *  );
> - * @endcode
> - *
> - * Application tasks requiring more information may view this single
> argument
> - * as an index into an array of parameter blocks.
> - *
> - * @section ClassicTasksSecFloatingPointConsiderations Floating Point
> Considerations
> - *
> - * Creating a task with the @ref RTEMS_FLOATING_POINT attribute flag
> results in
> - * additional memory being allocated for the TCB to store the state of the
> - * numeric coprocessor during task switches. This additional memory is NOT
> - * allocated for @ref RTEMS_NO_FLOATING_POINT tasks. Saving and restoring
> the
> - * context of a @c RTEMS_FLOATING_POINT task takes longer than that of a
> @c
> - * RTEMS_NO_FLOATING_POINT task because of the relatively large amount of
> time
> - * required for the numeric coprocessor to save or restore its
> computational
> - * state.
> - *
> - * Since RTEMS was designed specifically for embedded military
> applications
> - * which are floating point intensive, the executive is optimized to avoid
> - * unnecessarily saving and restoring the state of the numeric
> coprocessor. The
> - * state of the numeric coprocessor is only saved when a @c
> - * RTEMS_FLOATING_POINT task is dispatched and that task was not the last
> task
> - * to utilize the coprocessor. In a system with only one @c
> - * RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will
> never
> - * be saved or restored.
> - *
> - * Although the overhead imposed by @c RTEMS_FLOATING_POINT tasks is
> minimal,
> - * some applications may wish to completely avoid the overhead associated
> with
> - * @c RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor.
> By
> - * preventing a task from being preempted while performing a sequence of
> - * floating point operations, a @c RTEMS_NO_FLOATING_POINT task can
> utilize
> - * the numeric coprocessor without incurring the overhead of a @c
> - * RTEMS_FLOATING_POINT context switch. This approach also avoids the
> - * allocation of a floating point context area. However, if this approach
> is
> - * taken by the application designer, NO tasks should be created as @c
> - * RTEMS_FLOATING_POINT tasks.  Otherwise, the floating point context
> will not
> - * be correctly maintained because RTEMS assumes that the state of the
> numeric
> - * coprocessor will not be altered by @c RTEMS_NO_FLOATING_POINT tasks.
> - *
> - * If the supported processor type does not have hardware floating
> capabilities
> - * or a standard numeric coprocessor, RTEMS will not provide built-in
> support
> - * for hardware floating point on that processor. In this case, all tasks
> are
> - * considered @c RTEMS_NO_FLOATING_POINT whether created as @c
> - * RTEMS_FLOATING_POINT or @c RTEMS_NO_FLOATING_POINT tasks. A floating
> point
> - * emulation software library must be utilized for floating point
> operations.
> - *
> - * On some processors, it is possible to disable the floating point unit
> - * dynamically. If this capability is supported by the target processor,
> then
> - * RTEMS will utilize this capability to enable the floating point unit
> only
> - * for tasks which are created with the @c RTEMS_FLOATING_POINT attribute.
> - * The consequence of a @c RTEMS_NO_FLOATING_POINT task attempting to
> access
> - * the floating point unit is CPU dependent but will generally result in
> an
> - * exception condition.
> - *
> - * @section ClassicTasksSecPerTaskVariables Per Task Variables
> - *
> - * Per task variables are no longer available.  In particular the
> - * rtems_task_variable_add(), rtems_task_variable_get() and
> - * rtems_task_variable_delete() functions are neither declared nor defined
> - * anymore.  Use thread local storage or POSIX Keys instead.
> - *
> - * @section ClassicTasksSecBuildingTaskAttributeSet Building a Task
> Attribute Set
> - *
> - * In general, an attribute set is built by a bitwise OR of the desired
> - * components. The set of valid task attribute components is listed below:
> - *
> - * - @ref RTEMS_NO_FLOATING_POINT - does not use coprocessor (default)
> - * - @ref RTEMS_FLOATING_POINT - uses numeric coprocessor
> - * - @ref RTEMS_LOCAL - local task (default)
> - * - @ref RTEMS_GLOBAL - global task
> - *
> - * Attribute values are specifically designed to be mutually exclusive,
> - * therefore bitwise OR and addition operations are equivalent as long as
> each
> - * attribute appears exactly once in the component list. A component
> listed as
> - * a default is not required to appear in the component list, although it
> is a
> - * good programming practice to specify default components. If all
> defaults are
> - * desired, then @ref RTEMS_DEFAULT_ATTRIBUTES should be used.  This
> example
> - * demonstrates the attribute_set parameter needed to create a local task
> which
> - * utilizes the numeric coprocessor. The attribute_set parameter could be
> @c
> - * RTEMS_FLOATING_POINT or @c RTEMS_LOCAL | @c RTEMS_FLOATING_POINT. The
> - * attribute_set parameter can be set to @c RTEMS_FLOATING_POINT because
> @c
> - * RTEMS_LOCAL is the default for all created tasks. If the task were
> global
> - * and used the numeric coprocessor, then the attribute_set parameter
> would be
> - * @c RTEMS_GLOBAL | @c RTEMS_FLOATING_POINT.
> - *
> - * @section ClassicTasksSecBuildingModeAndMask Building a Mode and Mask
> - *
> - * In general, a mode and its corresponding mask is built by a bitwise OR
> of
> - * the desired components. The set of valid mode constants and each mode's
> - * corresponding mask constant is listed below:
> - *
> - * <table>
> - * <tr><th>Mode Constant</th><th>Mask
> Constant</th><th>Description</th></tr>
> - * <tr><td>@ref RTEMS_PREEMPT</td><td>@ref
> RTEMS_PREEMPT_MASK</td><td>enables preemption</td></tr>
> - * <tr><td>@ref RTEMS_NO_PREEMPT</td><td>@ref
> RTEMS_PREEMPT_MASK</td><td>disables preemption</td></tr>
> - * <tr><td>@ref RTEMS_NO_TIMESLICE</td><td>@ref
> RTEMS_TIMESLICE_MASK</td><td>disables timeslicing</td></tr>
> - * <tr><td>@ref RTEMS_TIMESLICE</td><td>@ref
> RTEMS_TIMESLICE_MASK</td><td>enables timeslicing</td></tr>
> - * <tr><td>@ref RTEMS_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>enables ASR
> processing</td></tr>
> - * <tr><td>@ref RTEMS_NO_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>disables
> ASR processing</td></tr>
> - * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(0)</td><td>@ref
> RTEMS_INTERRUPT_MASK</td><td>enables all interrupts</td></tr>
> - * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(n)</td><td>@ref
> RTEMS_INTERRUPT_MASK</td><td>sets interrupts level n</td></tr>
> - * </table>
> - *
> - * Mode values are specifically designed to be mutually exclusive,
> therefore
> - * bitwise OR and addition operations are equivalent as long as each mode
> - * appears exactly once in the component list. A mode component listed as
> a
> - * default is not required to appear in the mode component list, although
> it is
> - * a good programming practice to specify default components. If all
> defaults
> - * are desired, the mode @ref RTEMS_DEFAULT_MODES and the mask @ref
> - * RTEMS_ALL_MODE_MASKS should be used.
> - *
> - * The following example demonstrates the mode and mask parameters used
> with
> - * the rtems_task_mode() directive to place a task at interrupt level 3
> and
> - * make it non-preemptible. The mode should be set to @c
> - * RTEMS_INTERRUPT_LEVEL(3) | @c RTEMS_NO_PREEMPT to indicate the desired
> - * preemption mode and interrupt level, while the mask parameter should
> be set
> - * to @c RTEMS_INTERRUPT_MASK | @c RTEMS_PREEMPT_MASK to indicate that
> - * the calling task's interrupt level and preemption mode are being
> altered.
> - */
> -
> - /**
> -  * @defgroup LocalPackages Local Packages
> -  *
> -  * @ingroup RTEMSAPIClassic
> -  *
> -  * @brief Local packages.
> -  */
> diff --git a/spec/build/cpukit/librtemscpu.yml
> b/spec/build/cpukit/librtemscpu.yml
> index ff4ac8e944..14a9de009b 100644
> --- a/spec/build/cpukit/librtemscpu.yml
> +++ b/spec/build/cpukit/librtemscpu.yml
> @@ -281,7 +281,6 @@ install:
>    - cpukit/include/rtems/rtems/eventimpl.h
>    - cpukit/include/rtems/rtems/eventmp.h
>    - cpukit/include/rtems/rtems/intr.h
> -  - cpukit/include/rtems/rtems/mainpage.h
>    - cpukit/include/rtems/rtems/message.h
>    - cpukit/include/rtems/rtems/messagedata.h
>    - cpukit/include/rtems/rtems/messageimpl.h
> --
> 2.35.3
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20231010/48ce4496/attachment-0001.htm>