summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-10-29 05:09:35 +1100
committerChris Johns <chrisj@rtems.org>2016-10-29 05:09:35 +1100
commit23a5ce44981ae3c5d92885ac089b2be825d2550e (patch)
tree6510c434a004fb3dabfab5c290bd2f520dd5f45c
parent2592441410608c414b5a4fa601f291010b985b04 (diff)
downloadrtems-docs-23a5ce44981ae3c5d92885ac089b2be825d2550e.tar.bz2
Remove the old files.
-rw-r--r--bsp_howto/bsp_howto_old_reference_only.rst4580
-rw-r--r--c_user/c_user_old_reference_only.rst23788
-rw-r--r--cpu_supplement/cpu_supplement_old_reference_only.rst4762
-rw-r--r--develenv/develenv_old_reference_only.rst1393
-rw-r--r--filesystem/filesystem_old_reference_only.rst4602
-rw-r--r--networking/networking_old_reference_only.rst2044
-rw-r--r--porting/porting_old_reference_only.rst1920
-rw-r--r--posix_users/posix_users_old_reference_only.rst11612
-rw-r--r--shell/shell_old_reference_only.rst6998
9 files changed, 0 insertions, 61699 deletions
diff --git a/bsp_howto/bsp_howto_old_reference_only.rst b/bsp_howto/bsp_howto_old_reference_only.rst
deleted file mode 100644
index ea68b57..0000000
--- a/bsp_howto/bsp_howto_old_reference_only.rst
+++ /dev/null
@@ -1,4580 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-:orphan:
-
-
-
-.. COMMENT: %**end of header
-
-.. COMMENT: COPYRIGHT (c) 1989-2013.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: Master file for the Getting Started (C) Guide
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The following determines which set of the tables and figures we will use.
-
-.. COMMENT: We default to ASCII but if available TeX or HTML versions will
-
-.. COMMENT: be used instead.
-
-.. COMMENT: @clear use-html
-
-.. COMMENT: @clear use-tex
-
-.. COMMENT: The following variable says to use texinfo or html for the two column
-
-.. COMMENT: texinfo tables. For somethings the format does not look good in html.
-
-.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
-
-.. COMMENT: good printed.
-
-.. COMMENT: Custom whitespace adjustments. We could fiddle a bit more.
-
-.. COMMENT: Title Page Stuff
-
-.. COMMENT: I don't really like having a short title page. -joel
-
-.. COMMENT: @shorttitlepage BSP and Device Driver Development Guide
-
-=======================================
-BSP and Device Driver Development Guide
-=======================================
-
-.. COMMENT: COPYRIGHT (c) 1988-2015.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
-
-.. COMMENT: can force the copyright description onto a left hand page.
-
-COPYRIGHT © 1988 - 2015.
-
-On-Line Applications Research Corporation (OAR).
-
-The authors have used their best efforts in preparing
-this material. These efforts include the development, research,
-and testing of the theories and programs to determine their
-effectiveness. No warranty of any kind, expressed or implied,
-with regard to the software or the material contained in this
-document is provided. No liability arising out of the
-application or use of any product described in this document is
-assumed. The authors reserve the right to revise this material
-and to make changes from time to time in the content hereof
-without obligation to notify anyone of such revision or changes.
-
-The RTEMS Project is hosted at http://www.rtems.org. Any
-inquiries concerning RTEMS, its related support components, or its
-documentation should be directed to the Community Project hosted athttp://www.rtems.org.
-
-Any inquiries for commercial services including training, support, custom
-development, application development assistance should be directed tohttp://www.rtems.com.
-
-.. COMMENT: This prevents a black box from being printed on "overflow" lines.
-
-.. COMMENT: The alternative is to rework a sentence to avoid this problem.
-
-RTEMS BSP and Device Driver Development Guide
-#############################################
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Introduction
-############
-
-Before reading this documentation, it is strongly advised to read the
-RTEMS Development Environment Guide to get acquainted with the RTEMS
-directory structure. This document describes how to do a RTEMS Board
-Support Package, i.e. how to port RTEMS on a new target board. Discussions
-are provided for the following topics:
-
-- RTEMS Board Support Package Organization
-
-- Makefiles and the Linker Command Script
-
-- Board Initialization Sequence
-
-- Device Drivers Including:
- - Console Driver
- - Clock Driver
- - Timer Driver
- - Real-Time Clock Driver
- - Non-Volatile Memory Driver
- - Networking Driver
- - Shared Memory Support Driver
- - Analog Driver
- - Discrete Driver
-
-The original version of this manual was written by Geoffroy Montel
-<g_montel@yahoo.com>. When he started development of the gen68340
-BSP, this manual did not exist. He wrote the initial version of
-this manual as the result of his experiences. At that time, this
-document was viewed internally as the most important "missing manual"
-in the RTEMS documentation set.
-
-The gen68340 BSP is a good example of the life of an RTEMS BSP. It is
-based upon a part not recommended for new designs and none of the core RTEMS
-Project team members have one of these boards. Thus we are unlikely to
-perform major updates on this BSP. So as long as it compiles and links all
-tests, it will be available.
-
-The RTEMS Project team members are always trying to identify common
-code across BSPs and refactoring the code into shared routines.
-As part of this effort, the we will enhance the common BSP Framework.
-Not surprisingly, not every BSP takes advantage of every feature in
-the framework. The gen68340 does not take advantage of as many features
-as the ERC32 BSP does. So in many ways, the ERC32 is a better example
-BSP at this point. But even the ERC32 BSP does not include examples
-of every driver template and framework available to the BSP author.
-So in this guide we will try to point out good examples from other BSPs.
-
-Our goal is for you to be able to reuse as much code as possible and
-write as little board specific code as possible.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Target Dependent Files
-######################
-
-RTEMS has a multi-layered approach to portability. This is done to
-maximize the amount of software that can be reused. Much of the
-RTEMS source code can be reused on all RTEMS platforms. Other parts
-of the executive are specific to hardware in some sense.
-RTEMS classifies target dependent code based upon its dependencies
-into one of the following categories.
-
-- CPU dependent
-
-- Board dependent
-
-- Peripheral dependent
-
-CPU Dependent
-=============
-
-This class of code includes the foundation
-routines for the executive proper such as the context switch and
-the interrupt subroutine implementations. Sources for the supported
-processor families can be found in ``cpukit/score/cpu``.
-A good starting point for a new family of processors is the``no_cpu`` directory, which holds both prototypes and
-descriptions of each needed CPU dependent function.
-
-CPU dependent code is further subcategorized if the implementation is
-dependent on a particular CPU model. For example, the MC68000 and MC68020
-processors are both members of the m68k CPU family but there are significant
-differences between these CPU models which RTEMS must take into account.
-
-The source code found in the ``cpukit/score/cpu`` is required to
-only depend upon the CPU model variations that GCC distinguishes
-for the purposes of multilib’ing. Multilib is the term the GNU
-community uses to refer to building a single library source multiple
-times with different compiler options so the binary code generated
-is compatible. As an example, from GCC’s perspective, many PowerPC
-CPU models are just a PPC603e. Remember that GCC only cares about
-the CPU code itself and need not be aware of any peripherals. In
-the embedded community, we are exposed to thousands of CPU models
-which are all based upon only a relative small number of CPU cores.
-
-Similarly for the SPARC/ERC32 BSP, the ``RTEMS_CPU`` is specified as``erc32`` which is the name of the CPU model and BSP for this SPARC V7
-system on chip. But the multilib variant used is actually ``v7``
-which indicates the ERC32 CPU core is a SPARC V7.
-
-Board Dependent
-===============
-
-This class of code provides the most specific glue between RTEMS and
-a particular board. This code is represented by the Board Support Packages
-and associated Device Drivers. Sources for the BSPs included in the
-RTEMS distribution are located in the directory ``c/src/lib/libbsp``.
-The BSP source directory is further subdivided based on the CPU family
-and BSP.
-
-Some BSPs may support multiple board models within a single board family.
-This is necessary when the board supports multiple variants on a
-single base board. For example, the Motorola MVME162 board family has a
-fairly large number of variations based upon the particular CPU model
-and the peripherals actually placed on the board.
-
-Peripheral Dependent
-====================
-
-This class of code provides a reusable library of peripheral device
-drivers which can be tailored easily to a particular board. The
-libchip library is a collection of reusable software objects that
-correspond to standard controllers. Just as the hardware engineer
-chooses a standard controller when designing a board, the goal of
-this library is to let the software engineer do the same thing.
-
-The source code for the reusable peripheral driver library may be found
-in the directory ``c/src/lib/libchip``. The source code is further
-divided based upon the class of hardware. Example classes include serial
-communications controllers, real-time clocks, non-volatile memory, and
-network controllers.
-
-Questions to Ask
-================
-
-When evaluating what is required to support RTEMS applications on
-a particular target board, the following questions should be asked:
-
-- Does a BSP for this board exist?
-
-- Does a BSP for a similar board exists?
-
-- Is the board’s CPU supported?
-
-If there is already a BSP for the board, then things may already be ready
-to start developing application software. All that remains is to verify
-that the existing BSP provides device drivers for all the peripherals
-on the board that the application will be using. For example, the application
-in question may require that the board’s Ethernet controller be used and
-the existing BSP may not support this.
-
-If the BSP does not exist and the board’s CPU model is supported, then
-examine the reusable chip library and existing BSPs for a close match.
-Other BSPs and libchip provide starting points for the development
-of a new BSP. It is often possible to copy existing components in
-the reusable chip library or device drivers from BSPs from different
-CPU families as the starting point for a new device driver.
-This will help reduce the development effort required.
-
-If the board’s CPU family is supported but the particular CPU model on
-that board is not, then the RTEMS port to that CPU family will have to
-be augmented. After this is done, development of the new BSP can proceed.
-
-Otherwise both CPU dependent code and the BSP will have to be written.
-
-This type of development often requires specialized skills. If
-you need help in making these modifications to RTEMS, please
-consider using one of the RTEMS Service Providers. The current
-list of these is at http://www.rtems.org/support.html.
-
-CPU Dependent Executive Files
-=============================
-
-The CPU dependent files in the RTEMS executive source code are found
-in the following directory:
-.. code:: c
-
- cpukit/score/cpu/*CPU*
-
-where *CPU* is replaced with the CPU family name.
-
-Within each CPU dependent directory inside the executive proper is a
-file named ``*CPU*.h`` which contains information about each of the
-supported CPU models within that family.
-
-CPU Dependent Support Files
-===========================
-
-The CPU dependent support files contain routines which aid in the development
-of applications using that CPU family. For example, the support routines
-may contain standard trap handlers for alignment or floating point exceptions
-or device drivers for peripheral controllers found on the CPU itself.
-This class of code may be found in the following directory:
-
-.. code:: c
-
- c/src/lib/libcpu/*CPU*
-
-CPU model dependent support code is found in the following directory:
-
-.. code:: c
-
- c/src/lib/libcpu/*CPU*/*CPU_MODEL*
-
-*CPU_MODEL* may be a specific CPU model name or a name indicating a CPU
-core or a set of related CPU models. The file ``configure.ac`` in each ``c/src/lib/libcpu/*CPU*`` directory contains the logic which enables
-the appropriate subdirectories for the specific CPU model your BSP has.
-
-Board Support Package Structure
-===============================
-
-The BSPs are all under the ``c/src/lib/libbsp`` directory. Below this
-directory, there is a subdirectory for each CPU family. Each BSP
-is found under the subdirectory for the appropriate processor
-family (m68k, powerpc, etc.). In addition, there is source code
-available which may be shared across all BSPs regardless of
-the CPU family or just across BSPs within a single CPU family. This
-results in a BSP using the following directories:
-.. code:: c
-
- c/src/lib/libbsp/shared
- c/src/lib/libbsp/*CPU*/shared
- c/src/lib/libbsp/*CPU*/*BSP*
-
-Under each BSP specific directory, there is a collection of
-subdirectories. For commonly provided functionality, the BSPs
-follow a convention on subdirectory naming. The following list
-describes the commonly found subdirectories under each BSP.
-
-- *console*:
- is technically the serial driver for the BSP rather
- than just a console driver, it deals with the board
- UARTs (i.e. serial devices).
-
-- *clock*:
- support for the clock tick – a regular time basis to the kernel.
-
-- *timer*:
- support of timer devices.
-
-- *rtc* or ``tod``:
- support for the hardware real-time clock.
-
-- *nvmem*:
- support for non-volatile memory such as EEPROM or Flash.
-
-- *network*:
- the Ethernet driver.
-
-- *shmsupp*:
- support of shared memory driver MPCI layer in a multiprocessor system,
-
-- *include*:
- include files for this BSP.
-
-- *gnatsupp*:
- BSP specific support for the GNU Ada run-time. Each BSP that wishes
- to have the possibility to map faults or exceptions into Ada language
- exceptions or hardware interrupts into Ada interrupt tasks must provide
- this support.
-
-There may be other directories in the BSP tree and the name should
-be indicative of the functionality of the code within that directory.
-
-The build order of the BSP is determined by the Makefile structure.
-This structure is discussed in more detail in the `Makefiles`_
-chapter.
-
-*NOTE:* This manual refers to the gen68340 BSP for numerous concrete
-examples. You should have a copy of the gen68340 BSP available while
-reading this piece of documentation. This BSP is located in the
-following directory:
-.. code:: c
-
- c/src/lib/libbsp/m68k/gen68340
-
-Later in this document, the $BSP340_ROOT label will be used
-to refer to this directory.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-
-Makefiles
-#########
-
-This chapter discusses the Makefiles associated with a BSP. It does not
-describe the process of configuring, building, and installing RTEMS.
-This chapter will not provide detailed information about this process.
-Nonetheless, it is important to remember that the general process consists
-of four phases as shown here:
-
-- .. code:: c
-
- bootstrap
-
-- .. code:: c
-
- configure
-
-- .. code:: c
-
- build
-
-- .. code:: c
-
- install
-
-During the bootstrap phase, you are using the ``configure.ac`` and``Makefile.am`` files as input to GNU autoconf and automake to
-generate a variety of files. This is done by running the ``bootstrap``
-script found at the top of the RTEMS source tree.
-
-During the configure phase, a number of files are generated. These
-generated files are tailored for the specific host/target combination
-by the configure script. This set of files includes the Makefiles used
-to actually compile and install RTEMS.
-
-During the build phase, the source files are compiled into object files
-and libraries are built.
-
-During the install phase, the libraries, header files, and other support
-files are copied to the BSP specific installation point. After installation
-is successfully completed, the files generated by the configure and build
-phases may be removed.
-
-Makefiles Used During The BSP Building Process
-==============================================
-
-RTEMS uses the *GNU automake* and *GNU autoconf* automatic
-configuration package. Consequently, there are a number of
-automatically generated files in each directory in the RTEMS
-source tree. The ``bootstrap`` script found in the top level
-directory of the RTEMS source tree is executed to produce the
-automatically generated files. That script must be run from
-a directory with a ``configure.ac`` file in it. The ``bootstrap``
-command is usually invoked in one of the following manners:
-
-- ``bootstrap`` to regenerate all files that are generated by
- autoconf and automake.
-
-- ``bootstrap -c`` to remove all files generated by autoconf and
- automake.
-
-- ``bootstrap -p`` to regenerate ``preinstall.am`` files.
-
-There is a file named ``Makefile.am`` in each directory of
-a BSP. This file is used by *automake* to produce the file named``Makefile.in`` which is also found in each directory of a BSP.
-When modifying a ``Makefile.am``, you can probably find examples of
-anything you need to do in one of the BSPs.
-
-The configure process specializes the ``Makefile.in`` files at the time that RTEMS
-is configured for a specific development host and target. Makefiles
-are automatically generated from the ``Makefile.in`` files. It is
-necessary for the BSP developer to provide the ``Makefile.am``
-files and generate the ``Makefile.in`` files. Most of the
-time, it is possible to copy the ``Makefile.am`` from another
-similar directory and edit it.
-
-The ``Makefile`` files generated are processed when configuring
-and building RTEMS for a given BSP.
-
-The BSP developer is responsible for generating ``Makefile.am``
-files which properly build all the files associated with their BSP.
-Most BSPs will only have a single ``Makefile.am`` which details
-the set of source files to build to compose the BSP support library
-along with the set of include files that are to be installed.
-
-This single ``Makefile.am`` at the top of the BSP tree specifies
-the set of header files to install. This fragment from the SPARC/ERC32
-BSP results in four header files being installed.
-.. code:: c
-
- include_HEADERS = include/bsp.h
- include_HEADERS += include/tm27.h
- include_HEADERS += include/erc32.h
- include_HEADERS += include/coverhd.h
-
-When adding new include files, you will be adding to the set of``include_HEADERS``. When you finish editing the ``Makefile.am``
-file, do not forget to run ``bootstrap -p`` to regenerate the``preinstall.am``.
-
-The ``Makefile.am`` also specifies which source files to build.
-By convention, logical components within the BSP each assign their
-source files to a unique variable. These variables which define
-the source files are collected into a single variable which instructs
-the GNU autotools that we are building ``libbsp.a``. This fragment
-from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
-support code, and the console device driver source is managed
-in the ``Makefile.am``.
-.. code:: c
-
- startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \\
- ../../shared/bsppredriverhook.c \\
- ../../shared/bsppost.c ../../sparc/shared/bspstart.c \\
- ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \\
- startup/spurious.c startup/erc32mec.c startup/boardinit.S
- clock_SOURCES = clock/ckinit.c
- ...
- noinst_LIBRARIES = libbsp.a
- libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
-
-When adding new files to an existing directory, do not forget to add
-the new files to the list of files to be built in the corresponding``XXX_SOURCES`` variable in the ``Makefile.am`` and run``bootstrap``.
-
-Some BSPs use code that is built in ``libcpu``. If you BSP does
-this, then you will need to make sure the objects are pulled into your
-BSP library. The following from the SPARC/ERC32 BSP pulls in the cache,
-register window management and system call support code from the directory
-corresponding to its ``RTEMS_CPU`` model.
-.. code:: c
-
- libbsp_a_LIBADD = ../../../libcpu/@RTEMS_CPU@/cache.rel \\
- ../../../libcpu/@RTEMS_CPU@/reg_win.rel \\
- ../../../libcpu/@RTEMS_CPU@/syscall.rel
-
-*NOTE:* The ``Makefile.am`` files are ONLY processed by``bootstrap`` and the resulting ``Makefile.in`` files are only
-processed during the configure process of a RTEMS build. Therefore,
-when developing a BSP and adding a new file to a ``Makefile.am``,
-the already generated ``Makefile`` will not automatically
-include the new references unless you configured RTEMS with the``--enable-maintainer-mode`` option. Otherwise, the new file not
-being be taken into account!
-
-Creating a New BSP Make Customization File
-==========================================
-
-When building a BSP or an application using that BSP, it is necessary
-to tailor the compilation arguments to account for compiler flags, use
-custom linker scripts, include the RTEMS libraries, etc.. The BSP
-must be built using this information. Later, once the BSP is installed
-with the toolset, this same information must be used when building the
-application. So a BSP must include a build configuration file. The
-configuration file is ``make/custom/BSP.cfg``.
-
-The configuration file is taken into account when building one’s
-application using the RTEMS template Makefiles (``make/templates``).
-These application template Makefiles have been included with the
-RTEMS source distribution since the early 1990’s. However there is
-a desire in the RTEMS user community to move all provided examples to
-GNU autoconf. They are included in the 4.9 release series and used for
-all examples provided with RTEMS. There is no definite time table for
-obsoleting them. You are free to use these but be warned they have
-fallen out of favor with many in the RTEMS community and may disappear
-in the future.
-
-The following is a slightly shortened version of the make customization
-file for the gen68340 BSP. The original source for this file can be
-found in the ``make/custom`` directory.
-.. code:: c
-
- # The RTEMS CPU Family and Model
- RTEMS_CPU=m68k
- RTEMS_CPU_MODEL=m68340
- include $(RTEMS_ROOT)/make/custom/default.cfg
- # This is the actual bsp directory used during the build process.
- RTEMS_BSP_FAMILY=gen68340
- # This contains the compiler options necessary to select the CPU model
- # and (hopefully) optimize for it.
- CPU_CFLAGS = -mcpu=cpu32
- # optimize flag: typically -O2
- CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
-
-The make customization files have generally grown simpler and simpler
-with each RTEMS release. Beginning in the 4.9 release series, the rules
-for linking an RTEMS application are shared by all BSPs. Only BSPs which
-need to perform a transformation from linked ELF file to a downloadable
-format have any additional actions for program link time. In 4.8 and
-older, every BSP specified the "make executable" or ``make-exe``
-rule and duplicated the same actions.
-
-It is generally easier to copy a ``make/custom`` file from a
-BSP similar to the one being developed.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Linker Script
-#############
-
-What is a "linkcmds" file?
-==========================
-
-The ``linkcmds`` file is a script which is passed to the linker at linking
-time. This file describes the memory configuration of the board as needed
-to link the program. Specifically it specifies where the code and data
-for the application will reside in memory.
-
-The format of the linker script is defined by the GNU Loader ``ld``
-which is included as a component of the GNU Binary Utilities. If you
-are using GNU/Linux, then you probably have the documentation installed
-already and are using these same tools configured for *native* use.
-Please visit the Binutils project http://sourceware.org/binutils/
-if you need more information.
-
-Program Sections
-================
-
-An embedded systems programmer must be much more aware of the
-placement of their executable image in memory than the average
-applications programmer. A program destined to be embedded as well
-as the target system have some specific properties that must be
-taken into account. Embedded machines often mean average performances
-and small memory usage. It is the memory usage that concerns us
-when examining the linker command file.
-
-Two types of memories have to be distinguished:
-
-- RAM - volatile offering read and write access
-
-- ROM - non-volatile but read only
-
-Even though RAM and ROM can be found in every personal computer,
-one generally doesn’t care about them. In a personal computer,
-a program is nearly always stored on disk and executed in RAM. Things
-are a bit different for embedded targets: the target will execute the
-program each time it is rebooted or switched on. The application
-program is stored in non-volatile memory such as ROM, PROM, EEPROM,
-or Flash. On the other hand, data processing occurs in RAM.
-
-This leads us to the structure of an embedded program. In rough terms,
-an embedded program is made of sections. It is the responsibility of
-the application programmer to place these sections in the appropriate
-place in target memory. To make this clearer, if using the COFF
-object file format on the Motorola m68k family of microprocessors,
-the following sections will be present:
-
-- *code (``.text``) section*:
- is the program’s code and it should not be modified.
- This section may be placed in ROM.
-
-- *non-initialized data (``.bss``) section*:
- holds uninitialized variables of the program. It can stay in RAM.
-
-- *initialized data (``.data``) section*:
- holds the initialized program data which may be modified during the
- program’s life. This means they have to be in RAM.
- On the other hand, these variables must be set to predefined values, and
- those predefined values have to be stored in ROM.
-
-*NOTE:* Many programs and support libraries unknowingly assume that the``.bss`` section and, possibly, the application heap are initialized
-to zero at program start. This is not required by the ISO/ANSI C Standard
-but is such a common requirement that most BSPs do this.
-
-That brings us up to the notion of the image of an executable: it consists
-of the set of the sections that together constitute the application.
-
-Image of an Executable
-======================
-
-As a program executable has many sections (note that the user can define
-their own, and that compilers define theirs without any notice), one has to
-specify the placement of each section as well as the type of memory
-(RAM or ROM) the sections will be placed into.
-For instance, a program compiled for a Personal Computer will see all the
-sections to go to RAM, while a program destined to be embedded will see
-some of his sections going into the ROM.
-
-The connection between a section and where that section is loaded into
-memory is made at link time. One has to let the linker know where
-the different sections are to be placed once they are in memory.
-
-The following example shows a simple layout of program sections. With
-some object formats, there are many more sections but the basic
-layout is conceptually similar.
-.. code:: c
-
- +-----------------+-------------+
- | .text | RAM or ROM |
- +-----------------+-------------+
- | .data | RAM |
- +-----------------+-------------+
- | .bss | RAM |
- +-----------------+-------------+
-
-Example Linker Command Script
-=============================
-
-The GNU linker has a command language to specify the image format. This
-command language can be quite complicated but most of what is required
-can be learned by careful examination of a well-documented example.
-The following is a heavily commented version of the linker script
-used with the the ``gen68340`` BSP This file can be found at
-$BSP340_ROOT/startup/linkcmds.
-.. code:: c
-
- /*
- * Specify that the output is to be coff-m68k regardless of what the
- * native object format is.
- \*/
- OUTPUT_FORMAT(coff-m68k)
- /*
- * Set the amount of RAM on the target board.
- *
- * NOTE: The default may be overridden by passing an argument to ld.
- \*/
- RamSize = DEFINED(RamSize) ? RamSize : 4M;
- /*
- * Set the amount of RAM to be used for the application heap. Objects
- * allocated using malloc() come from this area. Having a tight heap
- * size is somewhat difficult and multiple attempts to squeeze it may
- * be needed reducing memory usage is important. If all objects are
- * allocated from the heap at system initialization time, this eases
- * the sizing of the application heap.
- *
- * NOTE 1: The default may be overridden by passing an argument to ld.
- *
- * NOTE 2: The TCP/IP stack requires additional memory in the Heap.
- *
- * NOTE 3: The GNAT/RTEMS run-time requires additional memory in
- * the Heap.
- \*/
- HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
- /*
- * Set the size of the starting stack used during BSP initialization
- * until first task switch. After that point, task stacks allocated
- * by RTEMS are used.
- *
- * NOTE: The default may be overridden by passing an argument to ld.
- \*/
- StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
- /*
- * Starting addresses and length of RAM and ROM.
- *
- * The addresses must be valid addresses on the board. The
- * Chip Selects should be initialized such that the code addresses
- * are valid.
- \*/
- MEMORY {
- ram : ORIGIN = 0x10000000, LENGTH = 4M
- rom : ORIGIN = 0x01000000, LENGTH = 4M
- }
- /*
- * This is for the network driver. See the Networking documentation
- * for more details.
- \*/
- ETHERNET_ADDRESS =
- DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
- /*
- * The following defines the order in which the sections should go.
- * It also defines a number of variables which can be used by the
- * application program.
- *
- * NOTE: Each variable appears with 1 or 2 leading underscores to
- * ensure that the variable is accessible from C code with a
- * single underscore. Some object formats automatically add
- * a leading underscore to all C global symbols.
- \*/
- SECTIONS {
- /*
- * Make the RomBase variable available to the application.
- \*/
- _RamSize = RamSize;
- __RamSize = RamSize;
- /*
- * Boot PROM - Set the RomBase variable to the start of the ROM.
- \*/
- rom : {
- _RomBase = .;
- __RomBase = .;
- } >rom
- /*
- * Dynamic RAM - set the RamBase variable to the start of the RAM.
- \*/
- ram : {
- _RamBase = .;
- __RamBase = .;
- } >ram
- /*
- * Text (code) goes into ROM
- \*/
- .text : {
- /*
- * Create a symbol for each object (.o).
- \*/
- CREATE_OBJECT_SYMBOLS
- /*
- * Put all the object files code sections here.
- \*/
- \*(.text)
- . = ALIGN (16); /* go to a 16-byte boundary \*/
- /*
- * C++ constructors and destructors
- *
- * NOTE: See the CROSSGCC mailing-list FAQ for
- * more details about the "\[......]".
- \*/
- __CTOR_LIST__ = .;
- \[......]
- __DTOR_END__ = .;
- /*
- * Declares where the .text section ends.
- \*/
- etext = .;
- _etext = .;
- } >rom
- /*
- * Exception Handler Frame section
- \*/
- .eh_fram : {
- . = ALIGN (16);
- \*(.eh_fram)
- } >ram
- /*
- * GCC Exception section
- \*/
- .gcc_exc : {
- . = ALIGN (16);
- \*(.gcc_exc)
- } >ram
- /*
- * Special variable to let application get to the dual-ported
- * memory.
- \*/
- dpram : {
- m340 = .;
- _m340 = .;
- . += (8 * 1024);
- } >ram
- /*
- * Initialized Data section goes in RAM
- \*/
- .data : {
- copy_start = .;
- \*(.data)
- . = ALIGN (16);
- _edata = .;
- copy_end = .;
- } >ram
- /*
- * Uninitialized Data section goes in ROM
- \*/
- .bss : {
- /*
- * M68K specific: Reserve some room for the Vector Table
- * (256 vectors of 4 bytes).
- \*/
- M68Kvec = .;
- _M68Kvec = .;
- . += (256 * 4);
- /*
- * Start of memory to zero out at initialization time.
- \*/
- clear_start = .;
- /*
- * Put all the object files uninitialized data sections
- * here.
- \*/
- \*(.bss)
- \*(COMMON)
- . = ALIGN (16);
- _end = .;
- /*
- * Start of the Application Heap
- \*/
- _HeapStart = .;
- __HeapStart = .;
- . += HeapSize;
- /*
- * The Starting Stack goes after the Application Heap.
- * M68K stack grows down so start at high address.
- \*/
- . += StackSize;
- . = ALIGN (16);
- stack_init = .;
- clear_end = .;
- /*
- * The RTEMS Executive Workspace goes here. RTEMS
- * allocates tasks, stacks, semaphores, etc. from this
- * memory.
- \*/
- _WorkspaceBase = .;
- __WorkspaceBase = .;
- } >ram
- }
-
-Initialized Data
-================
-
-Now there’s a problem with the initialized data: the ``.data`` section
-has to be in RAM as this data may be modified during the program execution.
-But how will the values be initialized at boot time?
-
-One approach is to place the entire program image in RAM and reload
-the image in its entirety each time the program is run. This is fine
-for use in a debug environment where a high-speed connection is available
-between the development host computer and the target. But even in this
-environment, it is cumbersome.
-
-The solution is to place a copy of the initialized data in a separate
-area of memory and copy it into the proper location each time the
-program is started. It is common practice to place a copy of the initialized ``.data`` section at the end of the code (``.text``) section
-in ROM when building a PROM image. The GNU tool ``objcopy``
-can be used for this purpose.
-
-The following figure illustrates the steps a linked program goes through
-to become a downloadable image.
-
-
-+--------------+-----+--------------------+--------------------------+
-| .data RAM | | .data RAM | |
-+--------------+ +--------------------+ |
-| .bss RAM | | .bss RAM | |
-+--------------+ +--------------------+-----+--------------------+
-| .text ROM | | .text ROM | | .text |
-+--------------+-----+---------+----------+-----+--------------------+
-| copy of .data ROM | | copy of .data | |
-+--------------------+---------+----------------+--------------------+
-| Step 1 |Step 2 Step 3 |
-+--------------------+--------------------------+--------------------+
-
-In Step 1, the program is linked together using the BSP linker script.
-
-In Step 2, a copy is made of the ``.data`` section and placed
-after the ``.text`` section so it can be placed in PROM. This step
-is done after the linking time. There is an example
-of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg:
-.. code:: c
-
- # make a PROM image using objcopy
- m68k-rtems-objcopy \\
- --adjust-section-vma .data= \\
- \`m68k-rtems-objdump --section-headers \\
- $(basename $@).exe \\
- | awk '\[...]` \\
- $(basename $@).exe
-
-NOTE: The address of the "copy of ``.data`` section" is
-created by extracting the last address in the ``.text``
-section with an ``awk`` script. The details of how
-this is done are not relevant.
-
-Step 3 shows the final executable image as it logically appears in
-the target’s non-volatile program memory. The board initialization
-code will copy the ""copy of ``.data`` section" (which are stored in
-ROM) to their reserved location in RAM.
-
-.. COMMENT: COPYRIGHT (c) 1988-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Miscellaneous Support Files
-###########################
-
-GCC Compiler Specifications File
-================================
-
-The file ``bsp_specs`` defines the start files and libraries
-that are always used with this BSP. The format of this file
-is admittedly cryptic and this document will make no attempt
-to explain it completely. Below is the ``bsp_specs``
-file from the PowerPC psim BSP:
-.. code:: c
-
- %rename endfile old_endfile
- %rename startfile old_startfile
- %rename link old_link
- \*startfile:
- %{!qrtems: %(old_startfile)} \\
- %{!nostdlib: %{qrtems: ecrti%O%s rtems_crti%O%s crtbegin.o%s start.o%s}}
- \*link:
- %{!qrtems: %(old_link)} %{qrtems: -Qy -dp -Bstatic -e _start -u __vectors}
- \*endfile:
- %{!qrtems: %(old_endfile)} %{qrtems: crtend.o%s ecrtn.o%s}
-
-The first section of this file renames the built-in definition of
-some specification variables so they can be augmented without
-embedded their original definition. The subsequent sections
-specify what behavior is expected when the ``-qrtems`` option is specified.
-
-The ``*startfile`` section specifies that the BSP specific file``start.o`` will be used instead of ``crt0.o``. In addition,
-various EABI support files (``ecrti.o`` etc.) will be linked in with
-the executable.
-
-The ``*link`` section adds some arguments to the linker when it is
-invoked by GCC to link an application for this BSP.
-
-The format of this file is specific to the GNU Compiler Suite. The
-argument used to override and extend the compiler built-in specifications
-is available in all recent GCC versions. The ``-specs`` option is
-present in all ``egcs`` distributions and ``gcc`` distributions
-starting with version 2.8.0.
-
-README Files
-============
-
-Most BSPs provide one or more ``README`` files. Generally, there
-is a ``README`` file at the top of the BSP source. This file
-describes the board and its hardware configuration, provides vendor
-information, local configuration information, information on downloading
-code to the board, debugging, etc.. The intent of this
-file is to help someone begin to use the BSP faster.
-
-A ``README`` file in a BSP subdirectory typically explains something
-about the contents of that subdirectory in greater detail. For example,
-it may list the documentation available for a particular peripheral
-controller and how to obtain that documentation. It may also explain some
-particularly cryptic part of the software in that directory or provide
-rationale on the implementation.
-
-times
-=====
-
-This file contains the results of the RTEMS Timing Test Suite. It is
-in a standard format so that results from one BSP can be easily compared
-with those of another target board.
-
-If a BSP supports multiple variants, then there may be multiple ``times``
-files. Usually these are named ``times.VARIANTn``.
-
-Tools Subdirectory
-==================
-
-Some BSPs provide additional tools that aid in using the target board.
-These tools run on the development host and are built as part of building
-the BSP. Most common is a script to automate running the RTEMS Test Suites
-on the BSP. Examples of this include:
-
-- ``powerpc/psim`` includes scripts to ease use of the simulator
-
-- ``m68k/mvme162`` includes a utility to download across the
- VMEbus into target memory if the host is a VMEbus board in the same
- chasis.
-
-bsp.h Include File
-==================
-
-The file ``include/bsp.h`` contains prototypes and definitions
-specific to this board. Every BSP is required to provide a ``bsp.h``.
-The best approach to writing a ``bsp.h`` is copying an existing one
-as a starting point.
-
-Many ``bsp.h`` files provide prototypes of variables defined
-in the linker script (``linkcmds``).
-
-tm27.h Include File
-===================
-
-The ``tm27`` test from the RTEMS Timing Test Suite is designed to measure the length of time required to vector to and return from an interrupt handler. This test requires some help from the BSP to know how to cause and manipulate the interrupt source used for this measurement. The following is a list of these:
-
-- ``MUST_WAIT_FOR_INTERRUPT`` - modifies behavior of ``tm27``.
-
-- ``Install_tm27_vector`` - installs the interrupt service
- routine for the Interrupt Benchmark Test (``tm27``).
-
-- ``Cause_tm27_intr`` - generates the interrupt source
- used in the Interrupt Benchmark Test (``tm27``).
-
-- ``Clear_tm27_intr`` - clears the interrupt source
- used in the Interrupt Benchmark Test (``tm27``).
-
-- ``Lower_tm27_intr`` - lowers the interrupt mask so the
- interrupt source used in the Interrupt Benchmark Test (``tm27``)
- can generate a nested interrupt.
-
-All members of the Timing Test Suite are designed to run *WITHOUT*
-the Clock Device Driver installed. This increases the predictability
-of the tests’ execution as well as avoids occassionally including the
-overhead of a clock tick interrupt in the time reported. Because of
-this it is sometimes possible to use the clock tick interrupt source
-as the source of this test interrupt. On other architectures, it is
-possible to directly force an interrupt to occur.
-
-Calling Overhead File
-=====================
-
-The file ``include/coverhd.h`` contains the overhead associated
-with invoking each directive. This overhead consists of the execution
-time required to package the parameters as well as to execute the "jump to
-subroutine" and "return from subroutine" sequence. The intent of this
-file is to help separate the calling overhead from the actual execution
-time of a directive. This file is only used by the tests in the
-RTEMS Timing Test Suite.
-
-The numbers in this file are obtained by running the "Timer Overhead"``tmoverhd`` test. The numbers in this file may be 0 and no
-overhead is subtracted from the directive execution times reported by
-the Timing Suite.
-
-There is a shared implementation of ``coverhd.h`` which sets all of
-the overhead constants to 0. On faster processors, this is usually the
-best alternative for the BSP as the calling overhead is extremely small.
-This file is located at:
-.. code:: c
-
- c/src/lib/libbsp/shared/include/coverhd.h
-
-sbrk() Implementation
-=====================
-
-Although nearly all BSPs give all possible memory to the C Program Heap
-at initialization, it is possible for a BSP to configure the initial
-size of the heap small and let it grow on demand. If the BSP wants
-to dynamically extend the heap used by the C Library memory allocation
-routines (i.e. ``malloc`` family), then the``sbrk`` routine must
-be functional. The following is the prototype for this routine:
-.. code:: c
-
- void * sbrk(size_t increment)
-
-The ``increment`` amount is based upon the ``sbrk_amount``
-parameter passed to the ``bsp_libc_init`` during system initialization... index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
-
-If your BSP does not want to support dynamic heap extension, then you do not have to do anything special. However, if you want to support ``sbrk``, you must provide an implementation of this method and define ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` in ``bsp.h``. This informs ``rtems/confdefs.h`` to configure the Malloc Family Extensions which support ``sbrk``.
-
-bsp_fatal_extension() - Cleanup the Hardware
-============================================
-
-The ``bsp_fatal_extension()`` is an optional BSP specific initial extension
-invoked once a fatal system state is reached. Most of the BSPs use the same
-shared version of ``bsp_fatal_extension()`` that does nothing or performs a
-system reset. This implementation is located in the following file:
-.. code:: c
-
- c/src/lib/libbsp/shared/bspclean.c
-
-The ``bsp_fatal_extension()`` routine can be used to return to a ROM
-monitor, insure that interrupt sources are disabled, etc.. This routine is the
-last place to ensure a clean shutdown of the hardware. The fatal source,
-internal error indicator, and the fatal code arguments are available to
-evaluate the fatal condition. All of the non-fatal shutdown sequences
-ultimately pass their exit status to ``rtems_shutdown_executive`` and this
-is what is passed to this routine in case the fatal source is
-RTEMS_FATAL_SOURCE_EXIT.
-
-On some BSPs, it prints a message indicating that the application
-completed execution and waits for the user to press a key before
-resetting the board. The PowerPC/gen83xx and PowerPC/gen5200 BSPs do
-this when they are built to support the FreeScale evaluation boards.
-This is convenient when using the boards in a development environment
-and may be disabled for production use.
-
-Configuration Macros
-====================
-
-Each BSP can define macros in bsp.h which alter some of the the default configuration parameters in ``rtems/confdefs.h``. This section describes those macros:
-
-- .. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
-
- ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` must be defined if the
- BSP has proper support for ``sbrk``. This is discussed in more detail
- in the previous section.
-
-- .. index:: BSP_IDLE_TASK_BODY
-
- ``BSP_IDLE_TASK_BODY`` may be defined to the entry point of a
- BSP specific IDLE thread implementation. This may be overridden if the
- application provides its own IDLE task implementation.
-
-- .. index:: BSP_IDLE_TASK_STACK_SIZE
-
- ``BSP_IDLE_TASK_STACK_SIZE`` may be defined to the desired
- default stack size for the IDLE task as recommended when using this BSP.
-
-- .. index:: BSP_INTERRUPT_STACK_SIZE
-
- ``BSP_INTERRUPT_STACK_SIZE`` may be defined to the desired default interrupt stack size as recommended when using this BSP. This is sometimes required when the BSP developer has knowledge of stack intensive interrupt handlers.
-
-- .. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY
-
- ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined when the BSP
- requires that RTEMS zero out the RTEMS C Program Heap at initialization.
- If the memory is already zeroed out by a test sequence or boot ROM,
- then the boot time can be reduced by not zeroing memory twice.
-
-- .. index:: BSP_DEFAULT_UNIFIED_WORK_AREAS
-
- ``BSP_DEFAULT_UNIFIED_WORK_AREAS`` is defined when the BSP
- recommends that the unified work areas configuration should always
- be used. This is desirable when the BSP is known to always have very
- little RAM and thus saving memory by any means is desirable.
-
-set_vector() - Install an Interrupt Vector
-==========================================
-
-On targets with Simple Vectored Interrupts, the BSP must provide
-an implementation of the ``set_vector`` routine. This routine is
-responsible for installing an interrupt vector. It invokes the support
-routines necessary to install an interrupt handler as either a "raw"
-or an RTEMS interrupt handler. Raw handlers bypass the RTEMS interrupt
-structure and are responsible for saving and restoring all their own
-registers. Raw handlers are useful for handling traps, debug vectors,
-etc..
-
-The ``set_vector`` routine is a central place to perform interrupt
-controller manipulation and encapsulate that information. It is usually
-implemented as follows:
-
-.. code:: c
-
- rtems_isr_entry set_vector( /* returns old vector \*/
- rtems_isr_entry handler, /* isr routine \*/
- rtems_vector_number vector, /* vector number \*/
- int type /* RTEMS or RAW intr \*/
- )
- {
- if the type is RAW
- install the raw vector
- else
- use rtems_interrupt_catch to install the vector
- perform any interrupt controller necessary to unmask
- the interrupt source
- return the previous handler
- }
-
-*NOTE:* The i386, PowerPC and ARM ports use a Programmable
-Interrupt Controller model which does not require the BSP to implement``set_vector``. BSPs for these architectures must provide a different
-set of support routines.
-
-Interrupt Delay Profiling
-=========================
-
-The RTEMS profiling needs support by the BSP for the interrupt delay times. In
-case profiling is enabled via the RTEMS build configuration option``--enable-profiling`` (in this case the pre-processor symbol``RTEMS_PROFILING`` is defined) a BSP may provide data for the interrupt
-delay times. The BSP can feed interrupt delay times with the``_Profiling_Update_max_interrupt_delay()`` function
-(``#include <rtems/score/profiling.h>``). For an example please have a look
-at ``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``.
-
-Programmable Interrupt Controller API
-=====================================
-
-A BSP can use the PIC API to install Interrupt Service Routines through
-a set of generic methods. In order to do so, the header files
-libbsp/shared/include/irq-generic.h and libbsp/shared/include/irq-info.h
-must be included by the bsp specific irq.h file present in the include/
-directory. The irq.h acts as a BSP interrupt support configuration file which
-is used to define some important MACROS. It contains the declarations for
-any required global functions like bsp_interrupt_dispatch(). Thus later on,
-every call to the PIC interface requires including <bsp/irq.h>
-
-The generic interrupt handler table is intitalized by invoking the``bsp_interrupt_initialize()`` method from bsp_start() in the bspstart.c
-file which sets up this table to store the ISR addresses, whose size is based
-on the definition of macros, BSP_INTERRUPT_VECTOR_MIN & BSP_INTERRUPT_VECTOR_MAX
-in include/bsp.h
-
-For the generic handler table to properly function, some bsp specific code is
-required, that should be present in irq/irq.c . The bsp-specific functions required
-to be writen by the BSP developer are :
-
-- .. index:: bsp_interrupt_facility_initialize()
-
- ``bsp_interrupt_facility_initialize()`` contains bsp specific interrupt
- initialization code(Clear Pending interrupts by modifying registers, etc.).
- This method is called from bsp_interrupt_initialize() internally while setting up
- the table.
-
-- .. index:: bsp_interrupt_handler_default()
-
- ``bsp_interrupt_handler_default()`` acts as a fallback handler when
- no ISR address has been provided corresponding to a vector in the table.
-
-- .. index:: bsp_interrupt_dispatch()
-
- ``bsp_interrupt_dispatch()`` service the ISR by handling
- any bsp specific code & calling the generic method bsp_interrupt_handler_dispatch()
- which in turn services the interrupt by running the ISR after looking it up in
- the table. It acts as an entry to the interrupt switchboard, since the bsp
- branches to this function at the time of occurrence of an interrupt.
-
-- .. index:: bsp_interrupt_vector_enable()
-
- ``bsp_interrupt_vector_enable()`` enables interrupts and is called in
- irq-generic.c while setting up the table.
-
-- .. index:: bsp_interrupt_vector_disable()
-
- ``bsp_interrupt_vector_disable()`` disables interrupts and is called in
- irq-generic.c while setting up the table & during other important parts.
-
-An interrupt handler is installed or removed with the help of the following functions :
-
-.. code:: c
-
- rtems_status_code rtems_interrupt_handler_install( /* returns status code \*/
- rtems_vector_number vector, /* interrupt vector \*/
- const char \*info, /* custom identification text \*/
- rtems_option options, /* Type of Interrupt \*/
- rtems_interrupt_handler handler, /* interrupt handler \*/
- void \*arg /* parameter to be passed to handler at the time of invocation \*/
- )
- rtems_status_code rtems_interrupt_handler_remove( /* returns status code \*/
- rtems_vector_number vector, /* interrupt vector \*/
- rtems_interrupt_handler handler, /* interrupt handler \*/
- void \*arg /* parameter to be passed to handler \*/
- )
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Ada95 Interrupt Support
-#######################
-
-Introduction
-============
-
-This chapter describes what is required to enable Ada interrupt
-and error exception handling when using GNAT over RTEMS.
-
-The GNAT Ada95 interrupt support RTEMS was developed by
-Jiri Gaisler <jgais@ws.estec.esa.nl> who also wrote this
-chapter.
-
-Mapping Interrupts to POSIX Signals
-===================================
-
-In Ada95, interrupts can be attached with the interrupt_attach pragma.
-For most systems, the gnat run-time will use POSIX signal to implement
-the interrupt handling, mapping one signal per interrupt. For interrupts
-to be propagated to the attached Ada handler, the corresponding signal
-must be raised when the interrupt occurs.
-
-The same mechanism is used to generate Ada error exceptions.
-Three error exceptions are defined: program, constraint and storage
-error. These are generated by raising the predefined signals: SIGILL,
-SIGFPE and SIGSEGV. These signals should be raised when a spurious
-or erroneous trap occurs.
-
-To enable gnat interrupt and error exception support for a particular
-BSP, the following has to be done:
-
-# Write an interrupt/trap handler that will raise the corresponding
- signal depending on the interrupt/trap number.
-
-# Install the interrupt handler for all interrupts/traps that will be
- handled by gnat (including spurious).
-
-# At startup, gnat calls ``__gnat_install_handler()``. The BSP
- must provide this function which installs the interrupt/trap handlers.
-
-Which CPU-interrupt will generate which signal is implementation
-defined. There are 32 POSIX signals (1 - 32), and all except the
-three error signals (SIGILL, SIGFPE and SIGSEGV) can be used. I
-would suggest to use the upper 16 (17 - 32) which do not
-have an assigned POSIX name.
-
-Note that the pragma interrupt_attach will only bind a signal
-to a particular Ada handler - it will not unmask the
-interrupt or do any other things to enable it. This have to be
-done separately, typically by writing various device register.
-
-Example Ada95 Interrupt Program
-===============================
-
-An example program (``irq_test``) is included in the
-Ada examples package to show how interrupts can be handled
-in Ada95. Note that generation of the test interrupt
-(``irqforce.c``) is BSP specific and must be edited.
-
-NOTE: The ``irq_test`` example was written for the SPARC/ERC32
-BSP.
-
-Version Requirements
-====================
-
-With RTEMS 4.0, a patch was required to psignal.c in RTEMS
-sources (to correct a bug associated to the default action of
-signals 15-32). The SPARC/ERC32 RTEMS BSP includes the``gnatsupp`` subdirectory that can be used as an example
-for other BSPs.
-
-With GNAT 3.11p, a patch is required for ``a-init.c`` to invoke
-the BSP specific routine that installs the exception handlers.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Initialization Code
-###################
-
-Introduction
-============
-
-The initialization code is the first piece of code executed when there’s a
-reset/reboot. Its purpose is to initialize the board for the application.
-This chapter contains a narrative description of the initialization
-process followed by a description of each of the files and routines
-commonly found in the BSP related to initialization. The remainder of
-this chapter covers special issues which require attention such
-as interrupt vector table and chip select initialization.
-
-Most of the examples in this chapter will be based on the SPARC/ERC32 and
-m68k/gen68340 BSP initialization code. Like most BSPs, the initialization
-for these BSP is divided into two subdirectories under the BSP source
-directory. The BSP source code for these BSPs is in the following
-directories:
-.. code:: c
-
- c/src/lib/libbsp/m68k/gen68340
- c/src/lib/libbsp/sparc/erc32
-
-Both BSPs contain startup code written in assembly language and C.
-The gen68340 BSP has its early initialization start code in the``start340`` subdirectory and its C startup code in the ``startup``
-directory. In the ``start340`` directory are two source files.
-The file ``startfor340only.s`` is the simpler of these files as it only
-has initialization code for a MC68340 board. The file ``start340.s``
-contains initialization for a 68349 based board as well.
-
-Similarly, the ERC32 BSP has startup code written in assembly language
-and C. However, this BSP shares this code with other SPARC BSPs.
-Thus the ``Makefile.am`` explicitly references the following files
-for this functionality.
-.. code:: c
-
- ../../sparc/shared/start.S
-
-*NOTE:* In most BSPs, the directory named ``start340`` in the
-gen68340 BSP would be simply named ``start`` or start followed by a
-BSP designation.
-
-Required Global Variables
-=========================
-
-Although not strictly part of initialization, there are a few global
-variables assumed to exist by reusable device drivers. These global
-variables should only defined by the BSP when using one of these device
-drivers.
-
-The BSP author probably should be aware of the ``Configuration``
-Table structure generated by ``<rtems/confdefs.h>`` during debug but
-should not explicitly reference it in the source code. There are helper
-routines provided by RTEMS to access individual fields.
-
-In older RTEMS versions, the BSP included a number of required global
-variables. We have made every attempt to eliminate these in the interest
-of simplicity.
-
-Board Initialization
-====================
-
-This section describes the steps an application goes through from the
-time the first BSP code is executed until the first application task
-executes. The following figure illustrates the program flow during
-this sequence:
-
-IMAGE NOT AVAILABLE IN ASCII VERSION
-
-The above figure illustrates the flow from assembly language start code
-to the shared ``bootcard.c`` framework then through the C Library,
-RTEMS, device driver initialization phases, and the context switch
-to the first application task. After this, the application executes
-until it calls ``exit``, ``rtems_shutdown_executive``, or some
-other normal termination initiating routine and a fatal system state is
-reached. The optional ``bsp_fatal_extension`` initial extension can perform
-BSP specific system termination.
-
-The routines invoked during this will be discussed and their location
-in the RTEMS source tree pointed out as we discuss each.
-
-Start Code - Assembly Language Initialization
----------------------------------------------
-
-The assembly language code in the directory ``start`` is the first part
-of the application to execute. It is responsible for initializing the
-processor and board enough to execute the rest of the BSP. This includes:
-
-- initializing the stack
-
-- zeroing out the uninitialized data section ``.bss``
-
-- disabling external interrupts
-
-- copy the initialized data from ROM to RAM
-
-The general rule of thumb is that the start code in assembly should
-do the minimum necessary to allow C code to execute to complete the
-initialization sequence.
-
-The initial assembly language start code completes its execution by
-invoking the shared routine ``boot_card()``.
-
-The label (symbolic name) associated with the starting address of the
-program is typically called ``start``. The start object file is the
-first object file linked into the program image so it is ensured that
-the start code is at offset 0 in the ``.text`` section. It is the
-responsibility of the linker script in conjunction with the compiler
-specifications file to put the start code in the correct location in
-the application image.
-
-boot_card() - Boot the Card
----------------------------
-
-The ``boot_card()`` is the first C code invoked. This file is the
-core component in the RTEMS BSP Initialization Framework and provides
-the proper sequencing of initialization steps for the BSP, RTEMS and
-device drivers. All BSPs use the same shared version of ``boot_card()``
-which is located in the following file:
-.. code:: c
-
- c/src/lib/libbsp/shared/bootcard.c
-
-The ``boot_card()`` routine performs the following functions:
-
-- It disables processor interrupts.
-
-- It sets the command line argument variables
- for later use by the application.
-
-- It invokes the BSP specific routine ``bsp_work_area_initialize()``
- which is supposed to initialize the RTEMS Workspace and the C Program Heap.
- Usually the default implementation in``c/src/lib/libbsp/shared/bspgetworkarea.c`` should be sufficient. Custom
- implementations can use ``bsp_work_area_initialize_default()`` or``bsp_work_area_initialize_with_table()`` available as inline functions from``#include <bsp/bootcard.h>``.
-
-- It invokes the BSP specific routine ``bsp_start()`` which is
- written in C and thus able to perform more advanced initialization.
- Often MMU, bus and interrupt controller initialization occurs here. Since the
- RTEMS Workspace and the C Program Heap was already initialized by``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc.
-
-- It invokes the RTEMS directive``rtems_initialize_data_structures()`` to initialize the RTEMS
- executive to a state where objects can be created but tasking is not
- enabled.
-
-- It invokes the BSP specific routine ``bsp_libc_init()`` to initialize
- the C Library. Usually the default implementation in``c/src/lib/libbsp/shared/bsplibc.c`` should be sufficient.
-
-- It invokes the RTEMS directive``rtems_initialize_before_drivers()`` to initialize the MPCI Server
- thread in a multiprocessor configuration and execute API specific
- extensions.
-
-- It invokes the BSP specific routine ``bsp_predriver_hook``. For
- most BSPs, the implementation of this routine does nothing.
-
-- It invokes the RTEMS directive``rtems_initialize_device_drivers()`` to initialize the statically
- configured set of device drivers in the order they were specified in
- the Configuration Table.
-
-- It invokes the BSP specific routine ``bsp_postdriver_hook``. For
- most BSPs, the implementation of this routine does nothing. However, some
- BSPs use this hook and perform some initialization which must be done at
- this point in the initialization sequence. This is the last opportunity
- for the BSP to insert BSP specific code into the initialization sequence.
-
-- It invokes the RTEMS directive``rtems_initialize_start_multitasking()``
- which initiates multitasking and performs a context switch to the
- first user application task and may enable interrupts as a side-effect of
- that context switch. The context switch saves the executing context. The
- application runs now. The directive rtems_shutdown_executive() will return
- to the saved context. The exit() function will use this directive.
- After a return to the saved context a fatal system state is reached. The
- fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
- passed to rtems_shutdown_executive().
- The enabling of interrupts during the first context switch is often the source
- for fatal errors during BSP development because the BSP did not clear and/or
- disable all interrupt sources and a spurious interrupt will occur.
- When in the context of the first task but before its body has been
- entered, any C++ Global Constructors will be invoked.
-
-That’s it. We just went through the entire sequence.
-
-bsp_work_area_initialize() - BSP Specific Work Area Initialization
-------------------------------------------------------------------
-
-This is the first BSP specific C routine to execute during system
-initialization. It must initialize the support for allocating memory from the
-C Program Heap and RTEMS Workspace commonly referred to as the work areas.
-Many BSPs place the work areas at the end of RAM although this is certainly not
-a requirement. Usually the default implementation in:file:`c/src/lib/libbsp/shared/bspgetworkarea.c` should be sufficient. Custom
-implementations can use ``bsp_work_area_initialize_default()`` or``bsp_work_area_initialize_with_table()`` available as inline functions from``#include <bsp/bootcard.h>``.
-
-bsp_start() - BSP Specific Initialization
------------------------------------------
-
-This is the second BSP specific C routine to execute during system
-initialization. It is called right after ``bsp_work_area_initialize()``.
-The ``bsp_start()`` routine often performs required fundamental hardware
-initialization such as setting bus controller registers that do not have a
-direct impact on whether or not C code can execute. The interrupt controllers
-are usually initialized here. The source code for this routine is usually
-found in the file :file:`c/src/lib/libbsp/${CPU}/${BSP}/startup/bspstart.c`.
-It is not allowed to create any operating system objects, e.g. RTEMS
-semaphores.
-
-After completing execution, this routine returns to the ``boot_card()``
-routine. In case of errors, the initialization should be terminated via``bsp_fatal()``.
-
-bsp_predriver_hook() - BSP Specific Predriver Hook
---------------------------------------------------
-
-The ``bsp_predriver_hook()`` method is the BSP specific routine that is
-invoked immediately before the the device drivers are initialized. RTEMS
-initialization is complete but interrupts and tasking are disabled.
-
-The BSP may use the shared version of this routine which is empty.
-Most BSPs do not provide a specific implementation of this callback.
-
-Device Driver Initialization
-----------------------------
-
-At this point in the initialization sequence, the initialization
-routines for all of the device drivers specified in the Device
-Driver Table are invoked. The initialization routines are invoked
-in the order they appear in the Device Driver Table.
-
-The Driver Address Table is part of the RTEMS Configuration Table. It
-defines device drivers entry points (initialization, open, close, read,
-write, and control). For more information about this table, please
-refer to the *Configuring a System* chapter in the*RTEMS Application C User’s Guide*.
-
-The RTEMS initialization procedure calls the initialization function for
-every driver defined in the RTEMS Configuration Table (this allows
-one to include only the drivers needed by the application).
-
-All these primitives have a major and a minor number as arguments:
-
-- the major number refers to the driver type,
-
-- the minor number is used to control two peripherals with the same
- driver (for instance, we define only one major number for the serial
- driver, but two minor numbers for channel A and B if there are two
- channels in the UART).
-
-RTEMS Postdriver Callback
--------------------------
-
-The ``bsp_postdriver_hook()`` BSP specific routine is invoked
-immediately after the the device drivers and MPCI are initialized.
-Interrupts and tasking are disabled.
-
-Most BSPs use the shared implementation of this routine which is responsible for opening the device ``/dev/console`` for standard input, output and error if the application has configured the Console Device Driver. This file is located at:
-.. code:: c
-
- c/src/lib/libbsp/shared/bsppost.c
-
-The Interrupt Vector Table
-==========================
-
-The Interrupt Vector Table is called different things on different
-processor families but the basic functionality is the same. Each
-entry in the Table corresponds to the handler routine for a particular
-interrupt source. When an interrupt from that source occurs, the
-specified handler routine is invoked. Some context information is
-saved by the processor automatically when this happens. RTEMS saves
-enough context information so that an interrupt service routine
-can be implemented in a high level language.
-
-On some processors, the Interrupt Vector Table is at a fixed address. If
-this address is in RAM, then usually the BSP only has to initialize
-it to contain pointers to default handlers. If the table is in ROM,
-then the application developer will have to take special steps to
-fill in the table.
-
-If the base address of the Interrupt Vector Table can be dynamically
-changed to an arbitrary address, then the RTEMS port to that processor
-family will usually allocate its own table and install it. For example,
-on some members of the Motorola MC68xxx family, the Vector Base Register
-(``vbr``) contains this base address.
-
-Interrupt Vector Table on the gen68340 BSP
-------------------------------------------
-
-The gen68340 BSP provides a default Interrupt Vector Table in the
-file ``$BSP_ROOT/start340/start340.s``. After the ``entry``
-label is the definition of space reserved for the table of
-interrupts vectors. This space is assigned the symbolic name
-of ``__uhoh`` in the ``gen68340`` BSP.
-
-At ``__uhoh`` label is the default interrupt handler routine. This
-routine is only called when an unexpected interrupts is raised. One can
-add their own routine there (in that case there’s a call to a routine -
-$BSP_ROOT/startup/dumpanic.c - that prints which address caused the
-interrupt and the contents of the registers, stack, etc.), but this should
-not return.
-
-Chip Select Initialization
-==========================
-
-When the microprocessor accesses a memory area, address decoding is
-handled by an address decoder, so that the microprocessor knows which
-memory chip(s) to access. The following figure illustrates this:
-
-.. code:: c
-
- +-------------------+
- ------------| |
- ------------| \|------------
- ------------| Address \|------------
- ------------| Decoder \|------------
- ------------| \|------------
- ------------| |
- +-------------------+
- CPU Bus Chip Select
-
-The Chip Select registers must be programmed such that they match
-the ``linkcmds`` settings. In the gen68340 BSP, ROM and RAM
-addresses can be found in both the ``linkcmds`` and initialization
-code, but this is not a great way to do this. It is better to
-define addresses in the linker script.
-
-Integrated Processor Registers Initialization
-=============================================
-
-The CPUs used in many embedded systems are highly complex devices
-with multiple peripherals on the CPU itself. For these devices,
-there are always some specific integrated processor registers
-that must be initialized. Refer to the processors’ manuals for
-details on these registers and be VERY careful programming them.
-
-Data Section Recopy
-===================
-
-The next initialization part can be found in``$BSP340_ROOT/start340/init68340.c``. First the Interrupt
-Vector Table is copied into RAM, then the data section recopy is initiated
-(_CopyDataClearBSSAndStart in ``$BSP340_ROOT/start340/startfor340only.s``).
-
-This code performs the following actions:
-
-- copies the .data section from ROM to its location reserved in RAM
- (see `Initialized Data`_ for more details about this copy),
-
-- clear ``.bss`` section (all the non-initialized
- data will take value 0).
-
-The RTEMS Configuration Table
-=============================
-
-The RTEMS configuration table contains the maximum number of objects RTEMS
-can handle during the application (e.g. maximum number of tasks,
-semaphores, etc.). It’s used to allocate the size for the RTEMS inner data
-structures.
-
-The RTEMS configuration table is application dependent, which means that
-one has to provide one per application. It is usually defined by defining
-macros and including the header file ``<rtems/confdefs.h>``. In simple
-applications such as the tests provided with RTEMS, it is commonly found
-in the main module of the application. For more complex applications,
-it may be in a file by itself.
-
-The header file ``<rtems/confdefs.h>`` defines a constant table
-named ``Configuration``. With RTEMS 4.8 and older, it was accepted
-practice for the BSP to copy this table into a modifiable copy named``BSP_Configuration``. This copy of the table was modified to define
-the base address of the RTEMS Executive Workspace as well as to reflect
-any BSP and device driver requirements not automatically handled by the
-application. In 4.9 and newer, we have eliminated the BSP copies of the
-configuration tables and are making efforts to make the configuration
-information generated by ``<rtems/confdefs.h>`` constant and read only.
-
-For more information on the RTEMS Configuration Table, refer to the*RTEMS Application C User’s Guide*.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Console Driver
-##############
-
-Introduction
-============
-
-This chapter describes the operation of a console driver using
-the RTEMS POSIX Termios support. Traditionally RTEMS has referred
-to all serial device drivers as console device drivers. A
-console driver can be used to do raw data processing in addition
-to the "normal" standard input and output device functions required
-of a console.
-
-The serial driver may be called as the consequence of a C Library
-call such as ``printf`` or ``scanf`` or directly via the``read`` or ``write`` system calls.
-There are two main functioning modes:
-
-- console: formatted input/output, with special characters (end of
- line, tabulations, etc.) recognition and processing,
-
-- raw: permits raw data processing.
-
-One may think that two serial drivers are needed to handle these two types
-of data, but Termios permits having only one driver.
-
-Termios
-=======
-
-Termios is a standard for terminal management, included in the POSIX
-1003.1b standard. As part of the POSIX and Open Group Single UNIX
-Specification, is commonly provided on UNIX implementations. The
-Open Group has the termios portion of the POSIX standard online
-at http://opengroup.org/onlinepubs/007908775/xbd/termios.html.
-The requirements for the ``<termios.h>`` file are also provided
-and are at http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html.
-
-Having RTEMS support for Termios is beneficial because:
-
-- from the user’s side because it provides standard primitive operations
- to access the terminal and change configuration settings. These operations
- are the same under UNIX and RTEMS.
-
-- from the BSP developer’s side because it frees the
- developer from dealing with buffer states and mutual exclusions on them.
- Early RTEMS console device drivers also did their own special
- character processing.
-
-- it is part of an internationally recognized standard.
-
-- it makes porting code from other environments easier.
-
-Termios support includes:
-
-- raw and console handling,
-
-- blocking or non-blocking characters receive, with or without
- Timeout.
-
-At this time, RTEMS documentation does not include a thorough discussion
-of the Termios functionality. For more information on Termios,
-type ``man termios`` on a Unix box or point a web browser
-athttp://www.freebsd.org/cgi/man.cgi.
-
-Driver Functioning Modes
-========================
-
-There are generally three main functioning modes for an UART (Universal
-Asynchronous Receiver-Transmitter, i.e. the serial chip):
-
-- polled mode
-
-- interrupt driven mode
-
-- task driven mode
-
-In polled mode, the processor blocks on sending/receiving characters.
-This mode is not the most efficient way to utilize the UART. But
-polled mode is usually necessary when one wants to print an
-error message in the event of a fatal error such as a fatal error
-in the BSP. This is also the simplest mode to
-program. Polled mode is generally preferred if the serial port is
-to be used primarily as a debug console. In a simple polled driver,
-the software will continuously check the status of the UART when
-it is reading or writing to the UART. Termios improves on this
-by delaying the caller for 1 clock tick between successive checks
-of the UART on a read operation.
-
-In interrupt driven mode, the processor does not block on sending/receiving
-characters. Data is buffered between the interrupt service routine
-and application code. Two buffers are used to insulate the application
-from the relative slowness of the serial device. One of the buffers is
-used for incoming characters, while the other is used for outgoing characters.
-
-An interrupt is raised when a character is received by the UART.
-The interrupt subroutine places the incoming character at the end
-of the input buffer. When an application asks for input,
-the characters at the front of the buffer are returned.
-
-When the application prints to the serial device, the outgoing characters
-are placed at the end of the output buffer. The driver will place
-one or more characters in the UART (the exact number depends on the UART)
-An interrupt will be raised when all the characters have been transmitted.
-The interrupt service routine has to send the characters
-remaining in the output buffer the same way. When the transmitting side
-of the UART is idle, it is typically necessary to prime the transmitter
-before the first interrupt will occur.
-
-The task driven mode is similar to interrupt driven mode, but the actual data
-processing is done in dedicated tasks instead of interrupt routines.
-
-Serial Driver Functioning Overview
-==================================
-
-The following Figure shows how a Termios driven serial driver works:
-Figure not included in ASCII version
-
-The following list describes the basic flow.
-
-- the application programmer uses standard C library call (printf,
- scanf, read, write, etc.),
-
-- C library (ctx.g. RedHat (formerly Cygnus) Newlib) calls
- the RTEMS system call interface. This code can be found in the:file:`cpukit/libcsupport/src` directory.
-
-- Glue code calls the serial driver entry routines.
-
-Basics
-------
-
-The low-level driver API changed between RTEMS 4.10 and RTEMS 4.11. The legacy
-callback API is still supported, but its use is discouraged. The following
-functions are deprecated:
-
-- ``rtems_termios_open()`` - use ``rtems_termios_device_open()`` in
- combination with ``rtems_termios_device_install()`` instead.
-
-- ``rtems_termios_close()`` - use ``rtems_termios_device_close()``
- instead.
-
-This manual describes the new API. A new console driver should consist of
-three parts.
-
-# The basic console driver functions using the Termios support. Add this
- the BSPs Makefile.am:
-
- .. code:: c
-
- [...]
- libbsp_a_SOURCES += ../../shared/console-termios.c
- \[...]
-
-# A general serial module specific low-level driver providing the handler
- table for the Termios ``rtems_termios_device_install()`` function. This
- low-level driver could be used for more than one BSP.
-
-# A BSP specific initialization routine ``console_initialize()``, that
- calls ``rtems_termios_device_install()`` providing a low-level driver
- context for each installed device.
-
-You need to provide a device handler structure for the Termios device
-interface. The functions are described later in this chapter. The first open
-and set attributes handler return a boolean status to indicate success (true)
-or failure (false). The polled read function returns an unsigned character in
-case one is available or minus one otherwise.
-
-If you want to use polled IO it should look like the following. Termios must
-be told the addresses of the handler that are to be used for simple character
-IO, i.e. pointers to the ``my_driver_poll_read()`` and``my_driver_poll_write()`` functions described later in `Termios and Polled IO`_.
-
-.. code:: c
-
- const rtems_termios_handler my_driver_handler_polled = {
- .first_open = my_driver_first_open,
- .last_close = my_driver_last_close,
- .poll_read = my_driver_poll_read,
- .write = my_driver_poll_write,
- .set_attributes = my_driver_set_attributes,
- .stop_remote_tx = NULL,
- .start_remote_tx = NULL,
- .mode = TERMIOS_POLLED
- }
-
-For an interrupt driven implementation you need the following. The driver
-functioning is quite different in this mode. There is no device driver read
-handler to be passed to Termios. Indeed a ``console_read()`` call returns the
-contents of Termios input buffer. This buffer is filled in the driver
-interrupt subroutine, see also `Termios and Interrupt Driven IO`_. The driver
-is responsible for providing a pointer to the``my_driver_interrupt_write()`` function.
-
-.. code:: c
-
- const rtems_termios_handler my_driver_handler_interrupt = {
- .first_open = my_driver_first_open,
- .last_close = my_driver_last_close,
- .poll_read = NULL,
- .write = my_driver_interrupt_write,
- .set_attributes = my_driver_set_attributes,
- .stopRemoteTx = NULL,
- .stop_remote_tx = NULL,
- .start_remote_tx = NULL,
- .mode = TERMIOS_IRQ_DRIVEN
- };
-
-You can also provide hander for remote transmission control. This
-is not covered in this manual, so they are set to ``NULL`` in the above
-examples.
-
-The low-level driver should provide a data structure for its device context.
-The initialization routine must provide a context for each installed device via``rtems_termios_device_install()``. For simplicity of the console
-initialization example the device name is also present. Her is an example header file.
-.. code:: c
-
- #ifndef MY_DRIVER_H
- #define MY_DRIVER_H
- #include <rtems/termiostypes.h>
- #include <some-chip-header.h>
- /* Low-level driver specific data structure \*/
- typedef struct {
- rtems_termios_device_context base;
- const char \*device_name;
- volatile module_register_block \*regs;
- /* More stuff \*/
- } my_driver_context;
- extern const rtems_termios_handler my_driver_handler_polled;
- extern const rtems_termios_handler my_driver_handler_interrupt;
- #endif /* MY_DRIVER_H \*/
-
-
-Termios and Polled IO
----------------------
-
-The following handler are provided by the low-level driver and invoked by
-Termios for simple character IO.
-
-The ``my_driver_poll_write()`` routine is responsible for writing ``n``
-characters from ``buf`` to the serial device specified by ``tty``.
-.. code:: c
-
- static void my_driver_poll_write(
- rtems_termios_device_context \*base,
- const char \*buf,
- size_t n
- )
- {
- my_driver_context \*ctx = (my_driver_context \*) base;
- size_t i;
- /* Write \*/
- for (i = 0; i < n; ++i) {
- my_driver_write_char(ctx, buf[i]);
- }
- }
-
-The ``my_driver_poll_read`` routine is responsible for reading a single
-character from the serial device specified by ``tty``. If no character is
-available, then the routine should return minus one.
-.. code:: c
-
- static int my_driver_poll_read(rtems_termios_device_context \*base)
- {
- my_driver_context \*ctx = (my_driver_context \*) base;
- /* Check if a character is available \*/
- if (my_driver_can_read_char(ctx)) {
- /* Return the character \*/
- return my_driver_read_char(ctx);
- } else {
- /* Return an error status \*/
- return -1;
- }
- }
-
-Termios and Interrupt Driven IO
--------------------------------
-
-The UART generally generates interrupts when it is ready to accept or to emit a
-number of characters. In this mode, the interrupt subroutine is the core of
-the driver.
-
-The ``my_driver_interrupt_handler()`` is responsible for processing
-asynchronous interrupts from the UART. There may be multiple interrupt
-handlers for a single UART. Some UARTs can generate a unique interrupt vector
-for each interrupt source such as a character has been received or the
-transmitter is ready for another character.
-
-In the simplest case, the ``my_driver_interrupt_handler()`` will have to check
-the status of the UART and determine what caused the interrupt. The following
-describes the operation of an ``my_driver_interrupt_handler`` which has to
-do this:
-.. code:: c
-
- static void my_driver_interrupt_handler(
- rtems_vector_number vector,
- void \*arg
- )
- {
- rtems_termios_tty \*tty = arg;
- my_driver_context \*ctx = rtems_termios_get_device_context(tty);
- char buf[N];
- size_t n;
- /*
- * Check if we have received something. The function reads the
- * received characters from the device and stores them in the
- * buffer. It returns the number of read characters.
- \*/
- n = my_driver_read_received_chars(ctx, buf, N);
- if (n > 0) {
- /* Hand the data over to the Termios infrastructure \*/
- rtems_termios_enqueue_raw_characters(tty, buf, n);
- }
- /*
- * Check if we have something transmitted. The functions returns
- * the number of transmitted characters since the last write to the
- * device.
- \*/
- n = my_driver_transmitted_chars(ctx);
- if (n > 0) {
- /*
- * Notify Termios that we have transmitted some characters. It
- * will call now the interrupt write function if more characters
- * are ready for transmission.
- \*/
- rtems_termios_dequeue_characters(tty, n);
- }
- }
-
-The ``my_driver_interrupt_write()`` function is responsible for telling the
-device that the ``n`` characters at ``buf`` are to be transmitted. It
-the value ``n`` is zero to indicate that no more characters are to send.
-The driver can disable the transmit interrupts now. This routine is invoked
-either from task context with disabled interrupts to start a new transmission
-process with exactly one character in case of an idle output state or from the
-interrupt handler to refill the transmitter. If the routine is invoked to
-start the transmit process the output state will become busy and Termios starts
-to fill the output buffer. If the transmit interrupt arises before Termios was
-able to fill the transmit buffer you will end up with one interrupt per
-character.
-.. code:: c
-
- static void my_driver_interrupt_write(
- rtems_termios_device_context \*base,
- const char \*buf,
- size_t n
- )
- {
- my_driver_context \*ctx = (my_driver_context \*) base;
- /*
- * Tell the device to transmit some characters from buf (less than
- * or equal to n). When the device is finished it should raise an
- * interrupt. The interrupt handler will notify Termios that these
- * characters have been transmitted and this may trigger this write
- * function again. You may have to store the number of outstanding
- * characters in the device data structure.
- \*/
- /*
- * Termios will set n to zero to indicate that the transmitter is
- * now inactive. The output buffer is empty in this case. The
- * driver may disable the transmit interrupts now.
- \*/
- }
-
-Initialization
---------------
-
-The BSP specific driver initialization is called once during the RTEMS
-initialization process.
-
-The ``console_initialize()`` function may look like this:
-.. code:: c
-
- #include <my-driver.h>
- #include <rtems/console.h>
- #include <bsp.h>
- #include <bsp/fatal.h>
- static my_driver_context driver_context_table[M] = { /* Some values \*/ };
- rtems_device_driver console_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg
- )
- {
- rtems_status_code sc;
- #ifdef SOME_BSP_USE_INTERRUPTS
- const rtems_termios_handler \*handler = &my_driver_handler_interrupt;
- #else
- const rtems_termios_handler \*handler = &my_driver_handler_polled;
- #endif
- /*
- * Initialize the Termios infrastructure. If Termios has already
- * been initialized by another device driver, then this call will
- * have no effect.
- \*/
- rtems_termios_initialize();
- /* Initialize each device \*/
- for (
- minor = 0;
- minor < RTEMS_ARRAY_SIZE(driver_context_table);
- ++minor
- ) {
- my_driver_context \*ctx = &driver_context_table[minor];
- /*
- * Install this device in the file system and Termios. In order
- * to use the console (i.e. being able to do printf, scanf etc.
- * on stdin, stdout and stderr), one device must be registered as
- * "/dev/console" (CONSOLE_DEVICE_NAME).
- \*/
- sc = rtems_termios_device_install(
- ctx->device_name,
- major,
- minor,
- handler,
- NULL,
- ctx
- );
- if (sc != RTEMS_SUCCESSFUL) {
- bsp_fatal(SOME_BSP_FATAL_CONSOLE_DEVICE_INSTALL);
- }
- }
- return RTEMS_SUCCESSFUL;
- }
-
-Opening a serial device
------------------------
-
-The ``console_open()`` function provided by :file:`console-termios.c` is
-called whenever a serial device is opened. The device registered as``"/dev/console"`` (``CONSOLE_DEVICE_NAME``) is opened automatically
-during RTEMS initialization. For instance, if UART channel 2 is registered as``"/dev/tty1"``, the ``console_open()`` entry point will be called as the
-result of an ``fopen("/dev/tty1", mode)`` in the application.
-
-During the first open of the device Termios will call the``my_driver_first_open()`` handler.
-.. code:: c
-
- static bool my_driver_first_open(
- rtems_termios_tty \*tty,
- rtems_termios_device_context \*base,
- struct termios \*term,
- rtems_libio_open_close_args_t \*args
- )
- {
- my_driver_context \*ctx = (my_driver_context \*) base;
- rtems_status_code sc;
- bool ok;
- /*
- * You may add some initialization code here.
- \*/
- /*
- * Sets the initial baud rate. This should be set to the value of
- * the boot loader. This function accepts only exact Termios baud
- * values.
- \*/
- sc = rtems_termios_set_initial_baud(tty, MY_DRIVER_BAUD_RATE);
- if (sc != RTEMS_SUCCESSFUL) {
- /* Not a valid Termios baud \*/
- }
- /*
- * Alternatively you can set the best baud.
- \*/
- rtems_termios_set_best_baud(term, MY_DRIVER_BAUD_RATE);
- /*
- * To propagate the initial Termios attributes to the device use
- * this.
- \*/
- ok = my_driver_set_attributes(base, term);
- if (!ok) {
- /* This is bad \*/
- }
- /*
- * Return true to indicate a successful set attributes, and false
- * otherwise.
- \*/
- return true;
- }
-
-Closing a Serial Device
------------------------
-
-The ``console_close()`` provided by :file:`console-termios.c` is invoked when
-the serial device is to be closed. This entry point corresponds to the device
-driver close entry point.
-
-Termios will call the ``my_driver_last_close()`` handler if the last close
-happens on the device.
-.. code:: c
-
- static void my_driver_last_close(
- rtems_termios_tty \*tty,
- rtems_termios_device_context \*base,
- rtems_libio_open_close_args_t \*args
- )
- {
- my_driver_context \*ctx = (my_driver_context \*) base;
- /*
- * The driver may do some cleanup here.
- \*/
- }
-
-Reading Characters from a Serial Device
----------------------------------------
-
-The ``console_read()`` provided by :file:`console-termios.c` is invoked when
-the serial device is to be read from. This entry point corresponds to the
-device driver read entry point.
-
-Writing Characters to a Serial Device
--------------------------------------
-
-The ``console_write()`` provided by :file:`console-termios.c` is invoked when
-the serial device is to be written to. This entry point corresponds to the
-device driver write entry point.
-
-Changing Serial Line Parameters
--------------------------------
-
-The ``console_control()`` provided by :file:`console-termios.c` is invoked
-when the line parameters for a particular serial device are to be changed.
-This entry point corresponds to the device driver IO control entry point.
-
-The application writer is able to control the serial line configuration with
-Termios calls (such as the ``ioctl()`` command, see the Termios
-documentation for more details). If the driver is to support dynamic
-configuration, then it must have the ``console_control()`` piece of code.
-Basically ``ioctl()`` commands call ``console_control()`` with the serial
-line configuration in a Termios defined data structure.
-
-The driver is responsible for reinitializing the device with the correct
-settings. For this purpose Termios calls the ``my_driver_set_attributes()``
-handler.
-.. code:: c
-
- static bool my_driver_set_attributes(
- rtems_termios_device_context \*base,
- const struct termios \*term
- )
- {
- my_driver_context \*ctx = (my_driver_context \*) base;
- /*
- * Inspect the termios data structure and configure the device
- * appropriately. The driver should only be concerned with the
- * parts of the structure that specify hardware setting for the
- * communications channel such as baud, character size, etc.
- \*/
- /*
- * Return true to indicate a successful set attributes, and false
- * otherwise.
- \*/
- return true;
- }
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Clock Driver
-############
-
-Introduction
-============
-
-The purpose of the clock driver is to provide two services for the operating
-system.
-
-- A steady time basis to the kernel, so that the RTEMS primitives that need
- a clock tick work properly. See the *Clock Manager* chapter of the*RTEMS Application C User’s Guide* for more details.
-
-- An optional time counter to generate timestamps of the uptime and wall
- clock time.
-
-The clock driver is usually located in the :file:`clock` directory of the BSP.
-Clock drivers should use the :dfn:`Clock Driver Shell` available via the:file:`clockdrv_shell.h` include file.
-
-Clock Driver Shell
-==================
-
-The :dfn:`Clock Driver Shell` include file defines the clock driver functions
-declared in ``#include <rtems/clockdrv.h>`` which are used by RTEMS
-configuration file ``#include <rtems/confdefs.h>``. In case the application
-configuration defines ``#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``,
-then the clock driver is registered and should provide its services to the
-operating system. A hardware specific clock driver must provide some
-functions, defines and macros for the :dfn:`Clock Driver Shell` which are
-explained here step by step. A clock driver file looks in general like this.
-.. code:: c
-
- /*
- * A section with functions, defines and macros to provide hardware specific
- * functions for the Clock Driver Shell.
- \*/
- #include "../../../shared/clockdrv_shell.h"
-
-Initialization
---------------
-
-Depending on the hardware capabilities one out of three clock driver variants
-must be selected.
-
-- The most basic clock driver provides only a periodic interrupt service
- routine which calls ``rtems_clock_tick()``. The interval is determined by
- the application configuration via ``#define
- CONFIGURE_MICROSECONDS_PER_TICK`` and can be obtained via``rtems_configuration_get_microseconds_per_tick()``. The timestamp
- resolution is limited to the clock tick interval.
-
-- In case the hardware lacks support for a free running counter, then the
- module used for the clock tick may provide support for timestamps with a
- resolution below the clock tick interval. For this so called simple
- timecounters can be used.
-
-- The desired variant uses a free running counter to provide accurate
- timestamps. This variant is mandatory on SMP configurations.
-
-Clock Tick Only Variant
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: c
-
- static void some_support_initialize_hardware( void )
- {
- /* Initialize hardware \*/
- }
- #define Clock_driver_support_initialize_hardware() \\
- some_support_initialize_hardware()
- /* Indicate that this clock driver lacks a proper timecounter in hardware \*/
- #define CLOCK_DRIVER_USE_DUMMY_TIMECOUNTER
- #include "../../../shared/clockdrv_shell.h"
-
-Simple Timecounter Variant
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: c
-
- #include <rtems/timecounter.h>
- static rtems_timecounter_simple some_tc;
- static uint32_t some_tc_get( rtems_timecounter_simple \*tc )
- {
- return some.counter;
- }
- static bool some_tc_is_pending( rtems_timecounter_simple \*tc )
- {
- return some.is_pending;
- }
- static uint32_t some_tc_get_timecount( struct timecounter \*tc )
- {
- return rtems_timecounter_simple_downcounter_get(
- tc,
- some_tc_get,
- some_tc_is_pending
- );
- }
- static void some_tc_tick( void )
- {
- rtems_timecounter_simple_downcounter_tick( &some_tc, some_tc_get );
- }
- static void some_support_initialize_hardware( void )
- {
- uint32_t frequency = 123456;
- uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
- uint32_t timecounter_ticks_per_clock_tick =
- ( frequency * us_per_tick ) / 1000000;
- /* Initialize hardware \*/
- rtems_timecounter_simple_install(
- &some_tc,
- frequency,
- timecounter_ticks_per_clock_tick,
- some_tc_get_timecount
- );
- }
- #define Clock_driver_support_initialize_hardware() \\
- some_support_initialize_hardware()
- #define Clock_driver_timecounter_tick() \\
- some_tc_tick()
- #include "../../../shared/clockdrv_shell.h"
-
-Timecounter Variant
-~~~~~~~~~~~~~~~~~~~
-
-This variant is preferred since it is the most efficient and yields the most
-accurate timestamps. It is also mandatory on SMP configurations to obtain
-valid timestamps. The hardware must provide a periodic interrupt to service
-the clock tick and a free running counter for the timecounter. The free
-running counter must have a power of two period. The ``tc_counter_mask``
-must be initialized to the free running counter period minus one, e.g. for a
-32-bit counter this is 0xffffffff. The ``tc_get_timecount`` function must
-return the current counter value (the counter values must increase, so if the
-counter counts down, a conversion is necessary). Use``RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER`` for the ``tc_quality``. Set``tc_frequency`` to the frequency of the free running counter in Hz. All
-other fields of the ``struct timecounter`` must be zero initialized.
-Install the initialized timecounter via ``rtems_timecounter_install()``.
-.. code:: c
-
- #include <rtems/timecounter.h>
- static struct timecounter some_tc;
- static uint32_t some_tc_get_timecount( struct timecounter \*tc )
- {
- some.free_running_counter;
- }
- static void some_support_initialize_hardware( void )
- {
- uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
- uint32_t frequency = 123456;
- /*
- * The multiplication must be done in 64-bit arithmetic to avoid an integer
- * overflow on targets with a high enough counter frequency.
- \*/
- uint32_t interval = (uint32_t) ( ( frequency * us_per_tick ) / 1000000 );
- /*
- * Initialize hardware and set up a periodic interrupt for the configuration
- * based interval.
- \*/
- some_tc.tc_get_timecount = some_tc_get_timecount;
- some_tc.tc_counter_mask = 0xffffffff;
- some_tc.tc_frequency = frequency;
- some_tc.tc_quality = RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER;
- rtems_timecounter_install( &some_tc );
- }
- #define Clock_driver_support_initialize_hardware() \\
- some_support_initialize_hardware()
- #include "../../../shared/clockdrv_shell.h"
-
-Install Clock Tick Interrupt Service Routine
---------------------------------------------
-
-The clock driver must provide a function to install the clock tick interrupt
-service routine via ``Clock_driver_support_install_isr()``.
-.. code:: c
-
- #include <bsp/irq.h>
- #include <bsp/fatal.h>
- static void some_support_install_isr( rtems_interrupt_handler isr )
- {
- rtems_status_code sc;
- sc = rtems_interrupt_handler_install(
- SOME_IRQ,
- "Clock",
- RTEMS_INTERRUPT_UNIQUE,
- isr,
- NULL
- );
- if ( sc != RTEMS_SUCCESSFUL ) {
- bsp_fatal( SOME_FATAL_IRQ_INSTALL );
- }
- }
- #define Clock_driver_support_install_isr( isr, old ) \\
- some_support_install_isr( isr )
- #include "../../../shared/clockdrv_shell.h"
-
-Support At Tick
----------------
-
-The hardware specific support at tick is specified by``Clock_driver_support_at_tick()``.
-.. code:: c
-
- static void some_support_at_tick( void )
- {
- /* Clear interrupt \*/
- }
- #define Clock_driver_support_at_tick() \\
- some_support_at_tick()
- #include "../../../shared/clockdrv_shell.h"
-
-System Shutdown Support
------------------------
-
-The :dfn:`Clock Driver Shell` provides the routine ``Clock_exit()`` that is
-scheduled to be run during system shutdown via the ``atexit()`` routine.
-The hardware specific shutdown support is specified by``Clock_driver_support_shutdown_hardware()`` which is used by``Clock_exit()``. It should disable the clock tick source if it was
-enabled. This can be used to prevent clock ticks after the system is shutdown.
-.. code:: c
-
- static void some_support_shutdown_hardware( void )
- {
- /* Shutdown hardware \*/
- }
- #define Clock_driver_support_shutdown_hardware() \\
- some_support_shutdown_hardware()
- #include "../../../shared/clockdrv_shell.h"
-
-Multiple Clock Driver Ticks Per Clock Tick
-------------------------------------------
-
-In case the hardware needs more than one clock driver tick per clock tick (e.g.
-due to a limited range of the hardware timer), then this can be specified with
-the optional ``#define CLOCK_DRIVER_ISRS_PER_TICK`` and ``#define
-CLOCK_DRIVER_ISRS_PER_TICK_VALUE`` defines. This is currently used only for x86
-and it hopefully remains that way.
-.. code:: c
-
- /* Enable multiple clock driver ticks per clock tick \*/
- #define CLOCK_DRIVER_ISRS_PER_TICK 1
- /* Specifiy the clock driver ticks per clock tick value \*/
- #define CLOCK_DRIVER_ISRS_PER_TICK_VALUE 123
- #include "../../../shared/clockdrv_shell.h"
-
-Clock Driver Ticks Counter
---------------------------
-
-The :dfn:`Clock Driver Shell` provide a global variable that is simply a count
-of the number of clock driver interrupt service routines that have occurred.
-This information is valuable when debugging a system. This variable is
-declared as follows:
-.. code:: c
-
- volatile uint32_t Clock_driver_ticks;
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Timer Driver
-############
-
-The timer driver is primarily used by the RTEMS Timing Tests.
-This driver provides as accurate a benchmark timer as possible.
-It typically reports its time in microseconds, CPU cycles, or
-bus cycles. This information can be very useful for determining
-precisely what pieces of code require optimization and to measure the
-impact of specific minor changes.
-
-The gen68340 BSP also uses the Timer Driver to support a high performance
-mode of the on-CPU UART.
-
-Benchmark Timer
-===============
-
-The RTEMS Timing Test Suite requires a benchmark timer. The
-RTEMS Timing Test Suite is very helpful for determining
-the performance of target hardware and comparing its performance
-to that of other RTEMS targets.
-
-This section describes the routines which are assumed to exist by
-the RTEMS Timing Test Suite. The names used are *EXACTLY* what
-is used in the RTEMS Timing Test Suite so follow the naming convention.
-
-benchmark_timer_initialize
---------------------------
-
-Initialize the timer source.
-.. code:: c
-
- void benchmark_timer_initialize(void)
- {
- initialize the benchmark timer
- }
-
-Read_timer
-----------
-
-The ``benchmark_timer_read`` routine returns the number of benchmark
-time units (typically microseconds) that have elapsed since the last
-call to ``benchmark_timer_initialize``.
-.. code:: c
-
- benchmark_timer_t benchmark_timer_read(void)
- {
- stop time = read the hardware timer
- if the subtract overhead feature is enabled
- subtract overhead from stop time
- return the stop time
- }
-
-Many implementations of this routine subtract the overhead required
-to initialize and read the benchmark timer. This makes the times reported
-more accurate.
-
-Some implementations report 0 if the harware timer value change is
-sufficiently small. This is intended to indicate that the execution time
-is below the resolution of the timer.
-
-benchmark_timer_disable_subtracting_average_overhead
-----------------------------------------------------
-
-This routine is invoked by the "Check Timer" (``tmck``) test in the
-RTEMS Timing Test Suite. It makes the ``benchmark_timer_read``
-routine NOT subtract the overhead required
-to initialize and read the benchmark timer. This is used
-by the ``tmoverhd`` test to determine the overhead
-required to initialize and read the timer.
-.. code:: c
-
- void benchmark_timer_disable_subtracting_average_overhead(bool find_flag)
- {
- disable the subtract overhead feature
- }
-
-The ``benchmark_timer_find_average_overhead`` variable is used to
-indicate the state of the "subtract overhead feature".
-
-gen68340 UART FIFO Full Mode
-============================
-
-The gen68340 BSP is an example of the use of the timer to support the UART
-input FIFO full mode (FIFO means First In First Out and roughly means
-buffer). This mode consists in the UART raising an interrupt when n
-characters have been received (*n* is the UART’s FIFO length). It results
-in a lower interrupt processing time, but the problem is that a scanf
-primitive will block on a receipt of less than *n* characters. The solution
-is to set a timer that will check whether there are some characters
-waiting in the UART’s input FIFO. The delay time has to be set carefully
-otherwise high rates will be broken:
-
-- if no character was received last time the interrupt subroutine was
- entered, set a long delay,
-
-- otherwise set the delay to the delay needed for *n* characters
- receipt.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Real-Time Clock Driver
-######################
-
-Introduction
-============
-
-The Real-Time Clock (*RTC*) driver is responsible for providing an
-interface to an *RTC* device. \[NOTE: In this chapter, the abbreviation*TOD* is used for *Time of Day*.] The capabilities provided by this
-driver are:
-
-- Set the RTC TOD to RTEMS TOD
-
-- Set the RTEMS TOD to the RTC TOD
-
-- Get the RTC TOD
-
-- Set the RTC TOD to the Specified TOD
-
-- Get the Difference Between the RTEMS and RTC TOD
-
-The reference implementation for a real-time clock driver can
-be found in ``c/src/lib/libbsp/shared/tod.c``. This driver
-is based on the libchip concept and can be easily configured
-to work with any of the RTC chips supported by the RTC
-chip drivers in the directory ``c/src/lib/lib/libchip/rtc``.
-There is a README file in this directory for each supported
-RTC chip. Each of these README explains how to configure the
-shared libchip implementation of the RTC driver for that particular
-RTC chip.
-
-The DY-4 DMV177 BSP used the shared libchip implementation of the RTC
-driver. There were no DMV177 specific configuration routines. A BSP
-could use configuration routines to dynamically determine what type
-of real-time clock is on a particular board. This would be useful for
-a BSP supporting multiple board models. The relevant ports of
-the DMV177’s ``RTC_Table`` configuration table is below:
-.. code:: c
-
- #include <bsp.h>
- #include <libchip/rtc.h>
- #include <libchip/icm7170.h>
- bool dmv177_icm7170_probe(int minor);
- rtc_tbl RTC_Table[] = {
- { "/dev/rtc0", /* sDeviceName \*/
- RTC_ICM7170, /* deviceType \*/
- &icm7170_fns, /* pDeviceFns \*/
- dmv177_icm7170_probe, /* deviceProbe \*/
- (void \*) ICM7170_AT_1_MHZ, /* pDeviceParams \*/
- DMV170_RTC_ADDRESS, /* ulCtrlPort1 \*/
- 0, /* ulDataPort \*/
- icm7170_get_register_8, /* getRegister \*/
- icm7170_set_register_8, /* setRegister \*/
- }
- };
- unsigned long RTC_Count = (sizeof(RTC_Table)/sizeof(rtc_tbl));
- rtems_device_minor_number RTC_Minor;
- bool dmv177_icm7170_probe(int minor)
- {
- volatile unsigned16 \*card_resource_reg;
- card_resource_reg = (volatile unsigned16 \*) DMV170_CARD_RESORCE_REG;
- if ( (\*card_resource_reg & DMV170_RTC_INST_MASK) == DMV170_RTC_INSTALLED )
- return TRUE;
- return FALSE;
- }
-
-Initialization
-==============
-
-The ``rtc_initialize`` routine is responsible for initializing the
-RTC chip so it can be used. The shared libchip implementation of this
-driver supports multiple RTCs and bases its initialization order on
-the order the chips are defined in the ``RTC_Table``. Each chip
-defined in the table may or may not be present on this particular board.
-It is the responsibility of the ``deviceProbe`` to indicate the
-presence of a particular RTC chip. The first RTC found to be present
-is considered the preferred RTC.
-
-In the shared libchip based implementation
-of the driver, the following actions are performed:
-.. code:: c
-
- rtems_device_driver rtc_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor_arg,
- void \*arg
- )
- {
- for each RTC configured in RTC_Table
- if the deviceProbe for this RTC indicates it is present
- set RTC_Minor to this device
- set RTC_Present to TRUE
- break out of this loop
- if RTC_Present is not TRUE
- return RTEMS_INVALID_NUMBER to indicate that no RTC is present
- register this minor number as the "/dev/rtc"
- perform the deviceInitialize routine for the preferred RTC chip
- for RTCs past this one in the RTC_Table
- if the deviceProbe for this RTC indicates it is present
- perform the deviceInitialize routine for this RTC chip
- register the configured name for this RTC
- }
-
-The ``deviceProbe`` routine returns TRUE if the device
-configured by this entry in the ``RTC_Table`` is present.
-This configuration scheme allows one to support multiple versions
-of the same board with a single BSP. For example, if the first
-generation of a board had Vendor A’s RTC chip and the second
-generation had Vendor B’s RTC chip, RTC_Table could contain
-information for both. The ``deviceProbe`` configured
-for Vendor A’s RTC chip would need to return TRUE if the
-board was a first generation one. The ``deviceProbe``
-routines are very board dependent and must be provided by
-the BSP.
-
-setRealTimeToRTEMS
-==================
-
-The ``setRealTimeToRTEMS`` routine sets the current RTEMS TOD to that
-of the preferred RTC.
-.. code:: c
-
- void setRealTimeToRTEMS(void)
- {
- if no RTCs are present
- return
- invoke the deviceGetTime routine for the preferred RTC
- set the RTEMS TOD using rtems_clock_set
- }
-
-setRealTimeFromRTEMS
-====================
-
-The ``setRealTimeFromRTEMS`` routine sets the preferred RTC TOD to the
-current RTEMS TOD.
-.. code:: c
-
- void setRealTimeFromRTEMS(void)
- {
- if no RTCs are present
- return
- obtain the RTEMS TOD using rtems_clock_get
- invoke the deviceSetTime routine for the preferred RTC
- }
-
-getRealTime
-===========
-
-The ``getRealTime`` returns the preferred RTC TOD to the
-caller.
-.. code:: c
-
- void getRealTime( rtems_time_of_day \*tod )
- {
- if no RTCs are present
- return
- invoke the deviceGetTime routine for the preferred RTC
- }
-
-setRealTime
-===========
-
-The ``setRealTime`` routine sets the preferred RTC TOD to the
-TOD specified by the caller.
-.. code:: c
-
- void setRealTime( rtems_time_of_day \*tod )
- {
- if no RTCs are present
- return
- invoke the deviceSetTime routine for the preferred RTC
- }
-
-checkRealTime
-=============
-
-The ``checkRealTime`` routine returns the number of seconds
-difference between the RTC TOD and the current RTEMS TOD.
-.. code:: c
-
- int checkRealTime( void )
- {
- if no RTCs are present
- return -1
- obtain the RTEMS TOD using rtems_clock_get
- get the TOD from the preferred RTC using the deviceGetTime routine
- convert the RTEMS TOD to seconds
- convert the RTC TOD to seconds
- return the RTEMS TOD in seconds - RTC TOD in seconds
- }
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-ATA Driver
-##########
-
-Terms
-=====
-
-ATA device - physical device attached to an IDE controller
-
-Introduction
-============
-
-ATA driver provides generic interface to an ATA device. ATA driver is
-hardware independent implementation of ATA standard defined in working draft
-"AT Attachment Interface with Extensions (ATA-2)" X3T10/0948D revision 4c,
-March 18, 1996. ATA Driver based on IDE Controller Driver and may be used for
-computer systems with single IDE controller and with multiple as well. Although
-current implementation has several restrictions detailed below ATA driver
-architecture allows easily extend the driver. Current restrictions are:
-
-- Only mandatory (see draft p.29) and two optional (READ/WRITE MULTIPLE)
- commands are implemented
-
-- Only PIO mode is supported but both poll and interrupt driven
-
-The reference implementation for ATA driver can be found in``cpukit/libblock/src/ata.c``.
-
-Initialization
-==============
-
-The ``ata_initialize`` routine is responsible for ATA driver
-initialization. The main goal of the initialization is to detect and
-register in the system all ATA devices attached to IDE controllers
-successfully initialized by the IDE Controller driver.
-
-In the implementation of the driver, the following actions are performed:
-.. code:: c
-
- rtems_device_driver ata_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg
- )
- {
- initialize internal ATA driver data structure
- for each IDE controller successfully initialized by the IDE Controller
- driver
- if the controller is interrupt driven
- set up interrupt handler
- obtain information about ATA devices attached to the controller
- with help of EXECUTE DEVICE DIAGNOSTIC command
- for each ATA device detected on the controller
- obtain device parameters with help of DEVICE IDENTIFY command
- register new ATA device as new block device in the system
- }
-
-Special processing of ATA commands is required because of absence of
-multitasking environment during the driver initialization.
-
-Detected ATA devices are registered in the system as physical block devices
-(see libblock library description). Device names are formed based on IDE
-controller minor number device is attached to and device number on the
-controller (0 - Master, 1 - Slave). In current implementation 64 minor
-numbers are reserved for each ATA device which allows to support up to 63
-logical partitions per device.
-.. code:: c
-
- controller minor device number device name ata device minor
- 0 0 hda 0
- 0 1 hdb 64
- 1 0 hdc 128
- 1 1 hdd 172
- ... ... ...
-
-ATA Driver Architecture
-=======================
-
-ATA Driver Main Internal Data Structures
-----------------------------------------
-
-ATA driver works with ATA requests. ATA request is described by the
-following structure:
-.. code:: c
-
- /* ATA request \*/
- typedef struct ata_req_s {
- Chain_Node link; /* link in requests chain \*/
- char type; /* request type \*/
- ata_registers_t regs; /* ATA command \*/
- uint32_t cnt; /* Number of sectors to be exchanged \*/
- uint32_t cbuf; /* number of current buffer from breq in use \*/
- uint32_t pos; /* current position in 'cbuf' \*/
- blkdev_request \*breq; /* blkdev_request which corresponds to the
- * ata request
- \*/
- rtems_id sema; /* semaphore which is used if synchronous
- * processing of the ata request is required
- \*/
- rtems_status_code status; /* status of ata request processing \*/
- int error; /* error code \*/
- } ata_req_t;
-
-ATA driver supports separate ATA requests queues for each IDE
-controller (one queue per controller). The following structure contains
-information about controller’s queue and devices attached to the controller:
-.. code:: c
-
- /*
- * This structure describes controller state, devices configuration on the
- * controller and chain of ATA requests to the controller.
- \*/
- typedef struct ata_ide_ctrl_s {
- bool present; /* controller state \*/
- ata_dev_t device[2]; /* ata devices description \*/
- Chain_Control reqs; /* requests chain \*/
- } ata_ide_ctrl_t;
-
-Driver uses array of the structures indexed by the controllers minor
-number.
-
-The following structure allows to map an ATA device to the pair (IDE
-controller minor number device is attached to, device number
-on the controller):
-.. code:: c
-
- /*
- * Mapping of RTEMS ATA devices to the following pairs:
- * (IDE controller number served the device, device number on the controller)
- \*/
- typedef struct ata_ide_dev_s {
- int ctrl_minor;/* minor number of IDE controller serves RTEMS ATA device \*/
- int device; /* device number on IDE controller (0 or 1) \*/
- } ata_ide_dev_t;
-
-Driver uses array of the structures indexed by the ATA devices minor
-number.
-
-ATA driver defines the following internal events:
-.. code:: c
-
- /* ATA driver events \*/
- typedef enum ata_msg_type_s {
- ATA_MSG_GEN_EVT = 1, /* general event \*/
- ATA_MSG_SUCCESS_EVT, /* success event \*/
- ATA_MSG_ERROR_EVT, /* error event \*/
- ATA_MSG_PROCESS_NEXT_EVT /* process next ata request event \*/
- } ata_msg_type_t;
-
-Brief ATA Driver Core Overview
-------------------------------
-
-All ATA driver functionality is available via ATA driver ioctl. Current
-implementation supports only two ioctls: BLKIO_REQUEST and
-ATAIO_SET_MULTIPLE_MODE. Each ATA driver ioctl() call generates an
-ATA request which is appended to the appropriate controller queue depending
-on ATA device the request belongs to. If appended request is single request in
-the controller’s queue then ATA driver event is generated.
-
-ATA driver task which manages queue of ATA driver events is core of ATA
-driver. In current driver version queue of ATA driver events implemented
-as RTEMS message queue. Each message contains event type, IDE controller
-minor number on which event happened and error if an error occurred. Events
-may be generated either by ATA driver ioctl call or by ATA driver task itself.
-Each time ATA driver task receives an event it gets controller minor number
-from event, takes first ATA request from controller queue and processes it
-depending on request and event types. An ATA request processing may also
-includes sending of several events. If ATA request processing is finished
-the ATA request is removed from the controller queue. Note, that in current
-implementation maximum one event per controller may be queued at any moment
-of the time.
-
-(This part seems not very clear, hope I rewrite it soon)
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-IDE Controller Driver
-#####################
-
-Introduction
-============
-
-The IDE Controller driver is responsible for providing an
-interface to an IDE Controller. The capabilities provided by this
-driver are:
-
-- Read IDE Controller register
-
-- Write IDE Controller register
-
-- Read data block through IDE Controller Data Register
-
-- Write data block through IDE Controller Data Register
-
-The reference implementation for an IDE Controller driver can
-be found in ``$RTEMS_SRC_ROOT/c/src/libchip/ide``. This driver
-is based on the libchip concept and allows to work with any of the IDE
-Controller chips simply by appropriate configuration of BSP. Drivers for a
-particular IDE Controller chips locate in the following directories: drivers
-for well-known IDE Controller chips locate into``$RTEMS_SRC_ROOT/c/src/libchip/ide``, drivers for IDE Controller chips
-integrated with CPU locate into``$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU`` and
-drivers for custom IDE Controller chips (for example, implemented on FPGA)
-locate into ``$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``.
-There is a README file in these directories for each supported
-IDE Controller chip. Each of these README explains how to configure a BSP
-for that particular IDE Controller chip.
-
-Initialization
-==============
-
-IDE Controller chips used by a BSP are statically configured into``IDE_Controller_Table``. The ``ide_controller_initialize`` routine is
-responsible for initialization of all configured IDE controller chips.
-Initialization order of the chips based on the order the chips are defined in
-the ``IDE_Controller_Table``.
-
-The following actions are performed by the IDE Controller driver
-initialization routine:
-.. code:: c
-
- rtems_device_driver ide_controller_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor_arg,
- void \*arg
- )
- {
- for each IDE Controller chip configured in IDE_Controller_Table
- if (BSP dependent probe(if exists) AND device probe for this IDE chip
- indicates it is present)
- perform initialization of the particular chip
- register device with configured name for this chip
- }
-
-Read IDE Controller Register
-============================
-
-The ``ide_controller_read_register`` routine reads the content of the IDE
-Controller chip register. IDE Controller chip is selected via the minor
-number. This routine is not allowed to be called from an application.
-.. code:: c
-
- void ide_controller_read_register(rtems_device_minor_number minor,
- unsigned32 reg, unsigned32 \*value)
- {
- get IDE Controller chip configuration information from
- IDE_Controller_Table by minor number
- invoke read register routine for the chip
- }
-
-Write IDE Controller Register
-=============================
-
-The ``ide_controller_write_register`` routine writes IDE Controller chip
-register with specified value. IDE Controller chip is selected via the minor
-number. This routine is not allowed to be called from an application.
-.. code:: c
-
- void ide_controller_write_register(rtems_device_minor_number minor,
- unsigned32 reg, unsigned32 value)
- {
- get IDE Controller chip configuration information from
- IDE_Controller_Table by minor number
- invoke write register routine for the chip
- }
-
-Read Data Block Through IDE Controller Data Register
-====================================================
-
-The ``ide_controller_read_data_block`` provides multiple consequent read
-of the IDE Controller Data Register. IDE Controller chip is selected via the
-minor number. The same functionality may be achieved via separate multiple
-calls of ``ide_controller_read_register`` routine but``ide_controller_read_data_block`` allows to escape functions call
-overhead. This routine is not allowed to be called from an application.
-.. code:: c
-
- void ide_controller_read_data_block(
- rtems_device_minor_number minor,
- unsigned16 block_size,
- blkdev_sg_buffer \*bufs,
- uint32_t \*cbuf,
- uint32_t \*pos
- )
- {
- get IDE Controller chip configuration information from
- IDE_Controller_Table by minor number
- invoke read data block routine for the chip
- }
-
-Write Data Block Through IDE Controller Data Register
-=====================================================
-
-The ``ide_controller_write_data_block`` provides multiple consequent write
-into the IDE Controller Data Register. IDE Controller chip is selected via the
-minor number. The same functionality may be achieved via separate multiple
-calls of ``ide_controller_write_register`` routine but``ide_controller_write_data_block`` allows to escape functions call
-overhead. This routine is not allowed to be called from an application.
-.. code:: c
-
- void ide_controller_write_data_block(
- rtems_device_minor_number minor,
- unsigned16 block_size,
- blkdev_sg_buffer \*bufs,
- uint32_t \*cbuf,
- uint32_t \*pos
- )
- {
- get IDE Controller chip configuration information from
- IDE_Controller_Table by minor number
- invoke write data block routine for the chip
- }
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Non-Volatile Memory Driver
-##########################
-
-The Non-Volatile driver is responsible for providing an
-interface to various types of non-volatile memory. These
-types of memory include, but are not limited to, Flash, EEPROM,
-and battery backed RAM. The capabilities provided
-by this class of device driver are:
-
-- Initialize the Non-Volatile Memory Driver
-
-- Optional Disable Read and Write Handlers
-
-- Open a Particular Memory Partition
-
-- Close a Particular Memory Partition
-
-- Read from a Particular Memory Partition
-
-- Write to a Particular Memory Partition
-
-- Erase the Non-Volatile Memory Area
-
-There is currently only one non-volatile device driver included in the
-RTEMS source tree. The information provided in this chapter
-is based on drivers developed for applications using RTEMS.
-It is hoped that this driver model information can form the
-basis for a standard non-volatile memory driver model that
-can be supported in future RTEMS distribution.
-
-Major and Minor Numbers
-=======================
-
-The *major* number of a device driver is its index in the
-RTEMS Device Address Table.
-
-A *minor* number is associated with each device instance
-managed by a particular device driver. An RTEMS minor number
-is an ``unsigned32`` entity. Convention calls
-dividing the bits in the minor number down into categories
-that specify an area of non-volatile memory and a partition
-with that area. This results in categories
-like the following:
-
-- *area* - indicates a block of non-volatile memory
-
-- *partition* - indicates a particular address range with an area
-
-From the above, it should be clear that a single device driver
-can support multiple types of non-volatile memory in a single system.
-The minor number is used to distinguish the types of memory and
-blocks of memory used for different purposes.
-
-Non-Volatile Memory Driver Configuration
-========================================
-
-There is not a standard non-volatile driver configuration table but some
-fields are common across different drivers. The non-volatile memory driver
-configuration table is typically an array of structures with each
-structure containing the information for a particular area of
-non-volatile memory.
-The following is a list of the type of information normally required
-to configure each area of non-volatile memory.
-
-*memory_type*
- is the type of memory device in this area. Choices are battery backed RAM,
- EEPROM, Flash, or an optional user-supplied type. If the user-supplied type
- is configured, then the user is responsible for providing a set of
- routines to program the memory.
-
-*memory*
- is the base address of this memory area.
-
-*attributes*
- is a pointer to a memory type specific attribute block. Some of
- the fields commonly contained in this memory type specific attribute
- structure area:
-
- *use_protection_algorithm*
-
- is set to TRUE to indicate that the protection (i.e. locking) algorithm
- should be used for this area of non-volatile memory. A particular
- type of non-volatile memory may not have a protection algorithm.
-
- *access*
-
- is an enumerated type to indicate the organization of the memory
- devices in this memory area. The following is a list of the
- access types supported by the current driver implementation:
- - simple unsigned8
- - simple unsigned16
- - simple unsigned32
- - simple unsigned64
- - single unsigned8 at offset 0 in an unsigned16
- - single unsigned8 at offset 1 in an unsigned16
- - single unsigned8 at offset 0 in an unsigned32
- - single unsigned8 at offset 1 in an unsigned32
- - single unsigned8 at offset 2 in an unsigned32
- - single unsigned8 at offset 3 in an unsigned32
-
- *depth*
-
- is the depth of the progamming FIFO on this particular chip. Some
- chips, particularly EEPROMs, have the same programming algorithm but
- vary in the depth of the amount of data that can be programmed in a single
- block.
-
-*number_of_partitions*
- is the number of logical partitions within this area.
-
-*Partitions*
- is the address of the table that contains an entry to describe each
- partition in this area. Fields within each element of this
- table are defined as follows:
-
- *offset*
-
- is the offset of this partition from the base address of this area.
-
- *length*
-
- is the length of this partition.
-
-By dividing an area of memory into multiple partitions, it is possible
-to easily divide the non-volatile memory for different purposes.
-
-Initialize the Non-Volatile Memory Driver
-=========================================
-
-At system initialization, the non-volatile memory driver’s
-initialization entry point will be invoked. As part of
-initialization, the driver will perform
-whatever initializatin is required on each non-volatile memory area.
-
-The discrete I/O driver may register device names for memory
-partitions of particular interest to the system. Normally this
-will be restricted to the device "/dev/nv_memory" to indicate
-the entire device driver.
-
-Disable Read and Write Handlers
-===============================
-
-Depending on the target’s non-volatile memory configuration, it may be
-possible to write to a status register and make the memory area completely
-inaccessible. This is target dependent and beyond the standard capabilities
-of any memory type. The user has the optional capability to provide
-handlers to disable and enable access to a partiticular memory area.
-
-Open a Particular Memory Partition
-==================================
-
-This is the driver open call. Usually this call does nothing other than
-validate the minor number.
-
-With some drivers, it may be necessary to allocate memory when a particular
-device is opened. If that is the case, then this is often the place
-to do this operation.
-
-Close a Particular Memory Partition
-===================================
-
-This is the driver close call. Usually this call does nothing.
-
-With some drivers, it may be necessary to allocate memory when a particular
-device is opened. If that is the case, then this is the place
-where that memory should be deallocated.
-
-Read from a Particular Memory Partition
-=======================================
-
-This corresponds to the driver read call. After validating the minor
-number and arguments, this call enables reads from the specified
-memory area by invoking the user supplied "enable reads handler"
-and then reads the indicated memory area. When
-invoked the ``argument_block`` is actually a pointer to the following
-structure type:
-.. code:: c
-
- typedef struct {
- uint32_t offset;
- void \*buffer;
- uint32_t length;
- uint32_t status;
- } Non_volatile_memory_Driver_arguments;
-
-The driver reads ``length`` bytes starting at ``offset`` into
-the partition and places them at ``buffer``. The result is returned
-in ``status``.
-
-After the read operation is complete, the user supplied "disable reads handler"
-is invoked to protect the memory area again.
-
-Write to a Particular Memory Partition
-======================================
-
-This corresponds to the driver write call. After validating the minor
-number and arguments, this call enables writes to the specified
-memory area by invoking the "enable writes handler", then unprotecting
-the memory area, and finally actually writing to the indicated memory
-area. When invoked the ``argument_block`` is actually a pointer to
-the following structure type:
-.. code:: c
-
- typedef struct {
- uint32_t offset;
- void \*buffer;
- uint32_t length;
- uint32_t status;
- } Non_volatile_memory_Driver_arguments;
-
-The driver writes ``length`` bytes from ``buffer`` and
-writes them to the non-volatile memory starting at ``offset`` into
-the partition. The result is returned in ``status``.
-
-After the write operation is complete, the "disable writes handler"
-is invoked to protect the memory area again.
-
-Erase the Non-Volatile Memory Area
-==================================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-the specified area of non-volatile memory is erased.
-
-.. COMMENT: Written by Eric Norum
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Networking Driver
-#################
-
-Introduction
-============
-
-This chapter is intended to provide an introduction to the
-procedure for writing RTEMS network device drivers.
-The example code is taken from the ‘Generic 68360’ network device
-driver. The source code for this driver is located in the``c/src/lib/libbsp/m68k/gen68360/network`` directory in the RTEMS
-source code distribution. Having a copy of this driver at
-hand when reading the following notes will help significantly.
-
-Learn about the network device
-==============================
-
-Before starting to write the network driver become completely
-familiar with the programmer’s view of the device.
-The following points list some of the details of the
-device that must be understood before a driver can be written.
-
-- Does the device use DMA to transfer packets to and from
- memory or does the processor have to
- copy packets to and from memory on the device?
-
-- If the device uses DMA, is it capable of forming a single
- outgoing packet from multiple fragments scattered in separate
- memory buffers?
-
-- If the device uses DMA, is it capable of chaining multiple
- outgoing packets, or does each outgoing packet require
- intervention by the driver?
-
-- Does the device automatically pad short frames to the minimum
- 64 bytes or does the driver have to supply the padding?
-
-- Does the device automatically retry a transmission on detection
- of a collision?
-
-- If the device uses DMA, is it capable of buffering multiple
- packets to memory, or does the receiver have to be restarted
- after the arrival of each packet?
-
-- How are packets that are too short, too long, or received with
- CRC errors handled? Does the device automatically continue
- reception or does the driver have to intervene?
-
-- How is the device Ethernet address set? How is the device
- programmed to accept or reject broadcast and multicast packets?
-
-- What interrupts does the device generate? Does it generate an
- interrupt for each incoming packet, or only for packets received
- without error? Does it generate an interrupt for each packet
- transmitted, or only when the transmit queue is empty? What
- happens when a transmit error is detected?
-
-In addition, some controllers have specific questions regarding
-board specific configuration. For example, the SONIC Ethernet
-controller has a very configurable data bus interface. It can
-even be configured for sixteen and thirty-two bit data buses. This
-type of information should be obtained from the board vendor.
-
-Understand the network scheduling conventions
-=============================================
-
-When writing code for the driver transmit and receive tasks,
-take care to follow the network scheduling conventions. All tasks
-which are associated with networking share various
-data structures and resources. To ensure the consistency
-of these structures the tasks
-execute only when they hold the network semaphore (``rtems_bsdnet_semaphore``).
-The transmit and receive tasks must abide by this protocol. Be very
-careful to avoid ‘deadly embraces’ with the other network tasks.
-A number of routines are provided to make it easier for the network
-driver code to conform to the network task scheduling conventions.
-
-- ``void rtems_bsdnet_semaphore_release(void)``
- This function releases the network semaphore.
- The network driver tasks must call this function immediately before
- making any blocking RTEMS request.
-
-- ``void rtems_bsdnet_semaphore_obtain(void)``
- This function obtains the network semaphore.
- If a network driver task has released the network semaphore to allow other
- network-related tasks to run while the task blocks, then this function must
- be called to reobtain the semaphore immediately after the return from the
- blocking RTEMS request.
-
-- ``rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set \*)``
- The network driver task should call this function when it wishes to wait
- for an event. This function releases the network semaphore,
- calls ``rtems_event_receive`` to wait for the specified event
- or events and reobtains the semaphore.
- The value returned is the value returned by the ``rtems_event_receive``.
-
-Network Driver Makefile
-=======================
-
-Network drivers are considered part of the BSD network package and as such
-are to be compiled with the appropriate flags. This can be accomplished by
-adding ``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``.
-If the driver is inside the RTEMS source tree or is built using the
-RTEMS application Makefiles, then adding the following line accomplishes
-this:
-
-.. code:: c
-
- DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
-
-This is equivalent to the following list of definitions. Early versions
-of the RTEMS BSD network stack required that all of these be defined.
-
-.. code:: c
-
- -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \\
- -DDIAGNOSTIC -DBOOTP_COMPAT
-
-Defining these macros tells the network header files that the driver
-is to be compiled with extended visibility into the network stack. This
-is in sharp contrast to applications that simply use the network stack.
-Applications do not require this level of visibility and should stick
-to the portable application level API.
-
-As a direct result of being logically internal to the network stack,
-network drivers use the BSD memory allocation routines This means,
-for example, that malloc takes three arguments. See the SONIC
-device driver (``c/src/lib/libchip/network/sonic.c``) for an example
-of this. Because of this, network drivers should not include``<stdlib.h>``. Doing so will result in conflicting definitions
-of ``malloc()``.
-
-*Application level* code including network servers such as the FTP
-daemon are *not* part of the BSD kernel network code and should not be
-compiled with the BSD network flags. They should include``<stdlib.h>`` and not define the network stack visibility
-macros.
-
-Write the Driver Attach Function
-================================
-
-The driver attach function is responsible for configuring the driver
-and making the connection between the network stack
-and the driver.
-
-Driver attach functions take a pointer to an``rtems_bsdnet_ifconfig`` structure as their only argument.
-and set the driver parameters based on the
-values in this structure. If an entry in the configuration
-structure is zero the attach function chooses an
-appropriate default value for that parameter.
-
-The driver should then set up several fields in the ifnet structure
-in the device-dependent data structure supplied and maintained by the driver:
-
-``ifp->if_softc``
- Pointer to the device-dependent data. The first entry
- in the device-dependent data structure must be an ``arpcom``
- structure.
-
-``ifp->if_name``
- The name of the device. The network stack uses this string
- and the device number for device name lookups. The device name should
- be obtained from the ``name`` entry in the configuration structure.
-
-``ifp->if_unit``
- The device number. The network stack uses this number and the
- device name for device name lookups. For example, if``ifp->if_name`` is ‘``scc``’ and ``ifp->if_unit`` is ‘``1``’,
- the full device name would be ‘``scc1``’. The unit number should be
- obtained from the ‘name’ entry in the configuration structure.
-
-``ifp->if_mtu``
- The maximum transmission unit for the device. For Ethernet
- devices this value should almost always be 1500.
-
-``ifp->if_flags``
- The device flags. Ethernet devices should set the flags
- to ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the
- device can broadcast packets to multiple destinations
- and does not receive and transmit at the same time.
-
-``ifp->if_snd.ifq_maxlen``
- The maximum length of the queue of packets waiting to be
- sent to the driver. This is normally set to ``ifqmaxlen``.
-
-``ifp->if_init``
- The address of the driver initialization function.
-
-``ifp->if_start``
- The address of the driver start function.
-
-``ifp->if_ioctl``
- The address of the driver ioctl function.
-
-``ifp->if_output``
- The address of the output function. Ethernet devices
- should set this to ``ether_output``.
-
-RTEMS provides a function to parse the driver name in the
-configuration structure into a device name and unit number.
-.. code:: c
-
- int rtems_bsdnet_parse_driver_name (
- const struct rtems_bsdnet_ifconfig \*config,
- char \**namep
- );
-
-The function takes two arguments; a pointer to the configuration
-structure and a pointer to a pointer to a character. The function
-parses the configuration name entry, allocates memory for the driver
-name, places the driver name in this memory, sets the second argument
-to point to the name and returns the unit number.
-On error, a message is printed and -1 is returned.
-
-Once the attach function has set up the above entries it must link the
-driver data structure onto the list of devices by
-calling ``if_attach``. Ethernet devices should then
-call ``ether_ifattach``. Both functions take a pointer to the
-device’s ``ifnet`` structure as their only argument.
-
-The attach function should return a non-zero value to indicate that
-the driver has been successfully configured and attached.
-
-Write the Driver Start Function.
-================================
-
-This function is called each time the network stack wants to start the
-transmitter. This occures whenever the network stack adds a packet
-to a device’s send queue and the ``IFF_OACTIVE`` bit in the
-device’s ``if_flags`` is not set.
-
-For many devices this function need only set the ``IFF_OACTIVE`` bit in the``if_flags`` and send an event to the transmit task
-indicating that a packet is in the driver transmit queue.
-
-Write the Driver Initialization Function.
-=========================================
-
-This function should initialize the device, attach to interrupt handler,
-and start the driver transmit and receive tasks. The function
-.. code:: c
-
- rtems_id
- rtems_bsdnet_newproc (char \*name,
- int stacksize,
- void(\*entry)(void \*),
- void \*arg);
-
-should be used to start the driver tasks.
-
-Note that the network stack may call the driver initialization function more
-than once.
-Make sure multiple versions of the receive and transmit tasks are not accidentally
-started.
-
-Write the Driver Transmit Task
-==============================
-
-This task is reponsible for removing packets from the driver send queue and sending them to the device. The task should block waiting for an event from the
-driver start function indicating that packets are waiting to be transmitted.
-When the transmit task has drained the driver send queue the task should clear
-the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another outgoing
-packet is queued.
-
-Write the Driver Receive Task
-=============================
-
-This task should block until a packet arrives from the device. If the
-device is an Ethernet interface the function ``ether_input`` should be called
-to forward the packet to the network stack. The arguments to ``ether_input``
-are a pointer to the interface data structure, a pointer to the ethernet
-header and a pointer to an mbuf containing the packet itself.
-
-Write the Driver Interrupt Handler
-==================================
-
-A typical interrupt handler will do nothing more than the hardware
-manipulation required to acknowledge the interrupt and send an RTEMS event
-to wake up the driver receive or transmit task waiting for the event.
-Network interface interrupt handlers must not make any calls to other
-network routines.
-
-Write the Driver IOCTL Function
-===============================
-
-This function handles ioctl requests directed at the device. The ioctl
-commands which must be handled are:
-
-``SIOCGIFADDR``
-
-``SIOCSIFADDR``
-
- If the device is an Ethernet interface these
- commands should be passed on to ``ether_ioctl``.
-
-``SIOCSIFFLAGS``
-
- This command should be used to start or stop the device,
- depending on the state of the interface ``IFF_UP`` and``IFF_RUNNING`` bits in ``if_flags``:
-
- ``IFF_RUNNING``
-
- Stop the device.
-
- ``IFF_UP``
-
- Start the device.
-
- ``IFF_UP|IFF_RUNNING``
-
- Stop then start the device.
-
- ``0``
-
- Do nothing.
-
-Write the Driver Statistic-Printing Function
-============================================
-
-This function should print the values of any statistic/diagnostic
-counters the network driver may use. The driver ioctl function should call
-the statistic-printing function when the ioctl command is``SIO_RTEMS_SHOW_STATS``.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Shared Memory Support Driver
-############################
-
-The Shared Memory Support Driver is responsible for providing glue
-routines and configuration information required by the Shared
-Memory Multiprocessor Communications Interface (MPCI). The
-Shared Memory Support Driver tailors the portable Shared
-Memory Driver to a particular target platform.
-
-This driver is only required in shared memory multiprocessing
-systems that use the RTEMS mulitprocessing support. For more
-information on RTEMS multiprocessing capabilities and the
-MPCI, refer to the *Multiprocessing Manager* chapter
-of the *RTEMS Application C User’s Guide*.
-
-Shared Memory Configuration Table
-=================================
-
-The Shared Memory Configuration Table is defined in the following
-structure:
-.. code:: c
-
- typedef volatile uint32_t vol_u32;
- typedef struct {
- vol_u32 \*address; /* write here for interrupt \*/
- vol_u32 value; /* this value causes interrupt \*/
- vol_u32 length; /* for this length (0,1,2,4) \*/
- } Shm_Interrupt_information;
- struct shm_config_info {
- vol_u32 \*base; /* base address of SHM \*/
- vol_u32 length; /* length (in bytes) of SHM \*/
- vol_u32 format; /* SHM is big or little endian \*/
- vol_u32 (\*convert)(); /* neutral conversion routine \*/
- vol_u32 poll_intr; /* POLLED or INTR driven mode \*/
- void (\*cause_intr)( uint32_t );
- Shm_Interrupt_information Intr; /* cause intr information \*/
- };
- typedef struct shm_config_info shm_config_table;
-
-where the fields are defined as follows:
-
-*base*
- is the base address of the shared memory buffer used to pass
- messages between the nodes in the system.
-
-*length*
- is the length (in bytes) of the shared memory buffer used to pass
- messages between the nodes in the system.
-
-*format*
- is either SHM_BIG or SHM_LITTLE to indicate that the neutral format
- of the shared memory area is big or little endian. The format
- of the memory should be chosen to match most of the inter-node traffic.
-
-*convert*
- is the address of a routine which converts from native format to
- neutral format. Ideally, the neutral format is the same as the
- native format so this routine is quite simple.
-
-*poll_intr*
- is either INTR_MODE or POLLED_MODE to indicate how the node will be
- informed of incoming messages.
-
-*cause_intr*
-
-*Intr*
-
- is the information required to cause an interrupt on a node. This
- structure contains the following fields:
-
- *address*
-
- is the address to write at to cause an interrupt on that node.
- For a polled node, this should be NULL.
-
- *value*
-
- is the value to write to cause an interrupt.
-
- *length*
-
- is the length of the entity to write on the node to cause an interrupt.
- This can be 0 to indicate polled operation, 1 to write a byte, 2 to
- write a sixteen-bit entity, and 4 to write a thirty-two bit entity.
-
-Primitives
-==========
-
-Convert Address
----------------
-
-The ``Shm_Convert_address`` is responsible for converting an address
-of an entity in the shared memory area into the address that should be
-used from this node. Most targets will simply return the address
-passed to this routine. However, some target boards will have a special
-window onto the shared memory. For example, some VMEbus boards have
-special address windows to access addresses that are normally reserved
-in the CPU’s address space.
-.. code:: c
-
- void \*Shm_Convert_address( void \*address )
- {
- return the local address version of this bus address
- }
-
-Get Configuration
------------------
-
-The ``Shm_Get_configuration`` routine is responsible for filling in the
-Shared Memory Configuration Table passed to it.
-.. code:: c
-
- void Shm_Get_configuration(
- uint32_t localnode,
- shm_config_table \**shmcfg
- )
- {
- fill in the Shared Memory Configuration Table
- }
-
-Locking Primitives
-------------------
-
-This is a collection of routines that are invoked by the portable
-part of the Shared Memory Driver to manage locks in the shared
-memory buffer area. Accesses to the shared memory must be
-atomic. Two nodes in a multiprocessor system must not be manipulating
-the shared data structures simultaneously. The locking primitives
-are used to insure this.
-
-To avoid deadlock, local processor interrupts should be disabled the entire
-time the locked queue is locked.
-
-The locking primitives operate on the lock``field`` of the ``Shm_Locked_queue_Control``
-data structure. This structure is defined as follows:
-.. code:: c
-
- typedef struct {
- vol_u32 lock; /* lock field for this queue \*/
- vol_u32 front; /* first envelope on queue \*/
- vol_u32 rear; /* last envelope on queue \*/
- vol_u32 owner; /* receiving (i.e. owning) node \*/
- } Shm_Locked_queue_Control;
-
-where each field is defined as follows:
-
-*lock*
- is the lock field. Every node in the system must agree on how this
- field will be used. Many processor families provide an atomic
- "test and set" instruction that is used to manage this field.
-
-*front*
- is the index of the first message on this locked queue.
-
-*rear*
- is the index of the last message on this locked queue.
-
-*owner*
- is the node number of the node that currently has this structure locked.
-
-Initializing a Shared Lock
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``Shm_Initialize_lock`` routine is responsible for
-initializing the lock field. This routines usually is implemented
-as follows:
-.. code:: c
-
- void Shm_Initialize_lock(
- Shm_Locked_queue_Control \*lq_cb
- )
- {
- lq_cb->lock = LQ_UNLOCKED;
- }
-
-Acquiring a Shared Lock
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``Shm_Lock`` routine is responsible for
-acquiring the lock field. Interrupts should be
-disabled while that lock is acquired. If the lock
-is currently unavailble, then the locking routine
-should delay a few microseconds to allow the other
-node to release the lock. Doing this reduces bus contention
-for the lock. This routines usually is implemented as follows:
-.. code:: c
-
- void Shm_Lock(
- Shm_Locked_queue_Control \*lq_cb
- )
- {
- disable processor interrupts
- set Shm_isrstat to previous interrupt disable level
- while ( TRUE ) {
- atomically attempt to acquire the lock
- if the lock was acquired
- return
- delay some small period of time
- }
- }
-
-Releasing a Shared Lock
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``Shm_Unlock`` routine is responsible for
-releasing the lock field and reenabling processor
-interrupts. This routines usually is implemented as follows:
-.. code:: c
-
- void Shm_Unlock(
- Shm_Locked_queue_Control \*lq_cb
- )
- {
- set the lock to the unlocked value
- reenable processor interrupts to their level prior
- to the lock being acquired. This value was saved
- in the global variable Shm_isrstat
- }
-
-Installing the MPCI ISR
-=======================
-
-The ``Shm_setvec`` is invoked by the portable portion
-of the shared memory to install the interrupt service routine
-that is invoked when an incoming message is announced. Some
-target boards support an interprocessor interrupt or mailbox
-scheme and this is where the ISR for that interrupt would be
-installed.
-
-On an interrupt driven node, this routine would be implemented
-as follows:
-.. code:: c
-
- void Shm_setvec( void )
- {
- install the interprocessor communications ISR
- }
-
-On a polled node, this routine would be empty.
-
-.. COMMENT: COPYRIGHT (c) 1988-2009.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Frame Buffer Driver
-###################
-
-In this chapter, we present the basic functionality implemented by a
-frame buffer driver: ``frame_buffer_initialize()``, ``frame_buffer_open()``,``frame_buffer_close()``, ``frame_buffer_read()``, ``frame_buffer_write()``
-and ``frame_buffer_control()``.
-
-Introduction
-============
-
-The purpose of the frame buffer driver is to provide an abstraction for
-graphics hardware.
-By using the frame buffer interface, an application can display graphics
-without knowing anything about the low-level details of interfacing to a
-particular graphics adapter. The parameters governing the mapping of
-memory to displayed pixels (planar or linear, bit depth, etc) is still
-implementation-specific, but device-independent methods are provided to
-determine and potentially modify these parameters.
-
-The frame buffer driver is commonly located in the ``console``
-directory of the BSP and registered by the name */dev/fb0*.
-Additional frame buffers (if available) are named */dev/fb1*,*/dev/fb2*, etc.
-
-To work with the frame buffer, the following operation sequence is used:``open()``, ``ioctls()`` to get the frame buffer info, ``read()`` and/or``write()``, and ``close()``.
-
-Driver Function Overview
-========================
-
-Initialization
---------------
-
-The driver initialization is called once during the RTEMS initialization
-process and returns RTEMS_SUCCESSFUL when the device driver is successfully
-initialized. During the initialization, a name is assigned to the frame
-buffer device. If the graphics hardware supports console text output,
-as is the case with the pc386 VGA hardware, initialization into graphics
-mode may be deferred until the device is ``open()`` ed.
-
-The ``frame_buffer_initialize()`` function may look like this:
-
-.. code:: c
-
- rtems_device_driver frame_buffer_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg)
- {
- rtems_status_code status;
- printk( "frame buffer driver initializing..\\n" );
- /*
- * Register the device
- \*/
- status = rtems_io_register_name("/dev/fb0", major, 0);
- if (status != RTEMS_SUCCESSFUL)
- {
- printk("Error registering frame buffer device!\\n");
- rtems_fatal_error_occurred( status );
- }
- /*
- * graphics hardware initialization goes here for non-console
- * devices
- \*/
- return RTEMS_SUCCESSFUL;
- }
-
-Opening the Frame Buffer Device
--------------------------------
-
-The ``frame_buffer_open()`` function is called whenever a frame buffer device is opened.
-If the frame buffer is registered as "/dev/fb0", the ``frame_buffer_open`` entry point
-will be called as the result of an ``open("/dev/fb0", mode)`` in the application.
-
-Thread safety of the frame buffer driver is implementation-dependent.
-The VGA driver shown below uses a mutex to prevent multiple open()
-operations of the frame buffer device.
-
-The ``frame_buffer_open()`` function returns RTEMS_SUCCESSFUL when the device driver
-is successfully opened, and RTEMS_UNSATISFIED if the device is already open:
-.. code:: c
-
- rtems_device_driver frame_buffer_close(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg
- )
- {
- if (pthread_mutex_unlock(&mutex) == 0){
- /* restore previous state. for VGA this means return to text mode.
- * leave out if graphics hardware has been initialized in
- * frame_buffer_initialize() \*/
- ega_hwterm();
- printk( "FBVGA close called.\\n" );
- return RTEMS_SUCCESSFUL;
- }
- return RTEMS_UNSATISFIED;
- }
-
-In the previous example, the function ``ega_hwinit()`` takes care of
-hardware-specific initialization.
-
-Closing the Frame Buffer Device
--------------------------------
-
-The ``frame_buffer_close()`` is invoked when the frame buffer device
-is closed. It frees up any resources allocated in``frame_buffer_open()``, and should restore previous hardware state.
-The entry point corresponds to the device driver close entry point.
-
-Returns RTEMS_SUCCESSFUL when the device driver is successfully closed:
-.. code:: c
-
- rtems_device_driver frame_buffer_close(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg)
- {
- pthread_mutex_unlock(&mutex);
- /* TODO check mutex return value, RTEMS_UNSATISFIED if it failed. we
- * don't want to unconditionally call ega_hwterm()... \*/
- /* restore previous state. for VGA this means return to text mode.
- * leave out if graphics hardware has been initialized in
- * frame_buffer_initialize() \*/
- ega_hwterm();
- printk( "frame buffer close called.\\n" );
- return RTEMS_SUCCESSFUL;
- }
-
-Reading from the Frame Buffer Device
-------------------------------------
-
-The ``frame_buffer_read()`` is invoked from a ``read()`` operation
-on the frame buffer device.
-Read functions should allow normal and partial reading at the end of frame buffer memory.
-This method returns RTEMS_SUCCESSFUL when the device is successfully read from:
-.. code:: c
-
- rtems_device_driver frame_buffer_read(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg
- )
- {
- rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg;
- rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
- memcpy(rw_args->buffer, (const void \*) (fb_fix.smem_start + rw_args->offset), rw_args->bytes_moved);
- return RTEMS_SUCCESSFUL;
- }
-
-Writing to the Frame Buffer Device
-----------------------------------
-
-The ``frame_buffer_write()`` is invoked from a ``write()``
-operation on the frame buffer device.
-The frame buffer write function is similar to the read function, and
-should handle similar cases involving partial writes.
-
-This method returns RTEMS_SUCCESSFUL when the device is successfully
-written to:
-.. code:: c
-
- rtems_device_driver frame_buffer_write(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg
- )
- {
- rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg;
- rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
- memcpy( (void \*) (fb_fix.smem_start + rw_args->offset), rw_args->buffer, rw_args->bytes_moved);
- return RTEMS_SUCCESSFUL;
- }
-
-Frame Buffer IO Control
------------------------
-
-The frame buffer driver allows several ioctls, partially compatible with
-the Linux kernel,
-to obtain information about the hardware.
-
-All ``ioctl()`` operations on the frame buffer device invoke``frame_buffer_control()``.
-
-Ioctls supported:
-
-- ioctls to get the frame buffer screen info (fixed and variable).
-
-- ioctl to set and get palette.
-
-.. code:: c
-
- rtems_device_driver frame_buffer_control(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*arg
- )
- {
- rtems_libio_ioctl_args_t \*args = arg;
- printk( "FBVGA ioctl called, cmd=%x\\n", args->command );
- switch( args->command ) {
- case FBIOGET_FSCREENINFO:
- args->ioctl_return = get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer );
- break;
- case FBIOGET_VSCREENINFO:
- args->ioctl_return = get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer );
- break;
- case FBIOPUT_VSCREENINFO:
- /* not implemented yet*/
- args->ioctl_return = -1;
- return RTEMS_UNSATISFIED;
- case FBIOGETCMAP:
- args->ioctl_return = get_palette( ( struct fb_cmap * ) args->buffer );
- break;
- case FBIOPUTCMAP:
- args->ioctl_return = set_palette( ( struct fb_cmap * ) args->buffer );
- break;
- default:
- args->ioctl_return = 0;
- break;
- }
- return RTEMS_SUCCESSFUL;
- }
-
-See ``rtems/fb.h`` for more information on the list of ioctls and
-data structures they work with.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Analog Driver
-#############
-
-The Analog driver is responsible for providing an
-interface to Digital to Analog Converters (DACs) and
-Analog to Digital Converters (ADCs). The capabilities provided
-by this class of device driver are:
-
-- Initialize an Analog Board
-
-- Open a Particular Analog
-
-- Close a Particular Analog
-
-- Read from a Particular Analog
-
-- Write to a Particular Analog
-
-- Reset DACs
-
-- Reinitialize DACS
-
-Most analog devices are found on I/O cards that support multiple
-DACs or ADCs on a single card.
-
-There are currently no analog device drivers included in the
-RTEMS source tree. The information provided in this chapter
-is based on drivers developed for applications using RTEMS.
-It is hoped that this driver model information can form the
-basis for a standard analog driver model that can be supported
-in future RTEMS distribution.
-
-Major and Minor Numbers
-=======================
-
-The *major* number of a device driver is its index in the
-RTEMS Device Address Table.
-
-A *minor* number is associated with each device instance
-managed by a particular device driver. An RTEMS minor number
-is an ``unsigned32`` entity. Convention calls for
-dividing the bits in the minor number down into categories
-like the following:
-
-- *board* - indicates the board a particular device is located on
-
-- *port* - indicates the particular device on a board.
-
-From the above, it should be clear that a single device driver
-can support multiple copies of the same board in a single system.
-The minor number is used to distinguish the devices.
-
-Analog Driver Configuration
-===========================
-
-There is not a standard analog driver configuration table but some
-fields are common across different drivers. The analog driver
-configuration table is typically an array of structures with each
-structure containing the information for a particular board.
-The following is a list of the type of information normally required
-to configure an analog board:
-
-*board_offset*
- is the base address of a board.
-
-*DAC_initial_values*
- is an array of the voltages that should be written to each DAC
- during initialization. This allows the driver to start the board
- in a known state.
-
-Initialize an Analog Board
-==========================
-
-At system initialization, the analog driver’s initialization entry point
-will be invoked. As part of initialization, the driver will perform
-whatever board initialization is required and then set all
-outputs to their configured initial state.
-
-The analog driver may register a device name for each DAC and ADC in
-the system.
-
-Open a Particular Analog
-========================
-
-This is the driver open call. Usually this call does nothing other than
-validate the minor number.
-
-With some drivers, it may be necessary to allocate memory when a particular
-device is opened. If that is the case, then this is often the place
-to do this operation.
-
-Close a Particular Analog
-=========================
-
-This is the driver close call. Usually this call does nothing.
-
-With some drivers, it may be necessary to allocate memory when a particular
-device is opened. If that is the case, then this is the place
-where that memory should be deallocated.
-
-Read from a Particular Analog
-=============================
-
-This corresponds to the driver read call. After validating the minor
-number and arguments, this call reads the indicated device. Most analog
-devices store the last value written to a DAC. Since DACs are output
-only devices, saving the last written value gives the appearance that
-DACs can be read from also. If the device is an ADC, then it is sampled.
-
-*NOTE:* Many boards have multiple analog inputs but only one ADC. On
-these boards, it will be necessary to provide some type of mutual exclusion
-during reads. On these boards, there is a MUX which must be switched
-before sampling the ADC. After the MUX is switched, the driver must
-delay some short period of time (usually microseconds) before the
-signal is stable and can be sampled. To make matters worse, some ADCs
-cannot respond to wide voltage swings in a single sample. On these
-ADCs, one must do two samples when the voltage swing is too large.
-On a practical basis, this means that the driver usually ends up
-double sampling the ADC on these systems.
-
-The value returned is a single precision floating point number
-representing the voltage read. This value is stored in the``argument_block`` passed in to the call. By returning the
-voltage, the caller is freed from having to know the number of
-bits in the analog and board dependent conversion algorithm.
-
-Write to a Particular Analog
-============================
-
-This corresponds to the driver write call. After validating the minor
-number and arguments, this call writes the indicated device. If the
-specified device is an ADC, then an error is usually returned.
-
-The value written is a single precision floating point number
-representing the voltage to be written to the specified DAC.
-This value is stored in the ``argument_block`` passed in to the
-call. By passing the voltage to the device driver, the caller is
-freed from having to know the number of bits in the analog
-and board dependent conversion algorithm.
-
-Reset DACs
-==========
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-all of the DACs are written to 0.0 volts.
-
-Reinitialize DACS
-=================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-all of the DACs are written with the initial value configured
-for this device.
-
-Get Last Written Values
-=======================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-the following information is returned to the caller:
-
-- last value written to the specified DAC
-
-- timestamp of when the last write was performed
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Discrete Driver
-###############
-
-The Discrete driver is responsible for providing an
-interface to Discrete Input/Outputs. The capabilities provided
-by this class of device driver are:
-
-- Initialize a Discrete I/O Board
-
-- Open a Particular Discrete Bitfield
-
-- Close a Particular Discrete Bitfield
-
-- Read from a Particular Discrete Bitfield
-
-- Write to a Particular Discrete Bitfield
-
-- Reset DACs
-
-- Reinitialize DACS
-
-Most discrete I/O devices are found on I/O cards that support many
-bits of discrete I/O on a single card. This driver model is centered
-on the notion of reading bitfields from the card.
-
-There are currently no discrete I/O device drivers included in the
-RTEMS source tree. The information provided in this chapter
-is based on drivers developed for applications using RTEMS.
-It is hoped that this driver model information can form the
-discrete I/O driver model that can be supported in future RTEMS
-distribution.
-
-Major and Minor Numbers
-=======================
-
-The *major* number of a device driver is its index in the
-RTEMS Device Address Table.
-
-A *minor* number is associated with each device instance
-managed by a particular device driver. An RTEMS minor number
-is an ``unsigned32`` entity. Convention calls for
-dividing the bits in the minor number down into categories
-that specify a particular bitfield. This results in categories
-like the following:
-
-- *board* - indicates the board a particular bitfield is located on
-
-- *word* - indicates the particular word of discrete bits the
- bitfield is located within
-
-- *start* - indicates the starting bit of the bitfield
-
-- *width* - indicates the width of the bitfield
-
-From the above, it should be clear that a single device driver
-can support multiple copies of the same board in a single system.
-The minor number is used to distinguish the devices.
-
-By providing a way to easily access a particular bitfield from
-the device driver, the application is insulated with knowing how
-to mask fields in and out of a discrete I/O.
-
-Discrete I/O Driver Configuration
-=================================
-
-There is not a standard discrete I/O driver configuration table but some
-fields are common across different drivers. The discrete I/O driver
-configuration table is typically an array of structures with each
-structure containing the information for a particular board.
-The following is a list of the type of information normally required
-to configure an discrete I/O board:
-
-*board_offset*
- is the base address of a board.
-
-*relay_initial_values*
- is an array of the values that should be written to each output
- word on the board during initialization. This allows the driver
- to start with the board’s output in a known state.
-
-Initialize a Discrete I/O Board
-===============================
-
-At system initialization, the discrete I/O driver’s initialization entry point
-will be invoked. As part of initialization, the driver will perform
-whatever board initializatin is required and then set all
-outputs to their configured initial state.
-
-The discrete I/O driver may register a device name for bitfields of
-particular interest to the system. Normally this will be restricted
-to the names of each word and, if the driver supports it, an "all words".
-
-Open a Particular Discrete Bitfield
-===================================
-
-This is the driver open call. Usually this call does nothing other than
-validate the minor number.
-
-With some drivers, it may be necessary to allocate memory when a particular
-device is opened. If that is the case, then this is often the place
-to do this operation.
-
-Close a Particular Discrete Bitfield
-====================================
-
-This is the driver close call. Usually this call does nothing.
-
-With some drivers, it may be necessary to allocate memory when a particular
-device is opened. If that is the case, then this is the place
-where that memory should be deallocated.
-
-Read from a Particular Discrete Bitfield
-========================================
-
-This corresponds to the driver read call. After validating the minor
-number and arguments, this call reads the indicated bitfield. A
-discrete I/O devices may have to store the last value written to
-a discrete output. If the bitfield is output only, saving the last
-written value gives the appearance that it can be read from also.
-If the bitfield is input, then it is sampled.
-
-*NOTE:* Many discrete inputs have a tendency to bounce. The application
-may have to take account for bounces.
-
-The value returned is an ``unsigned32`` number
-representing the bitfield read. This value is stored in the``argument_block`` passed in to the call.
-
-*NOTE:* Some discrete I/O drivers have a special minor number
-used to access all discrete I/O bits on the board. If this special
-minor is used, then the area pointed to by ``argument_block`` must
-be the correct size.
-
-Write to a Particular Discrete Bitfield
-=======================================
-
-This corresponds to the driver write call. After validating the minor
-number and arguments, this call writes the indicated device. If the
-specified device is an ADC, then an error is usually returned.
-
-The value written is an ``unsigned32`` number
-representing the value to be written to the specified
-bitfield. This value is stored in the``argument_block`` passed in to the call.
-
-*NOTE:* Some discrete I/O drivers have a special minor number
-used to access all discrete I/O bits on the board. If this special
-minor is used, then the area pointed to by ``argument_block`` must
-be the correct size.
-
-Disable Discrete Outputs
-========================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-the discrete outputs are disabled.
-
-*NOTE:* It may not be possible to disable/enable discrete output on all
-discrete I/O boards.
-
-Enable Discrete Outputs
-=======================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-the discrete outputs are enabled.
-
-*NOTE:* It may not be possible to disable/enable discrete output on all
-discrete I/O boards.
-
-Reinitialize Outputs
-====================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-the discrete outputs are rewritten with the configured initial
-output values.
-
-Get Last Written Values
-=======================
-
-This is one of the IOCTL functions supported by the I/O control
-device driver entry point. When this IOCTL function is invoked,
-the following information is returned to the caller:
-
-- last value written to the specified output word
-
-- timestamp of when the last write was performed
-
-Command and Variable Index
-##########################
-
-There are currently no Command and Variable Index entries.
-
-.. COMMENT: @printindex fn
-
-Concept Index
-#############
-
-There are currently no Concept Index entries.
-
-.. COMMENT: @printindex cp
diff --git a/c_user/c_user_old_reference_only.rst b/c_user/c_user_old_reference_only.rst
deleted file mode 100644
index 1eb6909..0000000
--- a/c_user/c_user_old_reference_only.rst
+++ /dev/null
@@ -1,23788 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-:orphan:
-
-
-
-.. COMMENT: %**end of header
-
-.. COMMENT: COPYRIGHT (c) 1989-2013.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: Master file for the C User's Guide
-
-.. COMMENT: Joel's Questions
-
-.. COMMENT: 1. Why does paragraphindent only impact makeinfo?
-
-.. COMMENT: 2. Why does paragraphindent show up in HTML?
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The following determines which set of the tables and figures we will use.
-
-.. COMMENT: We default to ASCII but if available TeX or HTML versions will
-
-.. COMMENT: be used instead.
-
-.. COMMENT: @clear use-html
-
-.. COMMENT: @clear use-tex
-
-.. COMMENT: The following variable says to use texinfo or html for the two column
-
-.. COMMENT: texinfo tables. For somethings the format does not look good in html.
-
-.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
-
-.. COMMENT: good printed.
-
-.. COMMENT: Custom whitespace adjustments. We could fiddle a bit more.
-
-.. COMMENT: @syncodeindex fn cp
-
-.. COMMENT: variable substitution info:
-
-.. COMMENT: the language is @value{LANGUAGE}
-
-.. COMMENT: NOTE: don't use underscore in the name
-
-.. COMMENT: Title Page Stuff
-
-.. COMMENT: I don't really like having a short title page. -joel
-
-.. COMMENT: @shorttitlepage RTEMS Applications C User's Guide
-
-====================
-RTEMS C User’s Guide
-====================
-
-.. COMMENT: COPYRIGHT (c) 1988-2015.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
-
-.. COMMENT: can force the copyright description onto a left hand page.
-
-COPYRIGHT © 1988 - 2015.
-
-On-Line Applications Research Corporation (OAR).
-
-The authors have used their best efforts in preparing
-this material. These efforts include the development, research,
-and testing of the theories and programs to determine their
-effectiveness. No warranty of any kind, expressed or implied,
-with regard to the software or the material contained in this
-document is provided. No liability arising out of the
-application or use of any product described in this document is
-assumed. The authors reserve the right to revise this material
-and to make changes from time to time in the content hereof
-without obligation to notify anyone of such revision or changes.
-
-The RTEMS Project is hosted at http://www.rtems.org. Any
-inquiries concerning RTEMS, its related support components, or its
-documentation should be directed to the Community Project hosted athttp://www.rtems.org.
-
-Any inquiries for commercial services including training, support, custom
-development, application development assistance should be directed tohttp://www.rtems.com.
-
-.. COMMENT: This prevents a black box from being printed on "overflow" lines.
-
-.. COMMENT: The alternative is to rework a sentence to avoid this problem.
-
-RTEMS Applications C User’s Guide
-#################################
-
-List of Figures
-###############
-
-.. COMMENT: COPYRIGHT (c) 1989-2015.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Preface
-#######
-
-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
-
-- Atmel AVR
-
-- ARM
-
-- Freescale (formerly Motorola) MC68xxx
-
-- Freescale (formerly Motorola) MC683xx
-
-- Freescale (formerly Motorola) ColdFire
-
-- Intel i386 and above
-
-- Lattice Semiconductor LM32
-
-- NEC V850
-
-- MIPS
-
-- PowerPC
-
-- Renesas (formerly Hitachi) SuperH
-
-- Renesas (formerly Hitachi) H8/300
-
-- Renesas M32C
-
-- SPARC v7, v8, and V9
-
-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.
-
-This document is a detailed users guide for a
-functionally compliant real-time multiprocessor executive. It
-describes the user interface and run-time behavior of Release
-4.10.99.0 of the C interface
-to RTEMS.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: This chapter is missing the following figures:
-
-.. COMMENT: Figure 1-1 RTEMS Application Architecture
-
-.. COMMENT: Figure 1-2 RTEMS Internal Architecture
-
-Overview
-########
-
-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.
-
-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.
-
-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.
-
-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.
-
-.. code:: c
-
- +-----------------------------------------------------------+
- | Application Dependent Software |
- | +----------------------------------------+ |
- | | Standard Application Components | |
- | | +-------------+---+ |
- | +---+-----------+ | | |
- | | Board Support | | RTEMS | |
- | | Package | | | |
- +----+---------------+--------------+-----------------+-----|
- | Target Hardware |
- +-----------------------------------------------------------+
-
-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.
-
-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:
-
-.. code:: c
-
- +-----------------------------------------------+
- | RTEMS Executive Interface |
- +-----------------------------------------------+
- | RTEMS Core |
- +-----------------------------------------------+
- | CPU Dependent Code |
- +-----------------------------------------------+
-
-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
-
-User Customization and Extensibility
-====================================
-
-As thirty-two 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 thirty-two 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.
-
-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.
-
-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 fileystems,
-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`_.
-
-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.
-
-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.
-
-Conventions
-===========
-
-The following conventions are used in this manual:
-
-- Significant words or phrases as well as all directive
- names are printed in bold type.
-
-- Items in bold capital letters are constants defined by
- RTEMS. Each language interface provided by RTEMS includes a
- file containing the standard set of constants, data types, and
- structure definitions which can be incorporated into the user
- application.
-
-- A number of type definitions are provided by RTEMS and
- can be found in rtems.h.
-
-- The characters "0x" preceding a number indicates that
- the number is in hexadecimal format. Any other numbers are
- assumed to be in decimal format.
-
-Manual Organization
-===================
-
-This first chapter has presented the introductory and
-background material for the RTEMS executive. The remaining
-chapters of this manual present a detailed description of RTEMS
-and the environment, including run time behavior, it creates for
-the user.
-
-A chapter is dedicated to each manager and provides a
-detailed discussion of each RTEMS manager and the directives
-which it provides. The presentation format for each directive
-includes the following sections:
-
-- Calling sequence
-
-- Directive status codes
-
-- Description
-
-- Notes
-
-The following provides an overview of the remainder
-of this manual:
-
-Chapter 2:
- Key Concepts: presents an introduction to the ideas which are common
- across multiple RTEMS managers.
-
-Chapter 3:
- RTEMS Data Types: describes the fundamental data types shared
- by the services in the RTEMS Classic API.
-
-Chapter 4:
- Scheduling Concepts: details the various RTEMS scheduling algorithms
- and task state transitions.
-
-Chapter 5:
- Initialization Manager: describes the functionality and directives
- provided by the Initialization Manager.
-
-Chapter 6:
- Task Manager: describes the functionality and directives provided
- by the Task Manager.
-
-Chapter 7:
- Interrupt Manager: describes the functionality and directives
- provided by the Interrupt Manager.
-
-Chapter 8:
- Clock Manager: describes the functionality and directives
- provided by the Clock Manager.
-
-Chapter 9:
- Timer Manager: describes the functionality and directives provided
- by the Timer Manager.
-
-Chapter 10:
- Rate Monotonic Manager: describes the functionality and directives
- provided by the Rate Monotonic Manager.
-
-Chapter 11:
- Semaphore Manager: describes the functionality and directives
- provided by the Semaphore Manager.
-
-Chapter 12:
- Barrier Manager: describes the functionality and directives
- provided by the Barrier Manager.
-
-Chapter 13:
- Message Manager: describes the functionality and directives
- provided by the Message Manager.
-
-Chapter 14:
- Event Manager: describes the
- functionality and directives provided by the Event Manager.
-
-Chapter 15:
- Signal Manager: describes the
- functionality and directives provided by the Signal Manager.
-
-Chapter 16:
- Partition Manager: describes the
- functionality and directives provided by the Partition Manager.
-
-Chapter 17:
- Region Manager: describes the
- functionality and directives provided by the Region Manager.
-
-Chapter 18:
- Dual-Ported Memory Manager: describes
- the functionality and directives provided by the Dual-Ported
- Memory Manager.
-
-Chapter 19:
- I/O Manager: describes the
- functionality and directives provided by the I/O Manager.
-
-Chapter 20:
- Fatal Error Manager: describes the functionality and directives
- provided by the Fatal Error Manager.
-
-Chapter 21:
- Board Support Packages: defines the
- functionality required of user-supplied board support packages.
-
-Chapter 22:
- User Extensions: shows the user how to
- extend RTEMS to incorporate custom features.
-
-Chapter 23:
- Configuring a System: details the process by which one tailors RTEMS
- for a particular single-processor or multiprocessor application.
-
-Chapter 24:
- Multiprocessing Manager: presents a
- conceptual overview of the multiprocessing capabilities provided
- by RTEMS as well as describing the Multiprocessing
- Communications Interface Layer and Multiprocessing Manager
- directives.
-
-Chapter 25:
- Stack Bounds Checker: presents the capabilities of the RTEMS
- task stack checker which can report stack usage as well as detect
- bounds violations.
-
-Chapter 26:
- CPU Usage Statistics: presents the capabilities of the CPU Usage
- statistics gathered on a per task basis along with the mechanisms
- for reporting and resetting the statistics.
-
-Chapter 27:
- Object Services: presents a collection of helper services useful
- when manipulating RTEMS objects. These include methods to assist
- in obtaining an object’s name in printable form. Additional services
- are provided to decompose an object Id and determine which API
- and object class it belongs to.
-
-Chapter 28:
- Chains: presents the methods provided to build, iterate and
- manipulate doubly-linked chains. This manager makes the
- chain implementation used internally by RTEMS to user space
- applications.
-
-Chapter 29:
- Timespec Helpers: presents a set of helper services useful
- when manipulating POSIX ``struct timespec`` instances.
-
-Chapter 30:
- Constant Bandwidth Server Scheduler API.
-
-Chapter 31:
- Directive Status Codes: provides a definition of each of the
- directive status codes referenced in this manual.
-
-Chapter 32:
- Example Application: provides a template for simple RTEMS applications.
-
-Chapter 33:
- Glossary: defines terms used throughout this manual.
-
-.. COMMENT: COPYRIGHT (c) 1988-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The following figure was replaced with an ASCII equivalent.
-
-.. COMMENT: Figure 2-1 Object ID Composition
-
-Key Concepts
-############
-
-Introduction
-============
-
-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.
-
-Objects
-=======
-
-.. index:: 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.
-
-Object Names
-------------
-.. index:: object name
-.. index:: rtems_object_name
-
-An object name is an unsigned thirty-two bit entity
-associated with the object by the user. The data type``rtems_name`` is used to store object names... index:: rtems_build_name
-
-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:: c
-
- rtems_object_name my_name;
- my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
-
-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... index:: rtems_object_get_name
-
-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.
-
-The following example illustrates the use of this method to print
-an object name:
-.. code:: c
-
- #include <rtems.h>
- #include <rtems/bspIo.h>
- void print_name(rtems_id id)
- {
- char buffer[10]; /* name assumed to be 10 characters or less \*/
- char \*result;
- result = rtems_object_get_name( id, sizeof(buffer), buffer );
- printk( "ID=0x%08x name=%s\\n", id, ((result) ? result : "no name") );
- }
-
-Object IDs
-----------
-
-.. index:: object ID
-.. index:: object ID composition
-.. index:: rtems_id
-
-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 thirty-two bit format which is used for most of the supported
-architectures and supports multiprocessor configurations. There is also
-a simpler sixteen bit format which is appropriate for smaller target
-architectures and does not support multiprocessor configurations.
-
-Thirty-Two Object ID Format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The thirty-two bit format for an object ID is composed of four parts: API,
-object class, node, and index. The data type ``rtems_id``
-is used to store object IDs.
-
-.. code:: c
-
- 31 27 26 24 23 16 15 0
- +---------+-------+--------------+-------------------------------+
- | | | | |
- | Class | API | Node | Index |
- | | | | |
- +---------+-------+--------------+-------------------------------+
-
-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 sixteen bits form an
-identifier within a particular object type. This identifier,
-called the object index, ranges in value from 1 to the maximum
-number of objects configured for this object type.
-
-Sixteen Bit Object ID Format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The sixteen bit format for an object ID is composed of three parts: API,
-object class, and index. The data type ``rtems_id``
-is used to store object IDs.
-
-.. code:: c
-
- 15 11 10 8 7 0
- +---------+-------+--------------+
- | | | |
- | Class | API | Index |
- | | | |
- +---------+-------+--------------+
-
-The sixteen-bit format is designed to be as similar as possible to the
-thrity-two bit format. The differences are limited to the eliminatation
-of the node field and reduction of the index field from sixteen-bits
-to 8-bits. Thus the sixteen bit format only supports up to 255 object
-instances per API/Class combination and single processor systems.
-As this format is typically utilized by sixteen-bit processors with
-limited address space, this is more than enough object instances.
-
-Object ID 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:.. index:: obtaining class from object ID
-.. index:: obtaining node from object ID
-.. index:: obtaining index from object ID
-.. index:: get class from object ID
-.. index:: get node from object ID
-.. index:: get index from object ID
-.. index:: rtems_object_id_get_api
-.. index:: rtems_object_id_get_class
-.. index:: rtems_object_id_get_node
-.. index:: rtems_object_id_get_index
-
-.. code:: c
-
- uint32_t rtems_object_id_get_api( rtems_id );
- uint32_t rtems_object_id_get_class( rtems_id );
- uint32_t rtems_object_id_get_node( rtems_id );
- uint32_t rtems_object_id_get_index( rtems_id );
-
-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.
-
-Communication and Synchronization
-=================================
-.. index:: 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
-
-- 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:
-
-- Semaphore
-
-- Message Queue
-
-- Event
-
-- Signal
-
-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.
-
-Time
-====
-.. index:: 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... index:: rtems_interval
-
-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``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 ``rtems_time_of_day`` is used to specify
-calendar time in RTEMS services.
-See `Time and Date Data Structures`_
-
-... index:: rtems_time_of_day
-
-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.
-
-Memory Management
-=================
-.. index:: 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:
-
-- Region
-
-- Partition
-
-- Dual Ported Memory
-
-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.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-RTEMS Data Types
-################
-
-Introduction
-============
-
-This chapter contains a complete list of the RTEMS primitive
-data types in alphabetical order. This is intended to be
-an overview and the user is encouraged to look at the appropriate
-chapters in the manual for more information about the
-usage of the various data types.
-
-List of Data Types
-==================
-
-The following is a complete list of the RTEMS primitive
-data types in alphabetical order:
-
-- .. index:: rtems_address
-
- ``rtems_address`` is the data type used to manage
- addresses. It is equivalent to
- a "void \*" pointer.
-
-- .. index:: rtems_asr
-
- ``rtems_asr`` is the return type for an
- RTEMS ASR.
-
-- .. index:: rtems_asr_entry
-
- ``rtems_asr_entry`` is the address of
- the entry point to an RTEMS ASR.
-
-- .. index:: rtems_attribute
-
- ``rtems_attribute`` is the data type used
- to manage the attributes for RTEMS objects. It is primarily
- used as an argument to object create routines to specify
- characteristics of the new object.
-
-- .. index:: rtems_boolean
-
- ``rtems_boolean`` may only take on the
- values of ``TRUE`` and ``FALSE``.
- This type is deprecated. Use "bool" instead.
-
-- .. index:: rtems_context
-
- ``rtems_context`` is the CPU dependent
- data structure used to manage the integer and system
- register portion of each task’s context.
-
-- .. index:: rtems_context_fp
-
- ``rtems_context_fp`` is the CPU dependent
- data structure used to manage the floating point portion of
- each task’s context.
-
-- .. index:: rtems_device_driver
-
- ``rtems_device_driver`` is the
- return type for a RTEMS device driver routine.
-
-- .. index:: rtems_device_driver_entry
-
- ``rtems_device_driver_entry`` is the
- entry point to a RTEMS device driver routine.
-
-- .. index:: rtems_device_major_number
-
- ``rtems_device_major_number`` is the
- data type used to manage device major numbers.
-
-- .. index:: rtems_device_minor_number
-
- ``rtems_device_minor_number`` is the
- data type used to manage device minor numbers.
-
-- .. index:: rtems_double
-
- ``rtems_double`` is the RTEMS data
- type that corresponds to double precision floating point
- on the target hardware.
- This type is deprecated. Use "double" instead.
-
-- .. index:: rtems_event_set
-
- ``rtems_event_set`` is the data
- type used to manage and manipulate RTEMS event sets
- with the Event Manager.
-
-- .. index:: rtems_extension
-
- ``rtems_extension`` is the return type
- for RTEMS user extension routines.
-
-- .. index:: rtems_fatal_extension
-
- ``rtems_fatal_extension`` is the
- entry point for a fatal error user extension handler routine.
-
-- .. index:: rtems_id
-
- ``rtems_id`` is the data type used
- to manage and manipulate RTEMS object IDs.
-
-- .. index:: rtems_interrupt_frame
-
- ``rtems_interrupt_frame`` is the
- data structure that defines the format of the interrupt
- stack frame as it appears to a user ISR. This data
- structure may not be defined on all ports.
-
-- .. index:: rtems_interrupt_level
-
- ``rtems_interrupt_level`` is the
- data structure used with the ``rtems_interrupt_disable``,``rtems_interrupt_enable``, and``rtems_interrupt_flash`` routines. This
- data type is CPU dependent and usually corresponds to
- the contents of the processor register containing
- the interrupt mask level.
-
-- .. index:: rtems_interval
-
- ``rtems_interval`` is the data
- type used to manage and manipulate time intervals.
- Intervals are non-negative integers used to measure
- the length of time in clock ticks.
-
-- .. index:: rtems_isr
-
- ``rtems_isr`` is the return type
- of a function implementing an RTEMS ISR.
-
-- .. index:: rtems_isr_entry
-
- ``rtems_isr_entry`` is the address of
- the entry point to an RTEMS ISR. It is equivalent to the
- entry point of the function implementing the ISR.
-
-- .. index:: rtems_mp_packet_classes
-
- ``rtems_mp_packet_classes`` is the
- enumerated type which specifies the categories of
- multiprocessing messages. For example, one of the
- classes is for messages that must be processed by
- the Task Manager.
-
-- .. index:: rtems_mode
-
- ``rtems_mode`` is the data type
- used to manage and dynamically manipulate the execution
- mode of an RTEMS task.
-
-- .. index:: rtems_mpci_entry
-
- ``rtems_mpci_entry`` is the return type
- of an RTEMS MPCI routine.
-
-- .. index:: rtems_mpci_get_packet_entry
-
- ``rtems_mpci_get_packet_entry`` is the address of
- the entry point to the get packet routine for an MPCI implementation.
-
-- .. index:: rtems_mpci_initialization_entry
-
- ``rtems_mpci_initialization_entry`` is the address of
- the entry point to the initialization routine for an MPCI implementation.
-
-- .. index:: rtems_mpci_receive_packet_entry
-
- ``rtems_mpci_receive_packet_entry`` is the address of
- the entry point to the receive packet routine for an MPCI implementation.
-
-- .. index:: rtems_mpci_return_packet_entry
-
- ``rtems_mpci_return_packet_entry`` is the address of
- the entry point to the return packet routine for an MPCI implementation.
-
-- .. index:: rtems_mpci_send_packet_entry
-
- ``rtems_mpci_send_packet_entry`` is the address of
- the entry point to the send packet routine for an MPCI implementation.
-
-- .. index:: rtems_mpci_table
-
- ``rtems_mpci_table`` is the data structure
- containing the configuration information for an MPCI.
-
-- .. index:: rtems_name
-
- ``rtems_name`` is the data type used to
- contain the name of a Classic API object. It is an unsigned
- thirty-two bit integer which can be treated as a numeric
- value or initialized using ``rtems_build_name`` to
- contain four ASCII characters.
-
-- .. index:: rtems_option
-
- ``rtems_option`` is the data type
- used to specify which behavioral options the caller desires.
- It is commonly used with potentially blocking directives to specify
- whether the caller is willing to block or return immediately with an error
- indicating that the resource was not available.
-
-- .. index:: rtems_packet_prefix
-
- ``rtems_packet_prefix`` is the data structure
- that defines the first bytes in every packet sent between nodes
- in an RTEMS multiprocessor system. It contains routing information
- that is expected to be used by the MPCI layer.
-
-- .. index:: rtems_signal_set
-
- ``rtems_signal_set`` is the data
- type used to manage and manipulate RTEMS signal sets
- with the Signal Manager.
-
-- .. index:: int8_t
-
- ``int8_t`` is the C99 data type that corresponds to signed eight
- bit integers. This data type is defined by RTEMS in a manner that
- ensures it is portable across different target processors.
-
-- .. index:: int16_t
-
- ``int16_t`` is the C99 data type that corresponds to signed
- sixteen bit integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-- .. index:: int32_t
-
- ``int32_t`` is the C99 data type that corresponds to signed
- thirty-two bit integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-- .. index:: int64_t
-
- ``int64_t`` is the C99 data type that corresponds to signed
- sixty-four bit integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-- .. index:: rtems_single
-
- ``rtems_single`` is the RTEMS data
- type that corresponds to single precision floating point
- on the target hardware.
- This type is deprecated. Use "float" instead.
-
-- .. index:: rtems_status_codes
-
- ``rtems_status_codes`` is the return type for most
- RTEMS services. This is an enumerated type of approximately twenty-five
- values. In general, when a service returns a particular status code, it
- indicates that a very specific error condition has occurred.
-
-- .. index:: rtems_task
-
- ``rtems_task`` is the return type for an
- RTEMS Task.
-
-- .. index:: rtems_task_argument
-
- ``rtems_task_argument`` is the data
- type for the argument passed to each RTEMS task. In RTEMS 4.7
- and older, this is an unsigned thirty-two bit integer. In
- RTEMS 4.8 and newer, this is based upon the C99 type ``uintptr_t``
- which is guaranteed to be an integer large enough to hold a
- pointer on the target architecture.
-
-- .. index:: rtems_task_begin_extension
-
- ``rtems_task_begin_extension`` is the
- entry point for a task beginning execution user extension handler routine.
-
-- .. index:: rtems_task_create_extension
-
- ``rtems_task_create_extension`` is the
- entry point for a task creation execution user extension handler routine.
-
-- .. index:: rtems_task_delete_extension
-
- ``rtems_task_delete_extension`` is the
- entry point for a task deletion user extension handler routine.
-
-- .. index:: rtems_task_entry
-
- ``rtems_task_entry`` is the address of
- the entry point to an RTEMS ASR. It is equivalent to the
- entry point of the function implementing the ASR.
-
-- .. index:: rtems_task_exitted_extension
-
- ``rtems_task_exitted_extension`` is the
- entry point for a task exitted user extension handler routine.
-
-- .. index:: rtems_task_priority
-
- ``rtems_task_priority`` is the data type
- used to manage and manipulate task priorities.
-
-- .. index:: rtems_task_restart_extension
-
- ``rtems_task_restart_extension`` is the
- entry point for a task restart user extension handler routine.
-
-- .. index:: rtems_task_start_extension
-
- ``rtems_task_start_extension`` is the
- entry point for a task start user extension handler routine.
-
-- .. index:: rtems_task_switch_extension
-
- ``rtems_task_switch_extension`` is the
- entry point for a task context switch user extension handler routine.
-
-- .. index:: rtems_tcb
-
- ``rtems_tcb`` is the data structure associated
- with each task in an RTEMS system.
-
-- .. index:: rtems_time_of_day
-
- ``rtems_time_of_day`` is the data structure
- used to manage and manipulate calendar time in RTEMS.
-
-- .. index:: rtems_timer_service_routine
-
- ``rtems_timer_service_routine`` is the
- return type for an RTEMS Timer Service Routine.
-
-- .. index:: rtems_timer_service_routine_entry
-
- ``rtems_timer_service_routine_entry`` is the address of
- the entry point to an RTEMS TSR. It is equivalent to the
- entry point of the function implementing the TSR.
-
-- .. index:: rtems_vector_number
-
- ``rtems_vector_number`` is the data
- type used to manage and manipulate interrupt vector numbers.
-
-- .. index:: uint8_t
-
- ``uint8_t`` is the C99 data type that corresponds to unsigned
- eight bit integers. This data type is defined by RTEMS in a manner that
- ensures it is portable across different target processors.
-
-- .. index:: uint16_t
-
- ``uint16_t`` is the C99 data type that corresponds to unsigned
- sixteen bit integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-- .. index:: uint32_t
-
- ``uint32_t`` is the C99 data type that corresponds to unsigned
- thirty-two bit integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-- .. index:: uint64_t
-
- ``uint64_t`` is the C99 data type that corresponds to unsigned
- sixty-four bit integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-- .. index:: uintptr_t
-
- ``uintptr_t`` is the C99 data type that corresponds to the
- unsigned integer type that is of sufficient size to represent addresses
- as unsigned integers. This data type is defined by RTEMS in a manner
- that ensures it is portable across different target processors.
-
-.. COMMENT: COPYRIGHT (c) 1988-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Scheduling Concepts
-###################
-
-.. index:: scheduling
-.. index:: task scheduling
-
-Introduction
-============
-
-The concept of scheduling in real-time systems dictates the ability to
-provide immediate response to specific external events, particularly
-the necessity of scheduling tasks to run within a specified time limit
-after the occurrence of an event. For example, software embedded in
-life-support systems used to monitor hospital patients must take instant
-action if a change in the patient’s status is detected.
-
-The component of RTEMS responsible for providing this capability is
-appropriately called the scheduler. The scheduler’s sole purpose is
-to allocate the all important resource of processor time to the various
-tasks competing for attention.
-
-Scheduling Algorithms
-=====================
-
-.. index:: scheduling algorithms
-
-RTEMS provides a plugin framework which allows it to support
-multiple scheduling algorithms. RTEMS now includes multiple
-scheduling algorithms in the SuperCore and the user can select which
-of these they wish to use in their application. In addition,
-the user can implement their own scheduling algorithm and
-configure RTEMS to use it.
-
-Supporting multiple scheduling algorithms gives the end user the
-option to select the algorithm which is most appropriate to their use
-case. Most real-time operating systems schedule tasks using a priority
-based algorithm, possibly with preemption control. The classic
-RTEMS scheduling algorithm which was the only algorithm available
-in RTEMS 4.10 and earlier, is a priority based scheduling algorithm.
-This scheduling algoritm is suitable for single core (e.g. non-SMP)
-systems and is now known as the *Deterministic Priority Scheduler*.
-Unless the user configures another scheduling algorithm, RTEMS will use
-this on single core systems.
-
-Priority Scheduling
--------------------
-.. index:: priority scheduling
-
-When using priority based scheduling, RTEMS allocates the processor using
-a priority-based, preemptive algorithm augmented to provide round-robin
-characteristics within individual priority groups. The goal of this
-algorithm is to guarantee that the task which is executing on the
-processor at any point in time is the one with the highest priority
-among all tasks in the ready state.
-
-When a task is added to the ready chain, it is placed behind all other
-tasks of the same priority. This rule provides a round-robin within
-priority group scheduling characteristic. This means that in a group of
-equal priority tasks, tasks will execute in the order they become ready
-or FIFO order. Even though there are ways to manipulate and adjust task
-priorities, the most important rule to remember is:
-
-- *Priority based scheduling algorithms will always select the
- highest priority task that is ready to run when allocating the processor
- to a task.*
-
-Priority scheduling is the most commonly used scheduling algorithm.
-It should be used by applications in which multiple tasks contend for
-CPU time or other resources and there is a need to ensure certain tasks
-are given priority over other tasks.
-
-There are a few common methods of accomplishing the mechanics of this
-algorithm. These ways involve a list or chain of tasks in the ready state.
-
-- The least efficient method is to randomly place tasks in the ready
- chain forcing the scheduler to scan the entire chain to determine which
- task receives the processor.
-
-- A more efficient method is to schedule the task by placing it
- in the proper place on the ready chain based on the designated scheduling
- criteria at the time it enters the ready state. Thus, when the processor
- is free, the first task on the ready chain is allocated the processor.
-
-- Another mechanism is to maintain a list of FIFOs per priority.
- When a task is readied, it is placed on the rear of the FIFO for its
- priority. This method is often used with a bitmap to assist in locating
- which FIFOs have ready tasks on them.
-
-RTEMS currently includes multiple priority based scheduling algorithms
-as well as other algorithms which incorporate deadline. Each algorithm
-is discussed in the following sections.
-
-Deterministic Priority Scheduler
---------------------------------
-
-This is the scheduler implementation which has always been in RTEMS.
-After the 4.10 release series, it was factored into pluggable scheduler
-selection. It schedules tasks using a priority based algorithm which
-takes into account preemption. It is implemented using an array of FIFOs
-with a FIFO per priority. It maintains a bitmap which is used to track
-which priorities have ready tasks.
-
-This algorithm is deterministic (e.g. predictable and fixed) in execution
-time. This comes at the cost of using slightly over three (3) kilobytes
-of RAM on a system configured to support 256 priority levels.
-
-This scheduler is only aware of a single core.
-
-Simple Priority Scheduler
--------------------------
-
-This scheduler implementation has the same behaviour as the Deterministic
-Priority Scheduler but uses only one linked list to manage all ready
-tasks. When a task is readied, a linear search of that linked list is
-performed to determine where to insert the newly readied task.
-
-This algorithm uses much less RAM than the Deterministic Priority
-Scheduler but is *O(n)* where *n* is the number of ready tasks.
-In a small system with a small number of tasks, this will not be a
-performance issue. Reducing RAM consumption is often critical in small
-systems which are incapable of supporting a large number of tasks.
-
-This scheduler is only aware of a single core.
-
-Simple SMP Priority Scheduler
------------------------------
-
-This scheduler is based upon the Simple Priority Scheduler and is designed
-to have the same behaviour on a single core system. But this scheduler
-is capable of scheduling threads across multiple cores in an SMP system.
-When given a choice of replacing one of two threads at equal priority
-on different cores, this algorithm favors replacing threads which are
-preemptible and have executed the longest.
-
-This algorithm is non-deterministic. When scheduling, it must consider
-which tasks are to be executed on each core while avoiding superfluous
-task migrations.
-
-Earliest Deadline First Scheduler
----------------------------------
-.. index:: earliest deadline first scheduling
-
-This is an alternative scheduler in RTEMS for single core applications.
-The primary EDF advantage is high total CPU utilization (theoretically
-up to 100%). It assumes that tasks have priorities equal to deadlines.
-
-This EDF is initially preemptive, however, individual tasks may be declared
-not-preemptive. Deadlines are declared using only Rate Monotonic manager which
-goal is to handle periodic behavior. Period is always equal to deadline. All
-ready tasks reside in a single ready queue implemented using a red-black tree.
-
-This implementation of EDF schedules two different types of task
-priority types while each task may switch between the two types within
-its execution. If a task does have a deadline declared using the Rate
-Monotonic manager, the task is deadline-driven and its priority is equal
-to deadline. On the contrary if a task does not have any deadline or
-the deadline is cancelled using the Rate Monotonic manager, the task is
-considered a background task with priority equal to that assigned
-upon initialization in the same manner as for priority scheduler. Each
-background task is of a lower importance than each deadline-driven one
-and is scheduled when no deadline-driven task and no higher priority
-background task is ready to run.
-
-Every deadline-driven scheduling algorithm requires means for tasks
-to claim a deadline. The Rate Monotonic Manager is responsible for
-handling periodic execution. In RTEMS periods are equal to deadlines,
-thus if a task announces a period, it has to be finished until the
-end of this period. The call of ``rtems_rate_monotonic_period``
-passes the scheduler the length of oncoming deadline. Moreover, the``rtems_rate_monotonic_cancel`` and ``rtems_rate_monotonic_delete``
-calls clear the deadlines assigned to the task.
-
-Constant Bandwidth Server Scheduling (CBS)
-------------------------------------------
-.. index:: constant bandwidth server scheduling
-
-This is an alternative scheduler in RTEMS for single core applications.
-The CBS is a budget aware extension of EDF scheduler. The main goal of this
-scheduler is to ensure temporal isolation of tasks meaning that a task’s
-execution in terms of meeting deadlines must not be influenced by other
-tasks as if they were run on multiple independent processors.
-
-Each task can be assigned a server (current implementation supports only
-one task per server). The server is characterized by period (deadline)
-and computation time (budget). The ratio budget/period yields bandwidth,
-which is the fraction of CPU to be reserved by the scheduler for each
-subsequent period.
-
-The CBS is equipped with a set of rules applied to tasks attached to servers
-ensuring that deadline miss because of another task cannot occur.
-In case a task breaks one of the rules, its priority is pulled to background
-until the end of its period and then restored again. The rules are:
-
-- Task cannot exceed its registered budget,
-
-- Task cannot be
- unblocked when a ratio between remaining budget and remaining deadline
- is higher than declared bandwidth.
-
-The CBS provides an extensive API. Unlike EDF, the``rtems_rate_monotonic_period`` does not declare a deadline because
-it is carried out using CBS API. This call only announces next period.
-
-Scheduling Modification Mechanisms
-==================================
-
-.. index:: scheduling mechanisms
-
-RTEMS provides four mechanisms which allow the user to alter the task
-scheduling decisions:
-
-- user-selectable task priority level
-
-- task preemption control
-
-- task timeslicing control
-
-- manual round-robin selection
-
-Each of these methods provides a powerful capability to customize sets
-of tasks to satisfy the unique and particular requirements encountered
-in custom real-time applications. Although each mechanism operates
-independently, there is a precedence relationship which governs the
-effects of scheduling modifications. The evaluation order for scheduling
-characteristics is always priority, preemption mode, and timeslicing.
-When reading the descriptions of timeslicing and manual round-robin
-it is important to keep in mind that preemption (if enabled) of a task
-by higher priority tasks will occur as required, overriding the other
-factors presented in the description.
-
-Task Priority and Scheduling
-----------------------------
-.. index:: task priority
-
-The most significant task scheduling modification mechanism is the ability
-for the user to assign a priority level to each individual task when it
-is created and to alter a task’s priority at run-time. RTEMS supports
-up to 255 priority levels. Level 255 is the lowest priority and level
-1 is the highest.
-
-Preemption
-----------.. index:: preemption
-
-Another way the user can alter the basic scheduling algorithm is by
-manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``)
-of individual tasks. If preemption is disabled for a task
-(``RTEMS_NO_PREEMPT``), then the task will not relinquish
-control of the processor until it terminates, blocks, or re-enables
-preemption. Even tasks which become ready to run and possess higher
-priority levels will not be allowed to execute. Note that the preemption
-setting has no effect on the manner in which a task is scheduled.
-It only applies once a task has control of the processor.
-
-Timeslicing
------------.. index:: timeslicing
-.. index:: round robin scheduling
-
-Timeslicing or round-robin scheduling is an additional method which
-can be used to alter the basic scheduling algorithm. Like preemption,
-timeslicing is specified on a task by task basis using the timeslicing
-mode flag (``RTEMS_TIMESLICE_MASK``). If timeslicing is
-enabled for a task (``RTEMS_TIMESLICE``), then RTEMS will
-limit the amount of time the task can execute before the processor is
-allocated to another task. Each tick of the real-time clock reduces
-the currently running task’s timeslice. When the execution time equals
-the timeslice, RTEMS will dispatch another task of the same priority
-to execute. If there are no other tasks of the same priority ready to
-execute, then the current task is allocated an additional timeslice and
-continues to run. Remember that a higher priority task will preempt
-the task (unless preemption is disabled) as soon as it is ready to run,
-even if the task has not used up its entire timeslice.
-
-Manual Round-Robin
-------------------.. index:: manual round robin
-
-The final mechanism for altering the RTEMS scheduling algorithm is
-called manual round-robin. Manual round-robin is invoked by using the``rtems_task_wake_after`` directive with a time interval
-of ``RTEMS_YIELD_PROCESSOR``. This allows a task to give
-up the processor and be immediately returned to the ready chain at the
-end of its priority group. If no other tasks of the same priority are
-ready to run, then the task does not lose control of the processor.
-
-Dispatching Tasks
-=================.. index:: dispatching
-
-The dispatcher is the RTEMS component responsible for
-allocating the processor to a ready task. In order to allocate
-the processor to one task, it must be deallocated or retrieved
-from the task currently using it. This involves a concept
-called a context switch. To perform a context switch, the
-dispatcher saves the context of the current task and restores
-the context of the task which has been allocated to the
-processor. Saving and restoring a task’s context is the
-storing/loading of all the essential information about a task to
-enable it to continue execution without any effects of the
-interruption. For example, the contents of a task’s register
-set must be the same when it is given the processor as they were
-when it was taken away. All of the information that must be
-saved or restored for a context switch is located either in the
-TCB or on the task’s stacks.
-
-Tasks that utilize a numeric coprocessor and are created with the``RTEMS_FLOATING_POINT`` attribute require additional
-operations during a context switch. These additional operations
-are necessary to save and restore the floating point context of``RTEMS_FLOATING_POINT`` tasks. To avoid unnecessary save
-and restore operations, the state of the numeric coprocessor is only
-saved when a ``RTEMS_FLOATING_POINT`` task is dispatched
-and that task was not the last task to utilize the coprocessor.
-
-Task State Transitions
-======================.. index:: task state transitions
-
-Tasks in an RTEMS system must always be in one of the
-five allowable task states. These states are: executing, ready,
-blocked, dormant, and non-existent.
-
-A task occupies the non-existent state before
-a ``rtems_task_create`` has been issued on its behalf.
-A task enters the non-existent state from any other state in the system
-when it is deleted with the ``rtems_task_delete`` directive.
-While a task occupies this state it does not have a TCB or a task ID
-assigned to it; therefore, no other tasks in the system may reference
-this task.
-
-When a task is created via the ``rtems_task_create``
-directive it enters the dormant state. This state is not entered through
-any other means. Although the task exists in the system, it cannot
-actively compete for system resources. It will remain in the dormant
-state until it is started via the ``rtems_task_start``
-directive, at which time it enters the ready state. The task is now
-permitted to be scheduled for the processor and to compete for other
-system resources.
-
-.. code:: c
-
- +-------------------------------------------------------------+
- | Non-existent |
- | +-------------------------------------------------------+ |
- | | | |
- | | | |
- | | Creating +---------+ Deleting | |
- | | -------------------> | Dormant | -------------------> | |
- | | +---------+ | |
- | | | | |
- | | Starting | | |
- | | | | |
- | | V Deleting | |
- | | +-------> +-------+ -------------------> | |
- | | Yielding / +----- | Ready | ------+ | |
- | | / / +-------+ <--+ \\ | |
- | | / / \\ \\ Blocking | |
- | | / / Dispatching Readying \\ \\ | |
- | | / V \\ V | |
- | | +-----------+ Blocking +---------+ | |
- | | | Executing | --------------> | Blocked | | |
- | | +-----------+ +---------+ | |
- | | | |
- | | | |
- | +-------------------------------------------------------+ |
- | Non-existent |
- +-------------------------------------------------------------+
-
-A task occupies the blocked state whenever it is unable to be scheduled
-to run. A running task may block itself or be blocked by other tasks in
-the system. The running task blocks itself through voluntary operations
-that cause the task to wait. The only way a task can block a task other
-than itself is with the ``rtems_task_suspend`` directive.
-A task enters the blocked state due to any of the following conditions:
-
-- A task issues a ``rtems_task_suspend`` directive
- which blocks either itself or another task in the system.
-
-- The running task issues a ``rtems_barrier_wait``
- directive.
-
-- The running task issues a ``rtems_message_queue_receive``
- directive with the wait option and the message queue is empty.
-
-- The running task issues an ``rtems_event_receive``
- directive with the wait option and the currently pending events do not
- satisfy the request.
-
-- The running task issues a ``rtems_semaphore_obtain``
- directive with the wait option and the requested semaphore is unavailable.
-
-- The running task issues a ``rtems_task_wake_after``
- directive which blocks the task for the given time interval. If the time
- interval specified is zero, the task yields the processor and remains
- in the ready state.
-
-- The running task issues a ``rtems_task_wake_when``
- directive which blocks the task until the requested date and time arrives.
-
-- The running task issues a ``rtems_rate_monotonic_period``
- directive and must wait for the specified rate monotonic period
- to conclude.
-
-- The running task issues a ``rtems_region_get_segment``
- directive with the wait option and there is not an available segment large
- enough to satisfy the task’s request.
-
-A blocked task may also be suspended. Therefore, both the suspension
-and the blocking condition must be removed before the task becomes ready
-to run again.
-
-A task occupies the ready state when it is able to be scheduled to run,
-but currently does not have control of the processor. Tasks of the same
-or higher priority will yield the processor by either becoming blocked,
-completing their timeslice, or being deleted. All tasks with the same
-priority will execute in FIFO order. A task enters the ready state due
-to any of the following conditions:
-
-- A running task issues a ``rtems_task_resume``
- directive for a task that is suspended and the task is not blocked
- waiting on any resource.
-
-- A running task issues a ``rtems_message_queue_send``,``rtems_message_queue_broadcast``, or a``rtems_message_queue_urgent`` directive
- which posts a message to the queue on which the blocked task is
- waiting.
-
-- A running task issues an ``rtems_event_send``
- directive which sends an event condition to a task which is blocked
- waiting on that event condition.
-
-- A running task issues a ``rtems_semaphore_release``
- directive which releases the semaphore on which the blocked task is
- waiting.
-
-- A timeout interval expires for a task which was blocked
- by a call to the ``rtems_task_wake_after`` directive.
-
-- A timeout period expires for a task which blocked by a
- call to the ``rtems_task_wake_when`` directive.
-
-- A running task issues a ``rtems_region_return_segment``
- directive which releases a segment to the region on which the blocked task
- is waiting and a resulting segment is large enough to satisfy
- the task’s request.
-
-- A rate monotonic period expires for a task which blocked
- by a call to the ``rtems_rate_monotonic_period`` directive.
-
-- A timeout interval expires for a task which was blocked
- waiting on a message, event, semaphore, or segment with a
- timeout specified.
-
-- A running task issues a directive which deletes a
- message queue, a semaphore, or a region on which the blocked
- task is waiting.
-
-- A running task issues a ``rtems_task_restart``
- directive for the blocked task.
-
-- The running task, with its preemption mode enabled, may
- be made ready by issuing any of the directives that may unblock
- a task with a higher priority. This directive may be issued
- from the running task itself or from an ISR.
- A ready task occupies the executing state when it has
- control of the CPU. A task enters the executing state due to
- any of the following conditions:
-
-- The task is the highest priority ready task in the
- system.
-
-- The running task blocks and the task is next in the
- scheduling queue. The task may be of equal priority as in
- round-robin scheduling or the task may possess the highest
- priority of the remaining ready tasks.
-
-- The running task may reenable its preemption mode and a
- task exists in the ready queue that has a higher priority than
- the running task.
-
-- The running task lowers its own priority and another
- task is of higher priority as a result.
-
-- The running task raises the priority of a task above its
- own and the running task is in preemption mode.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Initialization Manager
-######################
-
-Introduction
-============
-
-The Initialization Manager is responsible for
-initiating and shutting down RTEMS. Initiating RTEMS involves
-creating and starting all configured initialization tasks, and
-for invoking the initialization routine for each user-supplied
-device driver. In a multiprocessor configuration, this manager
-also initializes the interprocessor communications layer. The
-directives provided by the Initialization Manager are:
-
-- ``rtems_initialize_executive`` - Initialize RTEMS
-
-- ``rtems_shutdown_executive`` - Shutdown RTEMS
-
-Background
-==========
-
-Initialization Tasks
---------------------
-.. index:: initialization tasks
-
-Initialization task(s) are the mechanism by which
-RTEMS transfers initial control to the user’s application.
-Initialization tasks differ from other application tasks in that
-they are defined in the User Initialization Tasks Table and
-automatically created and started by RTEMS as part of its
-initialization sequence. Since the initialization tasks are
-scheduled using the same algorithm as all other RTEMS tasks,
-they must be configured at a priority and mode which will ensure
-that they will complete execution before other application tasks
-execute. Although there is no upper limit on the number of
-initialization tasks, an application is required to define at
-least one.
-
-A typical initialization task will create and start
-the static set of application tasks. It may also create any
-other objects used by the application. Initialization tasks
-which only perform initialization should delete themselves upon
-completion to free resources for other tasks. Initialization
-tasks may transform themselves into a "normal" application task.
-This transformation typically involves changing priority and
-execution mode. RTEMS does not automatically delete the
-initialization tasks.
-
-System Initialization
----------------------
-
-System Initialization begins with board reset and continues
-through RTEMS initialization, initialization of all device
-drivers, and eventually a context switch to the first user
-task. Remember, that interrupts are disabled during
-initialization and the *initialization context* is not
-a task in any sense and the user should be very careful
-during initialization.
-
-The BSP must ensure that the there is enough stack
-space reserved for the initialization context to
-successfully execute the initialization routines for
-all device drivers and, in multiprocessor configurations, the
-Multiprocessor Communications Interface Layer initialization
-routine.
-
-The Idle Task
--------------
-
-The Idle Task is the lowest priority task in a system
-and executes only when no other task is ready to execute. This
-default implementation of this task consists of an infinite
-loop. RTEMS allows the Idle Task body to be replaced by a CPU
-specific implementation, a BSP specific implementation or an
-application specific implementation.
-
-The Idle Task is preemptible and *WILL* be preempted when
-any other task is made ready to execute. This characteristic is
-critical to the overall behavior of any application.
-
-Initialization Manager Failure
-------------------------------
-
-The ``rtems_fatal_error_occurred`` directive will
-be invoked from ``rtems_initialize_executive``
-for any of the following reasons:
-
-- If either the Configuration Table or the CPU Dependent
- Information Table is not provided.
-
-- If the starting address of the RTEMS RAM Workspace,
- supplied by the application in the Configuration Table, is NULL
- or is not aligned on a four-byte boundary.
-
-- If the size of the RTEMS RAM Workspace is not large
- enough to initialize and configure the system.
-
-- If the interrupt stack size specified is too small.
-
-- If multiprocessing is configured and the node entry in
- the Multiprocessor Configuration Table is not between one and
- the maximum_nodes entry.
-
-- If a multiprocessor system is being configured and no
- Multiprocessor Communications Interface is specified.
-
-- If no user initialization tasks are configured. At
- least one initialization task must be configured to allow RTEMS
- to pass control to the application at the end of the executive
- initialization sequence.
-
-- If any of the user initialization tasks cannot be
- created or started successfully.
-
-A discussion of RTEMS actions when a fatal error occurs
-may be found `Announcing a Fatal Error`_.
-
-Operations
-==========
-
-Initializing RTEMS
-------------------
-
-The Initialization Manager ``rtems_initialize_executive``
-directives is called by the ``boot_card`` routine. The ``boot_card``
-routine is invoked by the Board Support Package once a basic C run-time
-environment is set up. This consists of
-
-- a valid and accessible text section, read-only data, read-write data and
- zero-initialized data,
-
-- an initialization stack large enough to initialize the rest of the Board
- Support Package, RTEMS and the device drivers,
-
-- all registers and components mandated by Application Binary Interface, and
-
-- disabled interrupts.
-
-The ``rtems_initialize_executive`` directive uses a system
-initialization linker set to initialize only those parts of the overall RTEMS
-feature set that is necessary for a particular application. See `Linker Sets`_.
-Each RTEMS feature used the application may optionally register an
-initialization handler. The system initialization API is available via``#included <rtems/sysinit.h>``.
-
-A list of all initialization steps follows. Some steps are optional depending
-on the requested feature set of the application. The initialization steps are
-execute in the order presented here.
-
-:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS`
- The work areas consisting of C Program Heap and the RTEMS Workspace are
- initialized by the Board Support Package. This step is mandatory.
-
-:dfn:`RTEMS_SYSINIT_BSP_START`
- Basic initialization step provided by the Board Support Package. This step is
- mandatory.
-
-:dfn:`RTEMS_SYSINIT_DATA_STRUCTURES`
- This directive is called when the Board Support Package has completed its basic
- initialization and allows RTEMS to initialize the application environment based
- upon the information in the Configuration Table, User Initialization Tasks
- Table, Device Driver Table, User Extension Table, Multiprocessor Configuration
- Table, and the Multiprocessor Communications Interface (MPCI) Table.
-
-:dfn:`RTEMS_SYSINIT_BSP_LIBC`
- Depending on the application configuration the IO library and root filesystem
- is initialized. This step is mandatory.
-
-:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS`
- This directive performs initialization that must occur between basis RTEMS data
- structure initialization and device driver initialization. In particular, in a
- multiprocessor configuration, this directive will create the MPCI Server Task.
-
-:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
- Initialization step performed right before device drivers are initialized
- provided by the Board Support Package. This step is mandatory.
-
-:dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS`
- This step initializes all statically configured device drivers and performs all
- RTEMS initialization which requires device drivers to be initialized. This
- step is mandatory.
- In a multiprocessor configuration, this service will initialize the
- Multiprocessor Communications Interface (MPCI) and synchronize with the other
- nodes in the system.
-
-:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS`
- Initialization step performed right after device drivers are initialized
- provided by the Board Support Package. This step is mandatory.
-
-The final action of the ``rtems_initialize_executive`` directive
-is to start multitasking. RTEMS does not return to the initialization context
-and the initialization stack may be re-used for interrupt processing.
-
-Many of RTEMS actions during initialization are based upon
-the contents of the Configuration Table. For more information
-regarding the format and contents of this table, please refer
-to the chapter `Configuring a System`_.
-
-The final action in the initialization sequence is the
-initiation of multitasking. When the scheduler and dispatcher
-are enabled, the highest priority, ready task will be dispatched
-to run. Control will not be returned to the Board Support
-Package after multitasking is enabled. The initialization stack may be re-used
-for interrupt processing.
-
-Shutting Down RTEMS
--------------------
-
-The ``rtems_shutdown_executive`` directive is invoked by the
-application to end multitasking and terminate the system.
-
-Directives
-==========
-
-This section details the Initialization Manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-INITIALIZE_EXECUTIVE - Initialize RTEMS
----------------------------------------
-.. index:: initialize RTEMS
-.. index:: start multitasking
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_initialize_executive
-
-.. code:: c
-
- void rtems_initialize_executive(void);
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-Iterates through the system initialization linker set and invokes the
-registered handlers. The final step is to start multitasking.
-
-**NOTES:**
-
-This directive should be called by ``boot_card`` only.
-
-This directive *does not return* to the caller. Errors in the initialization
-sequence are usually fatal and lead to a system termination.
-
-SHUTDOWN_EXECUTIVE - Shutdown RTEMS
------------------------------------
-.. index:: shutdown RTEMS
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_shutdown_executive
-
-.. code:: c
-
- void rtems_shutdown_executive(
- uint32_t result
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive is called when the application wishes to shutdown RTEMS. The
-system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and
-the specified ``result`` code.
-
-**NOTES:**
-
-This directive *must* be the last RTEMS directive
-invoked by an application and it *does not return* to the caller.
-
-This directive may be called any time.
-
-.. COMMENT: COPYRIGHT (c) 1988-2014.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Task Manager
-############
-
-.. index:: tasks
-
-Introduction
-============
-
-The task manager provides a comprehensive set of directives to
-create, delete, and administer tasks. The directives provided
-by the task manager are:
-
-- ``rtems_task_create`` - Create a task
-
-- ``rtems_task_ident`` - Get ID of a task
-
-- ``rtems_task_self`` - Obtain ID of caller
-
-- ``rtems_task_start`` - Start a task
-
-- ``rtems_task_restart`` - Restart a task
-
-- ``rtems_task_delete`` - Delete a task
-
-- ``rtems_task_suspend`` - Suspend a task
-
-- ``rtems_task_resume`` - Resume a task
-
-- ``rtems_task_is_suspended`` - Determine if a task is suspended
-
-- ``rtems_task_set_priority`` - Set task priority
-
-- ``rtems_task_mode`` - Change current task’s mode
-
-- ``rtems_task_wake_after`` - Wake up after interval
-
-- ``rtems_task_wake_when`` - Wake up when specified
-
-- ``rtems_iterate_over_all_threads`` - Iterate Over Tasks
-
-- ``rtems_task_variable_add`` - Associate per task variable
-
-- ``rtems_task_variable_get`` - Obtain value of a a per task variable
-
-- ``rtems_task_variable_delete`` - Remove per task variable
-
-Background
-==========
-
-Task Definition
----------------
-.. index:: 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).
-
-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.
-
-Task States
------------
-.. index:: 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.
-
-Task Priority
--------------
-.. index:: task priority
-.. index:: priority, task
-.. index:: rtems_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.
-
-Task Mode
----------
-.. index:: task mode
-.. index:: rtems_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... index:: preemption
-
-The preemption component allows a task to determine when control of the
-processor is relinquished. If preemption is disabled
-(``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
-(``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... index:: timeslicing
-
-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 (``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 (``RTEMS_NO_TIMESLICE``), then the task will be
-allowed to execute until a task of higher priority is made ready. If``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 (``RTEMS_ASR``), then signals
-sent to the task will be processed the next time the task executes. If
-signal processing is disabled (``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... index:: interrupt level, task
-
-The interrupt level component is used to determine which
-interrupts will be enabled when the task is executing.``RTEMS_INTERRUPT_LEVEL(n)``
-specifies that the task will execute at interrupt level n.
-
-- ``RTEMS_PREEMPT`` - enable preemption (default)
-
-- ``RTEMS_NO_PREEMPT`` - disable preemption
-
-- ``RTEMS_NO_TIMESLICE`` - disable timeslicing (default)
-
-- ``RTEMS_TIMESLICE`` - enable timeslicing
-
-- ``RTEMS_ASR`` - enable ASR processing (default)
-
-- ``RTEMS_NO_ASR`` - disable ASR processing
-
-- ``RTEMS_INTERRUPT_LEVEL(0)`` - enable all interrupts (default)
-
-- ``RTEMS_INTERRUPT_LEVEL(n)`` - execute at interrupt level n
-
-The set of default modes may be selected by specifying the``RTEMS_DEFAULT_MODES`` constant.
-
-Accessing Task Arguments
-------------------------
-.. index:: task arguments
-.. index:: task prototype
-
-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:.. index:: rtems_task
-
-.. code:: c
-
- rtems_task user_task(
- rtems_task_argument argument
- );
-
-Application tasks requiring more information may view this
-single argument as an index into an array of parameter blocks.
-
-Floating Point Considerations
------------------------------
-.. index:: floating point
-
-Creating a task with the ``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 ``RTEMS_NO_FLOATING_POINT`` tasks. Saving
-and restoring the context of a ``RTEMS_FLOATING_POINT`` task
-takes longer than that of a ``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``RTEMS_FLOATING_POINT`` task is dispatched and that task was
-not the last task to utilize the coprocessor. In a system with only one``RTEMS_FLOATING_POINT`` task, the state of the numeric
-coprocessor will never be saved or restored.
-
-Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks
-is minimal, some applications may wish to completely avoid the overhead
-associated with ``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``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric
-coprocessor without incurring the overhead of a``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 ``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``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 ``RTEMS_NO_FLOATING_POINT``
-whether created as ``RTEMS_FLOATING_POINT`` or``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 ``RTEMS_FLOATING_POINT``
-attribute. The consequence of a ``RTEMS_NO_FLOATING_POINT``
-task attempting to access the floating point unit is CPU dependent but will
-generally result in an exception condition.
-
-Per Task Variables
-------------------
-.. index:: per task variables
-
-Per task variables are deprecated, see the warning below.
-
-Per task variables are used to support global variables whose value
-may be unique to a task. After indicating that a variable should be
-treated as private (i.e. per-task) the task can access and modify the
-variable, but the modifications will not appear to other tasks, and
-other tasks’ modifications to that variable will not affect the value
-seen by the task. This is accomplished by saving and restoring the
-variable’s value each time a task switch occurs to or from the calling task.
-
-The value seen by other tasks, including those which have not added the
-variable to their set and are thus accessing the variable as a common
-location shared among tasks, cannot be affected by a task once it has
-added a variable to its local set. Changes made to the variable by
-other tasks will not affect the value seen by a task which has added the
-variable to its private set.
-
-This feature can be used when a routine is to be spawned repeatedly as
-several independent tasks. Although each task will have its own stack,
-and thus separate stack variables, they will all share the same static and
-global variables. To make a variable not shareable (i.e. a "global" variable
-that is specific to a single task), the tasks can call``rtems_task_variable_add`` to make a separate copy of the variable
-for each task, but all at the same physical address.
-
-Task variables increase the context switch time to and from the
-tasks that own them so it is desirable to minimize the number of
-task variables. One efficient method is to have a single task
-variable that is a pointer to a dynamically allocated structure
-containing the task’s private "global" data.
-
-A critical point with per-task variables is that each task must separately
-request that the same global variable is per-task private.
-
-*WARNING*: Per-Task variables are inherently broken on SMP systems. They
-only work correctly when there is one task executing in the system and
-that task is the logical owner of the value in the per-task variable’s
-location. There is no way for a single memory image to contain the
-correct value for each task executing on each core. Consequently,
-per-task variables are disabled in SMP configurations of RTEMS.
-Instead the application developer should
-consider the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys
-are not enabled in all RTEMS configurations.
-
-Building a Task Attribute Set
------------------------------
-.. index:: task attributes, building
-
-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:
-
-- ``RTEMS_NO_FLOATING_POINT`` - does not use coprocessor (default)
-
-- ``RTEMS_FLOATING_POINT`` - uses numeric coprocessor
-
-- ``RTEMS_LOCAL`` - local task (default)
-
-- ``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 ``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 ``RTEMS_FLOATING_POINT`` or``RTEMS_LOCAL | RTEMS_FLOATING_POINT``.
-The attribute_set parameter can be set to``RTEMS_FLOATING_POINT`` because ``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``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``.
-
-Building a Mode and Mask
-------------------------
-.. index:: task mode, building
-
-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:
-
-- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption
-
-- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption
-
-- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing
-
-- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing
-
-- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing
-
-- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing
-
-- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts
-
-- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
-
-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 ``RTEMS_DEFAULT_MODES`` and the
-mask ``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``RTEMS_INTERRUPT_LEVEL(3) |
-RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and
-interrupt level, while the mask parameter should be set to``RTEMS_INTERRUPT_MASK |
-RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task’s
-interrupt level and preemption mode are being altered.
-
-Operations
-==========
-
-Creating Tasks
---------------
-
-The ``rtems_task_create``
-directive creates a task by allocating a task
-control block, assigning the task a user-specified name,
-allocating it a stack and floating point context area, setting a
-user-specified initial priority, setting a user-specified
-initial mode, and assigning it a task ID. Newly created tasks
-are initially placed in the dormant state. All RTEMS tasks
-execute in the most privileged mode of the processor.
-
-Obtaining Task IDs
-------------------
-
-When a task is created, RTEMS generates a unique task ID and
-assigns it to the created task until it is deleted. The task ID
-may be obtained by either of two methods. First, as the result
-of an invocation of the ``rtems_task_create``
-directive, the task ID is
-stored in a user provided location. Second, the task ID may be
-obtained later using the ``rtems_task_ident``
-directive. The task ID is
-used by other directives to manipulate this task.
-
-Starting and Restarting Tasks
------------------------------
-
-The ``rtems_task_start``
-directive is used to place a dormant task in the
-ready state. This enables the task to compete, based on its
-current priority, for the processor and other system resources.
-Any actions, such as suspension or change of priority, performed
-on a task prior to starting it are nullified when the task is
-started.
-
-With the ``rtems_task_start``
-directive the user specifies the task’s
-starting address and argument. The argument is used to
-communicate some startup information to the task. As part of
-this directive, RTEMS initializes the task’s stack based upon
-the task’s initial execution mode and start address. The
-starting argument is passed to the task in accordance with the
-target processor’s calling convention.
-
-The ``rtems_task_restart``
-directive restarts a task at its initial
-starting address with its original priority and execution mode,
-but with a possibly different argument. The new argument may be
-used to distinguish between the original invocation of the task
-and subsequent invocations. The task’s stack and control block
-are modified to reflect their original creation values.
-Although references to resources that have been requested are
-cleared, resources allocated by the task are NOT automatically
-returned to RTEMS. A task cannot be restarted unless it has
-previously been started (i.e. dormant tasks cannot be
-restarted). All restarted tasks are placed in the ready state.
-
-Suspending and Resuming Tasks
------------------------------
-
-The ``rtems_task_suspend``
-directive is used to place either the caller or
-another task into a suspended state. The task remains suspended
-until a ``rtems_task_resume``
-directive is issued. This implies that a
-task may be suspended as well as blocked waiting either to
-acquire a resource or for the expiration of a timer.
-
-The ``rtems_task_resume``
-directive is used to remove another task from
-the suspended state. If the task is not also blocked, resuming
-it will place it in the ready state, allowing it to once again
-compete for the processor and resources. If the task was
-blocked as well as suspended, this directive clears the
-suspension and leaves the task in the blocked state.
-
-Suspending a task which is already suspended or resuming a
-task which is not suspended is considered an error.
-The ``rtems_task_is_suspended`` can be used to
-determine if a task is currently suspended.
-
-Delaying the Currently Executing Task
--------------------------------------
-
-The ``rtems_task_wake_after`` directive creates a sleep timer
-which allows a task to go to sleep for a specified interval. The task is
-blocked until the delay interval has elapsed, at which time the task is
-unblocked. A task calling the ``rtems_task_wake_after``
-directive with a delay
-interval of ``RTEMS_YIELD_PROCESSOR`` ticks will yield the
-processor to any other ready task of equal or greater priority and remain
-ready to execute.
-
-The ``rtems_task_wake_when``
-directive creates a sleep timer which allows
-a task to go to sleep until a specified date and time. The
-calling task is blocked until the specified date and time has
-occurred, at which time the task is unblocked.
-
-Changing Task Priority
-----------------------
-
-The ``rtems_task_set_priority``
-directive is used to obtain or change the
-current priority of either the calling task or another task. If
-the new priority requested is``RTEMS_CURRENT_PRIORITY`` or the task’s
-actual priority, then the current priority will be returned and
-the task’s priority will remain unchanged. If the task’s
-priority is altered, then the task will be scheduled according
-to its new priority.
-
-The ``rtems_task_restart``
-directive resets the priority of a task to its
-original value.
-
-Changing Task Mode
-------------------
-
-The ``rtems_task_mode``
-directive is used to obtain or change the current
-execution mode of the calling task. A task’s execution mode is
-used to enable preemption, timeslicing, ASR processing, and to
-set the task’s interrupt level.
-
-The ``rtems_task_restart``
-directive resets the mode of a task to its
-original value.
-
-Task Deletion
--------------
-
-RTEMS provides the ``rtems_task_delete``
-directive to allow a task to
-delete itself or any other task. This directive removes all
-RTEMS references to the task, frees the task’s control block,
-removes it from resource wait queues, and deallocates its stack
-as well as the optional floating point context. The task’s name
-and ID become inactive at this time, and any subsequent
-references to either of them is invalid. In fact, RTEMS may
-reuse the task ID for another task which is created later in the
-application.
-
-Unexpired delay timers (i.e. those used by``rtems_task_wake_after`` and``rtems_task_wake_when``) and
-timeout timers associated with the task are
-automatically deleted, however, other resources dynamically
-allocated by the task are NOT automatically returned to RTEMS.
-Therefore, before a task is deleted, all of its dynamically
-allocated resources should be deallocated by the user. This may
-be accomplished by instructing the task to delete itself rather
-than directly deleting the task. Other tasks may instruct a
-task to delete itself by sending a "delete self" message, event,
-or signal, or by restarting the task with special arguments
-which instruct the task to delete itself.
-
-Transition Advice for Obsolete Directives
------------------------------------------
-
-Notepads
-~~~~~~~~.. index:: rtems_task_get_note
-.. index:: rtems_task_set_note
-
-Task notepads and the associated directives``rtems_task_get_note`` and``rtems_task_set_note`` were removed after the 4.11 Release
-Series. These were never thread-safe to access and subject to conflicting
-use of the notepad index by libraries which were designed independently.
-
-It is recommended that applications be modified to use services
-which are thread safe and not subject to issues with multiple applications
-conflicting over the key (e.g. notepad index) selection. For most
-applications, POSIX Keys should be used. These are available in all RTEMS
-build configurations. It is also possible that Thread Local Storage is
-an option for some use cases.
-
-Directives
-==========
-
-This section details the task manager’s directives. A
-subsection is dedicated to each of this manager’s directives and
-describes the calling sequence, related constants, usage, and
-status codes.
-
-TASK_CREATE - Create a task
----------------------------
-.. index:: create a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_create
-
-.. code:: c
-
- rtems_status_code rtems_task_create(
- rtems_name name,
- rtems_task_priority initial_priority,
- size_t stack_size,
- rtems_mode initial_modes,
- rtems_attribute attribute_set,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task created successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - invalid task name
-``RTEMS_INVALID_PRIORITY`` - invalid task priority
-``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured
-``RTEMS_TOO_MANY`` - too many tasks created
-``RTEMS_UNSATISFIED`` - not enough memory for stack/FP context
-``RTEMS_TOO_MANY`` - too many global objects
-
-**DESCRIPTION:**
-
-This directive creates a task which resides on the local node.
-It allocates and initializes a TCB, a stack, and an optional
-floating point context area. The mode parameter contains values
-which sets the task’s initial execution mode. The``RTEMS_FLOATING_POINT`` attribute should be
-specified if the created task
-is to use a numeric coprocessor. For performance reasons, it is
-recommended that tasks not using the numeric coprocessor should
-specify the ``RTEMS_NO_FLOATING_POINT`` attribute.
-If the ``RTEMS_GLOBAL``
-attribute is specified, the task can be accessed from remote
-nodes. The task id, returned in id, is used in other task
-related directives to access the task. When created, a task is
-placed in the dormant state and can only be made ready to
-execute using the directive ``rtems_task_start``.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-Valid task priorities range from a high of 1 to a low of 255.
-
-If the requested stack size is less than the configured
-minimum stack size, then RTEMS will use the configured
-minimum as the stack size for this task. In addition
-to being able to specify the task stack size as a integer,
-there are two constants which may be specified:
-
-- ``RTEMS_MINIMUM_STACK_SIZE``
- is the minimum stack size *RECOMMENDED* for use on this processor.
- This value is selected by the RTEMS developers conservatively to
- minimize the risk of blown stacks for most user applications.
- Using this constant when specifying the task stack size, indicates
- that the stack size will be at least``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the
- user configured minimum stack size is larger than the recommended
- minimum, then it will be used.
-
-- ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE``
- indicates that this task is to be created with a stack size
- of the minimum stack size that was configured by the application.
- If not explicitly configured by the application, the default
- configured minimum stack size is the processor dependent value``RTEMS_MINIMUM_STACK_SIZE``. Since this uses
- the configured minimum stack size value, you may get a stack
- size that is smaller or larger than the recommended minimum. This
- can be used to provide large stacks for all tasks on complex
- applications or small stacks on applications that are trying
- to conserve memory.
-
-Application developers should consider the stack usage of the
-device drivers when calculating the stack size required for
-tasks which utilize the driver.
-
-The following task attribute constants are defined by RTEMS:
-
-- ``RTEMS_NO_FLOATING_POINT`` - does not use coprocessor (default)
-
-- ``RTEMS_FLOATING_POINT`` - uses numeric coprocessor
-
-- ``RTEMS_LOCAL`` - local task (default)
-
-- ``RTEMS_GLOBAL`` - global task
-
-The following task mode constants are defined by RTEMS:
-
-- ``RTEMS_PREEMPT`` - enable preemption (default)
-
-- ``RTEMS_NO_PREEMPT`` - disable preemption
-
-- ``RTEMS_NO_TIMESLICE`` - disable timeslicing (default)
-
-- ``RTEMS_TIMESLICE`` - enable timeslicing
-
-- ``RTEMS_ASR`` - enable ASR processing (default)
-
-- ``RTEMS_NO_ASR`` - disable ASR processing
-
-- ``RTEMS_INTERRUPT_LEVEL(0)`` - enable all interrupts (default)
-
-- ``RTEMS_INTERRUPT_LEVEL(n)`` - execute at interrupt level n
-
-The interrupt level portion of the task execution mode
-supports a maximum of 256 interrupt levels. These levels are
-mapped onto the interrupt levels actually supported by the
-target processor in a processor dependent fashion.
-
-Tasks should not be made global unless remote tasks must
-interact with them. This avoids the system overhead incurred by
-the creation of a global task. When a global task is created,
-the task’s name and id must be transmitted to every node in the
-system for insertion in the local copy of the global object
-table.
-
-The total number of global objects, including tasks, is limited
-by the maximum_global_objects field in the Configuration Table.
-
-TASK_IDENT - Get ID of a task
------------------------------
-.. index:: get ID of a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_ident
-
-.. code:: c
-
- rtems_status_code rtems_task_ident(
- rtems_name name,
- uint32_t node,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task identified successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - invalid task name
-``RTEMS_INVALID_NODE`` - invalid node id
-
-**DESCRIPTION:**
-
-This directive obtains the task id associated with the task name
-specified in name. A task may obtain its own id by specifying``RTEMS_SELF`` or its own task name in name. If the task name is not
-unique, then the task id returned will match one of the tasks
-with that name. However, this task id is not guaranteed to
-correspond to the desired task. The task id, returned in id, is
-used in other task related directives to access the task.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the
-local node being searched first. All other nodes are searched
-with the lowest numbered node searched first.
-
-If node is a valid node number which does not represent the
-local node, then only the tasks exported by the designated node
-are searched.
-
-This directive does not generate activity on remote nodes. It
-accesses only the local copy of the global object table.
-
-TASK_SELF - Obtain ID of caller
--------------------------------
-.. index:: obtain ID of caller
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_self
-
-.. code:: c
-
- rtems_id rtems_task_self(void);
-
-**DIRECTIVE STATUS CODES:**
-
-Returns the object Id of the calling task.
-
-**DESCRIPTION:**
-
-This directive returns the Id of the calling task.
-
-**NOTES:**
-
-If called from an interrupt service routine, this directive
-will return the Id of the interrupted task.
-
-TASK_START - Start a task
--------------------------
-.. index:: starting a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_start
-
-.. code:: c
-
- rtems_status_code rtems_task_start(
- rtems_id id,
- rtems_task_entry entry_point,
- rtems_task_argument argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - ask started successfully
-``RTEMS_INVALID_ADDRESS`` - invalid task entry point
-``RTEMS_INVALID_ID`` - invalid task id
-``RTEMS_INCORRECT_STATE`` - task not in the dormant state
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot start remote task
-
-**DESCRIPTION:**
-
-This directive readies the task, specified by ``id``, for execution
-based on the priority and execution mode specified when the task
-was created. The starting address of the task is given in``entry_point``. The task’s starting argument is contained in
-argument. This argument can be a single value or used as an index into an
-array of parameter blocks. The type of this numeric argument is an unsigned
-integer type with the property that any valid pointer to void can be converted
-to this type and then converted back to a pointer to void. The result will
-compare equal to the original pointer.
-
-**NOTES:**
-
-The calling task will be preempted if its preemption mode is
-enabled and the task being started has a higher priority.
-
-Any actions performed on a dormant task such as suspension or
-change of priority are nullified when the task is initiated via
-the ``rtems_task_start`` directive.
-
-TASK_RESTART - Restart a task
------------------------------
-.. index:: restarting a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_restart
-
-.. code:: c
-
- rtems_status_code rtems_task_restart(
- rtems_id id,
- rtems_task_argument argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task restarted successfully
-``RTEMS_INVALID_ID`` - task id invalid
-``RTEMS_INCORRECT_STATE`` - task never started
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot restart remote task
-
-**DESCRIPTION:**
-
-This directive resets the task specified by id to begin
-execution at its original starting address. The task’s priority
-and execution mode are set to the original creation values. If
-the task is currently blocked, RTEMS automatically makes the
-task ready. A task can be restarted from any state, except the
-dormant state.
-
-The task’s starting argument is contained in argument. This argument can be a
-single value or an index into an array of parameter blocks. The type of this
-numeric argument is an unsigned integer type with the property that any valid
-pointer to void can be converted to this type and then converted back to a
-pointer to void. The result will compare equal to the original pointer. This
-new argument may be used to distinguish
-between the initial ``rtems_task_start``
-of the task and any ensuing calls
-to ``rtems_task_restart``
-of the task. This can be beneficial in deleting
-a task. Instead of deleting a task using
-the ``rtems_task_delete``
-directive, a task can delete another task by restarting that
-task, and allowing that task to release resources back to RTEMS
-and then delete itself.
-
-**NOTES:**
-
-If id is ``RTEMS_SELF``, the calling task will be restarted and will not
-return from this directive.
-
-The calling task will be preempted if its preemption mode is
-enabled and the task being restarted has a higher priority.
-
-The task must reside on the local node, even if the task was
-created with the ``RTEMS_GLOBAL`` option.
-
-TASK_DELETE - Delete a task
----------------------------
-.. index:: deleting a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_delete
-
-.. code:: c
-
- rtems_status_code rtems_task_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task deleted successfully
-``RTEMS_INVALID_ID`` - task id invalid
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot restart remote task
-
-**DESCRIPTION:**
-
-This directive deletes a task, either the calling task or
-another task, as specified by id. RTEMS stops the execution of
-the task and reclaims the stack memory, any allocated delay or
-timeout timers, the TCB, and, if the task is ``RTEMS_FLOATING_POINT``, its
-floating point context area. RTEMS does not reclaim the
-following resources: region segments, partition buffers,
-semaphores, timers, or rate monotonic periods.
-
-**NOTES:**
-
-A task is responsible for releasing its resources back to RTEMS
-before deletion. To insure proper deallocation of resources, a
-task should not be deleted unless it is unable to execute or
-does not hold any RTEMS resources. If a task holds RTEMS
-resources, the task should be allowed to deallocate its
-resources before deletion. A task can be directed to release
-its resources and delete itself by restarting it with a special
-argument or by sending it a message, an event, or a signal.
-
-Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select
-another task to execute.
-
-When a global task is deleted, the task id must be transmitted
-to every node in the system for deletion from the local copy of
-the global object table.
-
-The task must reside on the local node, even if the task was
-created with the ``RTEMS_GLOBAL`` option.
-
-TASK_SUSPEND - Suspend a task
------------------------------
-.. index:: suspending a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_suspend
-
-.. code:: c
-
- rtems_status_code rtems_task_suspend(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task suspended successfully
-``RTEMS_INVALID_ID`` - task id invalid
-``RTEMS_ALREADY_SUSPENDED`` - task already suspended
-
-**DESCRIPTION:**
-
-This directive suspends the task specified by id from further
-execution by placing it in the suspended state. This state is
-additive to any other blocked state that the task may already be
-in. The task will not execute again until another task issues
-the ``rtems_task_resume``
-directive for this task and any blocked state
-has been removed.
-
-**NOTES:**
-
-The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id.
-In this case, the task will be suspended and a successful
-return code will be returned when the task is resumed.
-
-Suspending a global task which does not reside on the local node
-will generate a request to the remote node to suspend the
-specified task.
-
-If the task specified by id is already suspended, then the``RTEMS_ALREADY_SUSPENDED`` status code is returned.
-
-TASK_RESUME - Resume a task
----------------------------
-.. index:: resuming a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_resume
-
-.. code:: c
-
- rtems_status_code rtems_task_resume(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task resumed successfully
-``RTEMS_INVALID_ID`` - task id invalid
-``RTEMS_INCORRECT_STATE`` - task not suspended
-
-**DESCRIPTION:**
-
-This directive removes the task specified by id from the
-suspended state. If the task is in the ready state after the
-suspension is removed, then it will be scheduled to run. If the
-task is still in a blocked state after the suspension is
-removed, then it will remain in that blocked state.
-
-**NOTES:**
-
-The running task may be preempted if its preemption mode is
-enabled and the local task being resumed has a higher priority.
-
-Resuming a global task which does not reside on the local node
-will generate a request to the remote node to resume the
-specified task.
-
-If the task specified by id is not suspended, then the``RTEMS_INCORRECT_STATE`` status code is returned.
-
-TASK_IS_SUSPENDED - Determine if a task is Suspended
-----------------------------------------------------
-.. index:: is task suspended
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_is_suspended
-
-.. code:: c
-
- rtems_status_code rtems_task_is_suspended(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task is NOT suspended
-``RTEMS_ALREADY_SUSPENDED`` - task is currently suspended
-``RTEMS_INVALID_ID`` - task id invalid
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
-
-**DESCRIPTION:**
-
-This directive returns a status code indicating whether or
-not the specified task is currently suspended.
-
-**NOTES:**
-
-This operation is not currently supported on remote tasks.
-
-TASK_SET_PRIORITY - Set task priority
--------------------------------------
-.. index:: rtems_task_set_priority
-.. index:: current task priority
-.. index:: set task priority
-.. index:: get task priority
-.. index:: obtain task priority
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_task_set_priority(
- rtems_id id,
- rtems_task_priority new_priority,
- rtems_task_priority \*old_priority
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task priority set successfully
-``RTEMS_INVALID_ID`` - invalid task id
-``RTEMS_INVALID_ADDRESS`` - invalid return argument pointer
-``RTEMS_INVALID_PRIORITY`` - invalid task priority
-
-**DESCRIPTION:**
-
-This directive manipulates the priority of the task specified by
-id. An id of ``RTEMS_SELF`` is used to indicate
-the calling task. When new_priority is not equal to``RTEMS_CURRENT_PRIORITY``, the specified
-task’s previous priority is returned in old_priority. When
-new_priority is ``RTEMS_CURRENT_PRIORITY``,
-the specified task’s current
-priority is returned in old_priority. Valid priorities range
-from a high of 1 to a low of 255.
-
-**NOTES:**
-
-The calling task may be preempted if its preemption mode is
-enabled and it lowers its own priority or raises another task’s
-priority.
-
-In case the new priority equals the current priority of the task, then nothing
-happens.
-
-Setting the priority of a global task which does not reside on
-the local node will generate a request to the remote node to
-change the priority of the specified task.
-
-If the task specified by id is currently holding any binary
-semaphores which use the priority inheritance algorithm, then
-the task’s priority cannot be lowered immediately. If the
-task’s priority were lowered immediately, then priority
-inversion results. The requested lowering of the task’s
-priority will occur when the task has released all priority
-inheritance binary semaphores. The task’s priority can be
-increased regardless of the task’s use of priority inheritance
-binary semaphores.
-
-TASK_MODE - Change the current task mode
-----------------------------------------
-.. index:: current task mode
-.. index:: set task mode
-.. index:: get task mode
-.. index:: set task preemption mode
-.. index:: get task preemption mode
-.. index:: obtain task mode
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_mode
-
-.. code:: c
-
- rtems_status_code rtems_task_mode(
- rtems_mode mode_set,
- rtems_mode mask,
- rtems_mode \*previous_mode_set
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - task mode set successfully
-``RTEMS_INVALID_ADDRESS`` - ``previous_mode_set`` is NULL
-
-**DESCRIPTION:**
-
-This directive manipulates the execution mode of the calling
-task. A task’s execution mode enables and disables preemption,
-timeslicing, asynchronous signal processing, as well as
-specifying the current interrupt level. To modify an execution
-mode, the mode class(es) to be changed must be specified in the
-mask parameter and the desired mode(s) must be specified in the
-mode parameter.
-
-**NOTES:**
-
-The calling task will be preempted if it enables preemption and
-a higher priority task is ready to run.
-
-Enabling timeslicing has no effect if preemption is disabled. For
-a task to be timesliced, that task must have both preemption and
-timeslicing enabled.
-
-A task can obtain its current execution mode, without modifying
-it, by calling this directive with a mask value of``RTEMS_CURRENT_MODE``.
-
-To temporarily disable the processing of a valid ASR, a task
-should call this directive with the ``RTEMS_NO_ASR``
-indicator specified in mode.
-
-The set of task mode constants and each mode’s corresponding
-mask constant is provided in the following table:
-
-- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption
-
-- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption
-
-- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing
-
-- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing
-
-- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing
-
-- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing
-
-- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts
-
-- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
-
-TASK_WAKE_AFTER - Wake up after interval
-----------------------------------------
-.. index:: delay a task for an interval
-.. index:: wake up after an interval
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_wake_after
-
-.. code:: c
-
- rtems_status_code rtems_task_wake_after(
- rtems_interval ticks
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - always successful
-
-**DESCRIPTION:**
-
-This directive blocks the calling task for the specified number
-of system clock ticks. When the requested interval has elapsed,
-the task is made ready. The ``rtems_clock_tick``
-directive automatically updates the delay period.
-
-**NOTES:**
-
-Setting the system date and time with the``rtems_clock_set`` directive
-has no effect on a ``rtems_task_wake_after`` blocked task.
-
-A task may give up the processor and remain in the ready state
-by specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks.
-
-The maximum timer interval that can be specified is the maximum
-value which can be represented by the uint32_t type.
-
-A clock tick is required to support the functionality of this directive.
-
-TASK_WAKE_WHEN - Wake up when specified
----------------------------------------
-.. index:: delay a task until a wall time
-.. index:: wake up at a wall time
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_wake_when
-
-.. code:: c
-
- rtems_status_code rtems_task_wake_when(
- rtems_time_of_day \*time_buffer
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - awakened at date/time successfully
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
-``RTEMS_INVALID_TIME_OF_DAY`` - invalid time buffer
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-
-**DESCRIPTION:**
-
-This directive blocks a task until the date and time specified
-in time_buffer. At the requested date and time, the calling
-task will be unblocked and made ready to execute.
-
-**NOTES:**
-
-The ticks portion of time_buffer structure is ignored. The
-timing granularity of this directive is a second.
-
-A clock tick is required to support the functionality of this directive.
-
-ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
----------------------------------------------
-.. index:: iterate over all threads
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_iterate_over_all_threads
-
-.. code:: c
-
- typedef void (\*rtems_per_thread_routine)(
- Thread_Control \*the_thread
- );
- void rtems_iterate_over_all_threads(
- rtems_per_thread_routine routine
- );
-
-**DIRECTIVE STATUS CODES: NONE**
-
-**DESCRIPTION:**
-
-This directive iterates over all of the existant threads in the
-system and invokes ``routine`` on each of them. The user should
-be careful in accessing the contents of ``the_thread``.
-
-This routine is intended for use in diagnostic utilities and is
-not intented for routine use in an operational system.
-
-**NOTES:**
-
-There is NO protection while this routine is called. Thus it is
-possible that ``the_thread`` could be deleted while this is operating.
-By not having protection, the user is free to invoke support routines
-from the C Library which require semaphores for data structures.
-
-TASK_VARIABLE_ADD - Associate per task variable
------------------------------------------------
-.. index:: per-task variable
-.. index:: task private variable
-.. index:: task private data
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_variable_add
-
-.. code:: c
-
- rtems_status_code rtems_task_variable_add(
- rtems_id tid,
- void \**task_variable,
- void (\*dtor)(void \*)
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - per task variable added successfully
-``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is NULL
-``RTEMS_INVALID_ID`` - invalid task id
-``RTEMS_NO_MEMORY`` - invalid task id
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
-
-**DESCRIPTION:**
-
-This directive adds the memory location specified by the
-ptr argument to the context of the given task. The variable will
-then be private to the task. The task can access and modify the
-variable, but the modifications will not appear to other tasks, and
-other tasks’ modifications to that variable will not affect the value
-seen by the task. This is accomplished by saving and restoring the
-variable’s value each time a task switch occurs to or from the calling task.
-If the dtor argument is non-NULL it specifies the address of a ‘destructor’
-function which will be called when the task is deleted. The argument
-passed to the destructor function is the task’s value of the variable.
-
-**NOTES:**
-
-This directive is deprecated and task variables will be removed.
-
-Task variables increase the context switch time to and from the
-tasks that own them so it is desirable to minimize the number of
-task variables. One efficient method
-is to have a single task variable that is a pointer to a dynamically
-allocated structure containing the task’s private ‘global’ data.
-In this case the destructor function could be ‘free’.
-
-Per-task variables are disabled in SMP configurations and this service
-is not available.
-
-TASK_VARIABLE_GET - Obtain value of a per task variable
--------------------------------------------------------
-.. index:: get per-task variable
-.. index:: obtain per-task variable
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_variable_get
-
-.. code:: c
-
- rtems_status_code rtems_task_variable_get(
- rtems_id tid,
- void \**task_variable,
- void \**task_variable_value
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - per task variable obtained successfully
-``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``task_variable_value`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is not found
-``RTEMS_NO_MEMORY`` - invalid task id
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
-
-**DESCRIPTION:**
-
-This directive looks up the private value of a task variable for a
-specified task and stores that value in the location pointed to by
-the result argument. The specified task is usually not the calling
-task, which can get its private value by directly accessing the variable.
-
-**NOTES:**
-
-This directive is deprecated and task variables will be removed.
-
-If you change memory which ``task_variable_value`` points to,
-remember to declare that memory as volatile, so that the compiler
-will optimize it correctly. In this case both the pointer``task_variable_value`` and data referenced by ``task_variable_value``
-should be considered volatile.
-
-Per-task variables are disabled in SMP configurations and this service
-is not available.
-
-TASK_VARIABLE_DELETE - Remove per task variable
------------------------------------------------
-.. index:: per-task variable
-.. index:: task private variable
-.. index:: task private data
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_task_variable_delete
-
-.. code:: c
-
- rtems_status_code rtems_task_variable_delete(
- rtems_id id,
- void \**task_variable
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - per task variable deleted successfully
-``RTEMS_INVALID_ID`` - invalid task id
-``RTEMS_NO_MEMORY`` - invalid task id
-``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is NULL
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks
-
-**DESCRIPTION:**
-
-This directive removes the given location from a task’s context.
-
-**NOTES:**
-
-This directive is deprecated and task variables will be removed.
-
-Per-task variables are disabled in SMP configurations and this service
-is not available.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Interrupt Manager
-#################
-
-Introduction
-============
-
-Any real-time executive must provide a mechanism for
-quick response to externally generated interrupts to satisfy the
-critical time constraints of the application. The interrupt
-manager provides this mechanism for RTEMS. This manager permits
-quick interrupt response times by providing the critical ability
-to alter task execution which allows a task to be preempted upon
-exit from an ISR. The interrupt manager includes the following
-directive:
-
-- ``rtems_interrupt_catch`` - Establish an ISR
-
-- ``rtems_interrupt_disable`` - Disable Interrupts
-
-- ``rtems_interrupt_enable`` - Enable Interrupts
-
-- ``rtems_interrupt_flash`` - Flash Interrupt
-
-- ``rtems_interrupt_local_disable`` - Disable Interrupts on Current Processor
-
-- ``rtems_interrupt_local_enable`` - Enable Interrupts on Current Processor
-
-- ``rtems_interrupt_lock_initialize`` - Initialize an ISR Lock
-
-- ``rtems_interrupt_lock_acquire`` - Acquire an ISR Lock
-
-- ``rtems_interrupt_lock_release`` - Release an ISR Lock
-
-- ``rtems_interrupt_lock_acquire_isr`` - Acquire an ISR Lock from ISR
-
-- ``rtems_interrupt_lock_release_isr`` - Release an ISR Lock from ISR
-
-- ``rtems_interrupt_is_in_progress`` - Is an ISR in Progress
-
-Background
-==========
-
-Processing an Interrupt
------------------------
-.. index:: interrupt processing
-
-The interrupt manager allows the application to
-connect a function to a hardware interrupt vector. When an
-interrupt occurs, the processor will automatically vector to
-RTEMS. RTEMS saves and restores all registers which are not
-preserved by the normal C calling convention
-for the target
-processor and invokes the user’s ISR. The user’s ISR is
-responsible for processing the interrupt, clearing the interrupt
-if necessary, and device specific manipulation... index:: rtems_vector_number
-
-The ``rtems_interrupt_catch``
-directive connects a procedure to
-an interrupt vector. The vector number is managed using
-the ``rtems_vector_number`` data type.
-
-The interrupt service routine is assumed
-to abide by these conventions and have a prototype similar to
-the following:.. index:: rtems_isr
-
-.. code:: c
-
- rtems_isr user_isr(
- rtems_vector_number vector
- );
-
-The vector number argument is provided by RTEMS to
-allow the application to identify the interrupt source. This
-could be used to allow a single routine to service interrupts
-from multiple instances of the same device. For example, a
-single routine could service interrupts from multiple serial
-ports and use the vector number to identify which port requires
-servicing.
-
-To minimize the masking of lower or equal priority
-level interrupts, the ISR should perform the minimum actions
-required to service the interrupt. Other non-essential actions
-should be handled by application tasks. Once the user’s ISR has
-completed, it returns control to the RTEMS interrupt manager
-which will perform task dispatching and restore the registers
-saved before the ISR was invoked.
-
-The RTEMS interrupt manager guarantees that proper
-task scheduling and dispatching are performed at the conclusion
-of an ISR. A system call made by the ISR may have readied a
-task of higher priority than the interrupted task. Therefore,
-when the ISR completes, the postponed dispatch processing must
-be performed. No dispatch processing is performed as part of
-directives which have been invoked by an ISR.
-
-Applications must adhere to the following rule if
-proper task scheduling and dispatching is to be performed:
-
-- ** *The interrupt manager must be used for all ISRs which
- may be interrupted by the highest priority ISR which invokes an
- RTEMS directive.*
-
-Consider a processor which allows a numerically low
-interrupt level to interrupt a numerically greater interrupt
-level. In this example, if an RTEMS directive is used in a
-level 4 ISR, then all ISRs which execute at levels 0 through 4
-must use the interrupt manager.
-
-Interrupts are nested whenever an interrupt occurs
-during the execution of another ISR. RTEMS supports efficient
-interrupt nesting by allowing the nested ISRs to terminate
-without performing any dispatch processing. Only when the
-outermost ISR terminates will the postponed dispatching occur.
-
-RTEMS Interrupt Levels
-----------------------
-.. index:: interrupt levels
-
-Many processors support multiple interrupt levels or
-priorities. The exact number of interrupt levels is processor
-dependent. RTEMS internally supports 256 interrupt levels which
-are mapped to the processor’s interrupt levels. For specific
-information on the mapping between RTEMS and the target
-processor’s interrupt levels, refer to the Interrupt Processing
-chapter of the Applications Supplement document for a specific
-target processor.
-
-Disabling of Interrupts by RTEMS
---------------------------------
-.. index:: disabling interrupts
-
-During the execution of directive calls, critical
-sections of code may be executed. When these sections are
-encountered, RTEMS disables all maskable interrupts before the
-execution of the section and restores them to the previous level
-upon completion of the section. RTEMS has been optimized to
-ensure that interrupts are disabled for a minimum length of
-time. The maximum length of time interrupts are disabled by
-RTEMS is processor dependent and is detailed in the Timing
-Specification chapter of the Applications Supplement document
-for a specific target processor.
-
-Non-maskable interrupts (NMI) cannot be disabled, and
-ISRs which execute at this level MUST NEVER issue RTEMS system
-calls. If a directive is invoked, unpredictable results may
-occur due to the inability of RTEMS to protect its critical
-sections. However, ISRs that make no system calls may safely
-execute as non-maskable interrupts.
-
-Operations
-==========
-
-Establishing an ISR
--------------------
-
-The ``rtems_interrupt_catch``
-directive establishes an ISR for
-the system. The address of the ISR and its associated CPU
-vector number are specified to this directive. This directive
-installs the RTEMS interrupt wrapper in the processor’s
-Interrupt Vector Table and the address of the user’s ISR in the
-RTEMS’ Vector Table. This directive returns the previous
-contents of the specified vector in the RTEMS’ Vector Table.
-
-Directives Allowed from an ISR
-------------------------------
-
-Using the interrupt manager ensures that RTEMS knows
-when a directive is being called from an ISR. The ISR may then
-use system calls to synchronize itself with an application task.
-The synchronization may involve messages, events or signals
-being passed by the ISR to the desired task. Directives invoked
-by an ISR must operate only on objects which reside on the local
-node. The following is a list of RTEMS system calls that may be
-made from an ISR:
-
-- Task Management
- Although it is acceptable to operate on the RTEMS_SELF task (e.g.
- the currently executing task), while in an ISR, this will refer
- to the interrupted task. Most of the time, it is an application
- implementation error to use RTEMS_SELF from an ISR.
- - rtems_task_suspend
- - rtems_task_resume
-
-- Interrupt Management
- - rtems_interrupt_enable
- - rtems_interrupt_disable
- - rtems_interrupt_flash
- - rtems_interrupt_lock_acquire
- - rtems_interrupt_lock_release
- - rtems_interrupt_lock_acquire_isr
- - rtems_interrupt_lock_release_isr
- - rtems_interrupt_is_in_progress
- - rtems_interrupt_catch
-
-- Clock Management
- - rtems_clock_set
- - rtems_clock_get
- - rtems_clock_get_tod
- - rtems_clock_get_tod_timeval
- - rtems_clock_get_seconds_since_epoch
- - rtems_clock_get_ticks_per_second
- - rtems_clock_get_ticks_since_boot
- - rtems_clock_get_uptime
- - rtems_clock_set_nanoseconds_extension
- - rtems_clock_tick
-
-- Timer Management
- - rtems_timer_cancel
- - rtems_timer_reset
- - rtems_timer_fire_after
- - rtems_timer_fire_when
- - rtems_timer_server_fire_after
- - rtems_timer_server_fire_when
-
-- Event Management
- - rtems_event_send
- - rtems_event_system_send
- - rtems_event_transient_send
-
-- Semaphore Management
- - rtems_semaphore_release
-
-- Message Management
- - rtems_message_queue_send
- - rtems_message_queue_urgent
-
-- Signal Management
- - rtems_signal_send
-
-- Dual-Ported Memory Management
- - rtems_port_external_to_internal
- - rtems_port_internal_to_external
-
-- IO Management
- The following services are safe to call from an ISR if and only if
- the device driver service invoked is also safe. The IO Manager itself
- is safe but the invoked driver entry point may or may not be.
- - rtems_io_initialize
- - rtems_io_open
- - rtems_io_close
- - rtems_io_read
- - rtems_io_write
- - rtems_io_control
-
-- Fatal Error Management
- - rtems_fatal
- - rtems_fatal_error_occurred
-
-- Multiprocessing
- - rtems_multiprocessing_announce
-
-Directives
-==========
-
-This section details the interrupt manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-INTERRUPT_CATCH - Establish an ISR
-----------------------------------
-.. index:: establish an ISR
-.. index:: install an ISR
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_catch
-
-.. code:: c
-
- rtems_status_code rtems_interrupt_catch(
- rtems_isr_entry new_isr_handler,
- rtems_vector_number vector,
- rtems_isr_entry \*old_isr_handler
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - ISR established successfully
-``RTEMS_INVALID_NUMBER`` - illegal vector number
-``RTEMS_INVALID_ADDRESS`` - illegal ISR entry point or invalid ``old_isr_handler``
-
-**DESCRIPTION:**
-
-This directive establishes an interrupt service
-routine (ISR) for the specified interrupt vector number. The``new_isr_handler`` parameter specifies the entry point of the ISR.
-The entry point of the previous ISR for the specified vector is
-returned in ``old_isr_handler``.
-
-To release an interrupt vector, pass the old handler’s address obtained
-when the vector was first capture.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-INTERRUPT_DISABLE - Disable Interrupts
---------------------------------------
-.. index:: disable interrupts
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_disable
-
-.. code:: c
-
- void rtems_interrupt_disable(
- rtems_interrupt_level level
- );
- /* this is implemented as a macro and sets level as a side-effect \*/
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive disables all maskable interrupts and returns
-the previous ``level``. A later invocation of the``rtems_interrupt_enable`` directive should be used to
-restore the interrupt level.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-*This directive is implemented as a macro which modifies the ``level``
-parameter.*
-
-This directive is only available on uni-processor configurations. The
-directive ``rtems_interrupt_local_disable`` is available on all
-configurations.
-
-INTERRUPT_ENABLE - Enable Interrupts
-------------------------------------
-.. index:: enable interrupts
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_enable
-
-.. code:: c
-
- void rtems_interrupt_enable(
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive enables maskable interrupts to the ``level``
-which was returned by a previous call to``rtems_interrupt_disable``.
-Immediately prior to invoking this directive, maskable interrupts should
-be disabled by a call to ``rtems_interrupt_disable``
-and will be enabled when this directive returns to the caller.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-This directive is only available on uni-processor configurations. The
-directive ``rtems_interrupt_local_enable`` is available on all
-configurations.
-
-INTERRUPT_FLASH - Flash Interrupts
-----------------------------------
-.. index:: flash interrupts
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_flash
-
-.. code:: c
-
- void rtems_interrupt_flash(
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive temporarily enables maskable interrupts to the ``level``
-which was returned by a previous call to``rtems_interrupt_disable``.
-Immediately prior to invoking this directive, maskable interrupts should
-be disabled by a call to ``rtems_interrupt_disable``
-and will be redisabled when this directive returns to the caller.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-This directive is only available on uni-processor configurations. The
-directives ``rtems_interrupt_local_disable`` and``rtems_interrupt_local_enable`` is available on all
-configurations.
-
-INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
------------------------------------------------------------------
-.. index:: disable interrupts
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_local_disable
-
-.. code:: c
-
- void rtems_interrupt_local_disable(
- rtems_interrupt_level level
- );
- /* this is implemented as a macro and sets level as a side-effect \*/
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive disables all maskable interrupts and returns
-the previous ``level``. A later invocation of the``rtems_interrupt_local_enable`` directive should be used to
-restore the interrupt level.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-*This directive is implemented as a macro which modifies the ``level``
-parameter.*
-
-On SMP configurations this will not ensure system wide mutual exclusion. Use
-interrupt locks instead.
-
-INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
----------------------------------------------------------------
-.. index:: enable interrupts
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_local_enable
-
-.. code:: c
-
- void rtems_interrupt_local_enable(
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive enables maskable interrupts to the ``level``
-which was returned by a previous call to``rtems_interrupt_local_disable``.
-Immediately prior to invoking this directive, maskable interrupts should
-be disabled by a call to ``rtems_interrupt_local_disable``
-and will be enabled when this directive returns to the caller.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
---------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_lock_initialize
-
-.. code:: c
-
- void rtems_interrupt_lock_initialize(
- rtems_interrupt_lock \*lock
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-Initializes an interrupt lock.
-
-**NOTES:**
-
-Concurrent initialization leads to unpredictable results.
-
-INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_lock_acquire
-
-.. code:: c
-
- void rtems_interrupt_lock_acquire(
- rtems_interrupt_lock \*lock,
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-Interrupts will be disabled. On SMP configurations this directive acquires a
-SMP lock.
-
-**NOTES:**
-
-This directive will not cause the calling thread to be preempted. This
-directive can be used in thread and interrupt context.
-
-INTERRUPT_LOCK_RELEASE - Release an ISR Lock
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_lock_release
-
-.. code:: c
-
- void rtems_interrupt_lock_release(
- rtems_interrupt_lock \*lock,
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-The interrupt status will be restored. On SMP configurations this directive
-releases a SMP lock.
-
-**NOTES:**
-
-This directive will not cause the calling thread to be preempted. This
-directive can be used in thread and interrupt context.
-
-INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
----------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_lock_acquire_isr
-
-.. code:: c
-
- void rtems_interrupt_lock_acquire_isr(
- rtems_interrupt_lock \*lock,
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-The interrupt status will remain unchanged. On SMP configurations this
-directive acquires a SMP lock.
-
-In case the corresponding interrupt service routine can be interrupted by
-higher priority interrupts and these interrupts enter the critical section
-protected by this lock, then the result is unpredictable.
-
-**NOTES:**
-
-This directive should be called from the corresponding interrupt service
-routine.
-
-INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
----------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_lock_release_isr
-
-.. code:: c
-
- void rtems_interrupt_lock_release_isr(
- rtems_interrupt_lock \*lock,
- rtems_interrupt_level level
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-The interrupt status will remain unchanged. On SMP configurations this
-directive releases a SMP lock.
-
-**NOTES:**
-
-This directive should be called from the corresponding interrupt service
-routine.
-
-INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
-------------------------------------------------
-.. index:: is interrupt in progress
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_interrupt_is_in_progress
-
-.. code:: c
-
- bool rtems_interrupt_is_in_progress( void );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive returns ``TRUE`` if the processor is currently
-servicing an interrupt and ``FALSE`` otherwise. A return value
-of ``TRUE`` indicates that the caller is an interrupt service
-routine, *NOT* a task. The directives available to an interrupt
-service routine are restricted.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Clock Manager
-#############
-
-.. index:: clock
-
-Introduction
-============
-
-The clock manager provides support for time of day
-and other time related capabilities. The directives provided by
-the clock manager are:
-
-- ``rtems_clock_set`` - Set date and time
-
-- ``rtems_clock_get`` - Get date and time information
-
-- ``rtems_clock_get_tod`` - Get date and time in TOD format
-
-- ``rtems_clock_get_tod_timeval`` - Get date and time in timeval format
-
-- ``rtems_clock_get_seconds_since_epoch`` - Get seconds since epoch
-
-- ``rtems_clock_get_ticks_per_second`` - Get ticks per second
-
-- ``rtems_clock_get_ticks_since_boot`` - Get current ticks counter value
-
-- ``rtems_clock_tick_later`` - Get tick value in the future
-
-- ``rtems_clock_tick_later_usec`` - Get tick value in the future in microseconds
-
-- ``rtems_clock_tick_before`` - Is tick value is before a point in time
-
-- ``rtems_clock_get_uptime`` - Get time since boot
-
-- ``rtems_clock_get_uptime_timeval`` - Get time since boot in timeval format
-
-- ``rtems_clock_get_uptime_seconds`` - Get seconds since boot
-
-- ``rtems_clock_get_uptime_nanoseconds`` - Get nanoseconds since boot
-
-- ``rtems_clock_set_nanoseconds_extension`` - Install the nanoseconds since last tick handler
-
-- ``rtems_clock_tick`` - Announce a clock tick
-
-Background
-==========
-
-Required Support
-----------------
-
-For the features provided by the clock manager to be
-utilized, periodic timer interrupts are required. Therefore, a
-real-time clock or hardware timer is necessary to create the
-timer interrupts. The ``rtems_clock_tick``
-directive is normally called
-by the timer ISR to announce to RTEMS that a system clock tick
-has occurred. Elapsed time is measured in ticks. A tick is
-defined to be an integral number of microseconds which is
-specified by the user in the Configuration Table.
-
-
-Time and Date Data Structures
------------------------------
-
-The clock facilities of the clock manager operate
-upon calendar time. These directives utilize the following date
-and time structure for the native time and date format:
-.. index:: rtems_time_of_day
-
-.. code:: c
-
- struct rtems_tod_control {
- uint32_t year; /* greater than 1987 \*/
- uint32_t month; /* 1 - 12 \*/
- uint32_t day; /* 1 - 31 \*/
- uint32_t hour; /* 0 - 23 \*/
- uint32_t minute; /* 0 - 59 \*/
- uint32_t second; /* 0 - 59 \*/
- uint32_t ticks; /* elapsed between seconds \*/
- };
- typedef struct rtems_tod_control rtems_time_of_day;
-
-The native date and time format is the only format
-supported when setting the system date and time using the``rtems_clock_set`` directive. Some applications
-expect to operate on a "UNIX-style" date and time data structure. The``rtems_clock_get_tod_timeval`` always returns
-the date and time in ``struct timeval`` format. The``rtems_clock_get`` directive can optionally return
-the current date and time in this format.
-
-The ``struct timeval`` data structure has two fields: ``tv_sec``
-and ``tv_usec`` which are seconds and microseconds, respectively.
-The ``tv_sec`` field in this data structure is the number of seconds
-since the POSIX epoch of January 1, 1970 but will never be prior to
-the RTEMS epoch of January 1, 1988.
-
-Clock Tick and Timeslicing
---------------------------
-.. index:: timeslicing
-
-Timeslicing is a task scheduling discipline in which
-tasks of equal priority are executed for a specific period of
-time before control of the CPU is passed to another task. It is
-also sometimes referred to as the automatic round-robin
-scheduling algorithm. The length of time allocated to each task
-is known as the quantum or timeslice.
-
-The system’s timeslice is defined as an integral
-number of ticks, and is specified in the Configuration Table.
-The timeslice is defined for the entire system of tasks, but
-timeslicing is enabled and disabled on a per task basis.
-
-The ``rtems_clock_tick``
-directive implements timeslicing by
-decrementing the running task’s time-remaining counter when both
-timeslicing and preemption are enabled. If the task’s timeslice
-has expired, then that task will be preempted if there exists a
-ready task of equal priority.
-
-Delays
-------
-.. index:: delays
-
-A sleep timer allows a task to delay for a given
-interval or up until a given time, and then wake and continue
-execution. This type of timer is created automatically by the``rtems_task_wake_after``
-and ``rtems_task_wake_when`` directives and, as a result,
-does not have an RTEMS ID. Once activated, a sleep timer cannot
-be explicitly deleted. Each task may activate one and only one
-sleep timer at a time.
-
-Timeouts
---------
-.. index:: timeouts
-
-Timeouts are a special type of timer automatically
-created when the timeout option is used on the``rtems_message_queue_receive``,``rtems_event_receive``,``rtems_semaphore_obtain`` and``rtems_region_get_segment`` directives.
-Each task may have one and only one timeout active at a time.
-When a timeout expires, it unblocks the task with a timeout status code.
-
-Operations
-==========
-
-Announcing a Tick
------------------
-
-RTEMS provides the ``rtems_clock_tick`` directive which is
-called from the user’s real-time clock ISR to inform RTEMS that
-a tick has elapsed. The tick frequency value, defined in
-microseconds, is a configuration parameter found in the
-Configuration Table. RTEMS divides one million microseconds
-(one second) by the number of microseconds per tick to determine
-the number of calls to the``rtems_clock_tick`` directive per second. The
-frequency of ``rtems_clock_tick``
-calls determines the resolution
-(granularity) for all time dependent RTEMS actions. For
-example, calling ``rtems_clock_tick``
-ten times per second yields a higher
-resolution than calling ``rtems_clock_tick``
-two times per second. The ``rtems_clock_tick``
-directive is responsible for maintaining both
-calendar time and the dynamic set of timers.
-
-Setting the Time
-----------------
-
-The ``rtems_clock_set`` directive allows a task or an ISR to
-set the date and time maintained by RTEMS. If setting the date
-and time causes any outstanding timers to pass their deadline,
-then the expired timers will be fired during the invocation of
-the ``rtems_clock_set`` directive.
-
-Obtaining the Time
-------------------
-
-The ``rtems_clock_get`` directive allows a task or an ISR to
-obtain the current date and time or date and time related
-information. The current date and time can be returned in
-either native or UNIX-style format. Additionally, the
-application can obtain date and time related information such as
-the number of seconds since the RTEMS epoch, the number of ticks
-since the executive was initialized, and the number of ticks per
-second. The information returned by the``rtems_clock_get`` directive is
-dependent on the option selected by the caller. This
-is specified using one of the following constants
-associated with the enumerated type``rtems_clock_get_options``:.. index:: rtems_clock_get_options
-
-- ``RTEMS_CLOCK_GET_TOD`` - obtain native style date and time
-
-- ``RTEMS_CLOCK_GET_TIME_VALUE`` - obtain UNIX-style
- date and time
-
-- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - obtain number of ticks
- since RTEMS was initialized
-
-- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - obtain number
- of seconds since RTEMS epoch
-
-- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - obtain number of clock
- ticks per second
-
-Calendar time operations will return an error code if
-invoked before the date and time have been set.
-
-Directives
-==========
-
-This section details the clock manager’s directives.
-A subsection is dedicated to each of this manager’s directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-CLOCK_SET - Set date and time
------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: set the time of day
-
-.. index:: rtems_clock_set
-
-.. code:: c
-
- rtems_status_code rtems_clock_set(
- rtems_time_of_day \*time_buffer
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - date and time set successfully
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
-``RTEMS_INVALID_CLOCK`` - invalid time of day
-
-**DESCRIPTION:**
-
-This directive sets the system date and time. The
-date, time, and ticks in the time_buffer structure are all
-range-checked, and an error is returned if any one is out of its
-valid range.
-
-**NOTES:**
-
-Years before 1988 are invalid.
-
-The system date and time are based on the configured
-tick rate (number of microseconds in a tick).
-
-Setting the time forward may cause a higher priority
-task, blocked waiting on a specific time, to be made ready. In
-this case, the calling task will be preempted after the next
-clock tick.
-
-Re-initializing RTEMS causes the system date and time
-to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize
-the system date and time to application specific specifications.
-
-CLOCK_GET - Get date and time information
------------------------------------------
-.. index:: obtain the time of day
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get
-
-.. code:: c
-
- rtems_status_code rtems_clock_get(
- rtems_clock_get_options option,
- void \*time_buffer
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - current time obtained successfully
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
-
-**DESCRIPTION:**
-
-This directive is deprecated.
-
-This directive obtains the system date and time. If
-the caller is attempting to obtain the date and time (i.e.
-option is set to either ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``,``RTEMS_CLOCK_GET_TOD``, or``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time
-has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
-The caller can always obtain the number of ticks per second (option is``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of
-ticks since the executive was initialized option is``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
-
-The ``option`` argument may taken on any value of the enumerated
-type ``rtems_clock_get_options``. The data type expected for``time_buffer`` is based on the value of ``option`` as
-indicated below:.. index:: rtems_clock_get_options
-
-- ``RTEMS_CLOCK_GET_TOD`` - (rtems_time_of_day \*)
-
-- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - (rtems_interval \*)
-
-- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - (rtems_interval \*)
-
-- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - (rtems_interval \*)
-
-- ``RTEMS_CLOCK_GET_TIME_VALUE`` - (struct timeval \*)
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be
-preempted. Re-initializing RTEMS causes the system date and
-time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the
-system date and time to application specific specifications.
-
-CLOCK_GET_TOD - Get date and time in TOD format
------------------------------------------------
-.. index:: obtain the time of day
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_tod
-
-.. code:: c
-
- rtems_status_code rtems_clock_get_tod(
- rtems_time_of_day \*time_buffer
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - current time obtained successfully
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
-
-**DESCRIPTION:**
-
-This directive obtains the system date and time. If the date and time
-has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be
-preempted. Re-initializing RTEMS causes the system date and
-time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the
-system date and time to application specific specifications.
-
-CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
------------------------------------------------------------
-.. index:: obtain the time of day
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_tod_timeval
-
-.. code:: c
-
- rtems_status_code rtems_clock_get_tod(
- struct timeval \*time
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - current time obtained successfully
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-``RTEMS_INVALID_ADDRESS`` - ``time`` is NULL
-
-**DESCRIPTION:**
-
-This directive obtains the system date and time in POSIX``struct timeval`` format. If the date and time
-has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be
-preempted. Re-initializing RTEMS causes the system date and
-time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the
-system date and time to application specific specifications.
-
-CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
--------------------------------------------------------
-.. index:: obtain seconds since epoch
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_seconds_since_epoch
-
-.. code:: c
-
- rtems_status_code rtems_clock_get_seconds_since_epoch(
- rtems_interval \*the_interval
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - current time obtained successfully
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-``RTEMS_INVALID_ADDRESS`` - ``the_interval`` is NULL
-
-**DESCRIPTION:**
-
-This directive returns the number of seconds since the RTEMS
-epoch and the current system date and time. If the date and time
-has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be
-preempted. Re-initializing RTEMS causes the system date and
-time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the
-system date and time to application specific specifications.
-
-CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
--------------------------------------------------
-.. index:: obtain seconds since epoch
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_ticks_per_second
-
-.. code:: c
-
- rtems_interval rtems_clock_get_ticks_per_second(void);
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive returns the number of clock ticks per second. This
-is strictly based upon the microseconds per clock tick that the
-application has configured.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be preempted.
-
-CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
-------------------------------------------------------------
-.. index:: obtain ticks since boot
-.. index:: get current ticks counter value
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_ticks_since_boot
-
-.. code:: c
-
- rtems_interval rtems_clock_get_ticks_since_boot(void);
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive returns the current tick counter value. With a 1ms clock tick,
-this counter overflows after 50 days since boot. This is the historical
-measure of uptime in an RTEMS system. The newer service``rtems_clock_get_uptime`` is another and potentially more
-accurate way of obtaining similar information.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be preempted.
-
-CLOCK_TICK_LATER - Get tick value in the future
------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_tick_later
-
-.. code:: c
-
- rtems_interval rtems_clock_tick_later(
- rtems_interval delta
- );
-
-**DESCRIPTION:**
-
-Returns the ticks counter value delta ticks in the future.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be preempted.
-
-CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
---------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_tick_later_usec
-
-.. code:: c
-
- rtems_interval rtems_clock_tick_later_usec(
- rtems_interval delta_in_usec
- );
-
-**DESCRIPTION:**
-
-Returns the ticks counter value at least delta microseconds in the future.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be preempted.
-
-CLOCK_TICK_BEFORE - Is tick value is before a point in time
------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_tick_before
-
-.. code:: c
-
- rtems_interval rtems_clock_tick_before(
- rtems_interval tick
- );
-
-**DESCRIPTION:**
-
-Returns true if the current ticks counter value indicates a time before the
-time specified by the tick value and false otherwise.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the running task to be preempted.
-
-**EXAMPLE:**
-
-.. code:: c
-
- status busy( void )
- {
- rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
- do {
- if ( ok() ) {
- return success;
- }
- } while ( rtems_clock_tick_before( timeout ) );
- return timeout;
- }
-
-CLOCK_GET_UPTIME - Get the time since boot
-------------------------------------------
-.. index:: clock get uptime
-.. index:: uptime
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_uptime
-
-.. code:: c
-
- rtems_status_code rtems_clock_get_uptime(
- struct timespec \*uptime
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - clock tick processed successfully
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
-
-**DESCRIPTION:**
-
-This directive returns the seconds and nanoseconds since the
-system was booted. If the BSP supports nanosecond clock
-accuracy, the time reported will probably be different on every
-call.
-
-**NOTES:**
-
-This directive may be called from an ISR.
-
-CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
---------------------------------------------------------------------
-.. index:: clock get uptime
-.. index:: uptime
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_uptime_timeval
-
-.. code:: c
-
- void rtems_clock_get_uptime_timeval(
- struct timeval \*uptime
- );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive returns the seconds and microseconds since the
-system was booted. If the BSP supports nanosecond clock
-accuracy, the time reported will probably be different on every
-call.
-
-**NOTES:**
-
-This directive may be called from an ISR.
-
-CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
------------------------------------------------------
-.. index:: clock get uptime
-.. index:: uptime
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_uptime_seconds
-
-.. code:: c
-
- time_t rtems_clock_get_uptime_seconds(void);
-
-**DIRECTIVE STATUS CODES:**
-
-The system uptime in seconds.
-
-**DESCRIPTION:**
-
-This directive returns the seconds since the system was booted.
-
-**NOTES:**
-
-This directive may be called from an ISR.
-
-CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
--------------------------------------------------------------
-.. index:: clock get nanoseconds uptime
-.. index:: uptime
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_get_uptime_nanoseconds
-
-.. code:: c
-
- uint64_t rtems_clock_get_uptime_nanoseconds(void);
-
-**DIRECTIVE STATUS CODES:**
-
-The system uptime in nanoseconds.
-
-**DESCRIPTION:**
-
-This directive returns the nanoseconds since the system was booted.
-
-**NOTES:**
-
-This directive may be called from an ISR.
-
-CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
----------------------------------------------------------------------------------
-.. index:: clock set nanoseconds extension
-.. index:: nanoseconds extension
-.. index:: nanoseconds time accuracy
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_set_nanoseconds_extension
-
-.. code:: c
-
- rtems_status_code rtems_clock_set_nanoseconds_extension(
- rtems_nanoseconds_extension_routine routine
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - clock tick processed successfully
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
-
-**DESCRIPTION:**
-
-This directive is used by the Clock device driver to install the``routine`` which will be invoked by the internal RTEMS method used to
-obtain a highly accurate time of day. It is usually called during
-the initialization of the driver.
-
-When the ``routine`` is invoked, it will determine the number of
-nanoseconds which have elapsed since the last invocation of
-the ``rtems_clock_tick`` directive. It should do
-this as quickly as possible with as little impact as possible
-on the device used as a clock source.
-
-**NOTES:**
-
-This directive may be called from an ISR.
-
-This directive is called as part of every service to obtain the
-current date and time as well as timestamps.
-
-CLOCK_TICK - Announce a clock tick
-----------------------------------
-.. index:: clock tick
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_clock_tick
-
-.. code:: c
-
- rtems_status_code rtems_clock_tick( void );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - clock tick processed successfully
-
-**DESCRIPTION:**
-
-This directive announces to RTEMS that a system clock
-tick has occurred. The directive is usually called from the
-timer interrupt ISR of the local processor. This directive
-maintains the system date and time, decrements timers for
-delayed tasks, timeouts, rate monotonic periods, and implements
-timeslicing.
-
-**NOTES:**
-
-This directive is typically called from an ISR.
-
-The ``microseconds_per_tick`` and ``ticks_per_timeslice``
-parameters in the Configuration Table contain the number of
-microseconds per tick and number of ticks per timeslice,
-respectively.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Timer Manager
-#############
-
-.. index:: timers
-
-Introduction
-============
-
-The timer manager provides support for timer
-facilities. The directives provided by the timer manager are:
-
-- ``rtems_timer_create`` - Create a timer
-
-- ``rtems_timer_ident`` - Get ID of a timer
-
-- ``rtems_timer_cancel`` - Cancel a timer
-
-- ``rtems_timer_delete`` - Delete a timer
-
-- ``rtems_timer_fire_after`` - Fire timer after interval
-
-- ``rtems_timer_fire_when`` - Fire timer when specified
-
-- ``rtems_timer_initiate_server`` - Initiate server for task-based timers
-
-- ``rtems_timer_server_fire_after`` - Fire task-based timer after interval
-
-- ``rtems_timer_server_fire_when`` - Fire task-based timer when specified
-
-- ``rtems_timer_reset`` - Reset an interval timer
-
-Background
-==========
-
-Required Support
-----------------
-
-A clock tick is required to support the functionality provided by this manager.
-
-Timers
-------
-
-A timer is an RTEMS object which allows the
-application to schedule operations to occur at specific times in
-the future. User supplied timer service routines are invoked by
-either the ``rtems_clock_tick`` directive or
-a special Timer Server task when the timer fires. Timer service
-routines may perform any operations or directives which normally
-would be performed by the application code which invoked the``rtems_clock_tick`` directive.
-
-The timer can be used to implement watchdog routines
-which only fire to denote that an application error has
-occurred. The timer is reset at specific points in the
-application to ensure that the watchdog does not fire. Thus, if
-the application does not reset the watchdog timer, then the
-timer service routine will fire to indicate that the application
-has failed to reach a reset point. This use of a timer is
-sometimes referred to as a "keep alive" or a "deadman" timer.
-
-Timer Server
-------------
-
-The Timer Server task is responsible for executing the timer
-service routines associated with all task-based timers.
-This task executes at a priority higher than any RTEMS application
-task, and is created non-preemptible, and thus can be viewed logically as
-the lowest priority interrupt.
-
-By providing a mechanism where timer service routines execute
-in task rather than interrupt space, the application is
-allowed a bit more flexibility in what operations a timer
-service routine can perform. For example, the Timer Server
-can be configured to have a floating point context in which case
-it would be safe to perform floating point operations
-from a task-based timer. Most of the time, executing floating
-point instructions from an interrupt service routine
-is not considered safe. However, since the Timer Server task
-is non-preemptible, only directives allowed from an ISR can be
-called in the timer service routine.
-
-The Timer Server is designed to remain blocked until a
-task-based timer fires. This reduces the execution overhead
-of the Timer Server.
-
-Timer Service Routines
-----------------------
-
-The timer service routine should adhere to C calling
-conventions and have a prototype similar to the following:.. index:: rtems_timer_service_routine
-
-.. code:: c
-
- rtems_timer_service_routine user_routine(
- rtems_id timer_id,
- void \*user_data
- );
-
-Where the timer_id parameter is the RTEMS object ID
-of the timer which is being fired and user_data is a pointer to
-user-defined information which may be utilized by the timer
-service routine. The argument user_data may be NULL.
-
-Operations
-==========
-
-Creating a Timer
-----------------
-
-The ``rtems_timer_create`` directive creates a timer by
-allocating a Timer Control Block (TMCB), assigning the timer a
-user-specified name, and assigning it a timer ID. Newly created
-timers do not have a timer service routine associated with them
-and are not active.
-
-Obtaining Timer IDs
--------------------
-
-When a timer is created, RTEMS generates a unique
-timer ID and assigns it to the created timer until it is
-deleted. The timer ID may be obtained by either of two methods.
-First, as the result of an invocation of the``rtems_timer_create``
-directive, the timer ID is stored in a user provided location.
-Second, the timer ID may be obtained later using the``rtems_timer_ident`` directive. The timer ID
-is used by other directives to manipulate this timer.
-
-Initiating an Interval Timer
-----------------------------
-
-The ``rtems_timer_fire_after``
-and ``rtems_timer_server_fire_after``
-directives initiate a timer to fire a user provided
-timer service routine after the specified
-number of clock ticks have elapsed. When the interval has
-elapsed, the timer service routine will be invoked from the``rtems_clock_tick`` directive if it was initiated
-by the ``rtems_timer_fire_after`` directive
-and from the Timer Server task if initiated by the``rtems_timer_server_fire_after`` directive.
-
-Initiating a Time of Day Timer
-------------------------------
-
-The ``rtems_timer_fire_when``
-and ``rtems_timer_server_fire_when``
-directive initiate a timer to
-fire a user provided timer service routine when the specified
-time of day has been reached. When the interval has elapsed,
-the timer service routine will be invoked from the``rtems_clock_tick`` directive
-by the ``rtems_timer_fire_when`` directive
-and from the Timer Server task if initiated by the``rtems_timer_server_fire_when`` directive.
-
-Canceling a Timer
------------------
-
-The ``rtems_timer_cancel`` directive is used to halt the
-specified timer. Once canceled, the timer service routine will
-not fire unless the timer is reinitiated. The timer can be
-reinitiated using the ``rtems_timer_reset``,``rtems_timer_fire_after``, and``rtems_timer_fire_when`` directives.
-
-Resetting a Timer
------------------
-
-The ``rtems_timer_reset`` directive is used to restore an
-interval timer initiated by a previous invocation of``rtems_timer_fire_after`` or``rtems_timer_server_fire_after`` to
-its original interval length. If the
-timer has not been used or the last usage of this timer
-was by the ``rtems_timer_fire_when``
-or ``rtems_timer_server_fire_when``
-directive, then an error is returned. The timer service routine
-is not changed or fired by this directive.
-
-Initiating the Timer Server
----------------------------
-
-The ``rtems_timer_initiate_server`` directive is used to
-allocate and start the execution of the Timer Server task. The
-application can specify both the stack size and attributes of the
-Timer Server. The Timer Server executes at a priority higher than
-any application task and thus the user can expect to be preempted
-as the result of executing the ``rtems_timer_initiate_server``
-directive.
-
-Deleting a Timer
-----------------
-
-The ``rtems_timer_delete`` directive is used to delete a timer.
-If the timer is running and has not expired, the timer is
-automatically canceled. The timer’s control block is returned
-to the TMCB free list when it is deleted. A timer can be
-deleted by a task other than the task which created the timer.
-Any subsequent references to the timer’s name and ID are invalid.
-
-Directives
-==========
-
-This section details the timer manager’s directives.
-A subsection is dedicated to each of this manager’s directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-TIMER_CREATE - Create a timer
------------------------------
-.. index:: create a timer
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_create
-
-.. code:: c
-
- rtems_status_code rtems_timer_create(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer created successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - invalid timer name
-``RTEMS_TOO_MANY`` - too many timers created
-
-**DESCRIPTION:**
-
-This directive creates a timer. The assigned timer
-id is returned in id. This id is used to access the timer with
-other timer manager directives. For control and maintenance of
-the timer, RTEMS allocates a TMCB from the local TMCB free pool
-and initializes it.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-TIMER_IDENT - Get ID of a timer
--------------------------------
-.. index:: obtain the ID of a timer
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_ident
-
-.. code:: c
-
- rtems_status_code rtems_timer_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer identified successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - timer name not found
-
-**DESCRIPTION:**
-
-This directive obtains the timer id associated with
-the timer name to be acquired. If the timer name is not unique,
-then the timer id will match one of the timers with that name.
-However, this timer id is not guaranteed to correspond to the
-desired timer. The timer id is used to access this timer in
-other timer related directives.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-TIMER_CANCEL - Cancel a timer
------------------------------
-.. index:: cancel a timer
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_cancel
-
-.. code:: c
-
- rtems_status_code rtems_timer_cancel(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer canceled successfully
-``RTEMS_INVALID_ID`` - invalid timer id
-
-**DESCRIPTION:**
-
-This directive cancels the timer id. This timer will
-be reinitiated by the next invocation of ``rtems_timer_reset``,``rtems_timer_fire_after``, or``rtems_timer_fire_when`` with this id.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-TIMER_DELETE - Delete a timer
------------------------------
-.. index:: delete a timer
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_delete
-
-.. code:: c
-
- rtems_status_code rtems_timer_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer deleted successfully
-``RTEMS_INVALID_ID`` - invalid timer id
-
-**DESCRIPTION:**
-
-This directive deletes the timer specified by id. If
-the timer is running, it is automatically canceled. The TMCB
-for the deleted timer is reclaimed by RTEMS.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-A timer can be deleted by a task other than the task
-which created the timer.
-
-TIMER_FIRE_AFTER - Fire timer after interval
---------------------------------------------
-.. index:: fire a timer after an interval
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_fire_after
-
-.. code:: c
-
- rtems_status_code rtems_timer_fire_after(
- rtems_id id,
- rtems_interval ticks,
- rtems_timer_service_routine_entry routine,
- void \*user_data
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer initiated successfully
-``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL
-``RTEMS_INVALID_ID`` - invalid timer id
-``RTEMS_INVALID_NUMBER`` - invalid interval
-
-**DESCRIPTION:**
-
-This directive initiates the timer specified by id.
-If the timer is running, it is automatically canceled before
-being initiated. The timer is scheduled to fire after an
-interval ticks clock ticks has passed. When the timer fires,
-the timer service routine routine will be invoked with the
-argument user_data.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-TIMER_FIRE_WHEN - Fire timer when specified
--------------------------------------------
-.. index:: fire a timer at wall time
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_fire_when
-
-.. code:: c
-
- rtems_status_code rtems_timer_fire_when(
- rtems_id id,
- rtems_time_of_day \*wall_time,
- rtems_timer_service_routine_entry routine,
- void \*user_data
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer initiated successfully
-``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL
-``RTEMS_INVALID_ID`` - invalid timer id
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-``RTEMS_INVALID_CLOCK`` - invalid time of day
-
-**DESCRIPTION:**
-
-This directive initiates the timer specified by id.
-If the timer is running, it is automatically canceled before
-being initiated. The timer is scheduled to fire at the time of
-day specified by wall_time. When the timer fires, the timer
-service routine routine will be invoked with the argument
-user_data.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-TIMER_INITIATE_SERVER - Initiate server for task-based timers
--------------------------------------------------------------
-.. index:: initiate the Timer Server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_initiate_server
-
-.. code:: c
-
- rtems_status_code rtems_timer_initiate_server(
- uint32_t priority,
- uint32_t stack_size,
- rtems_attribute attribute_set
- )
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - Timer Server initiated successfully
-``RTEMS_TOO_MANY`` - too many tasks created
-
-**DESCRIPTION:**
-
-This directive initiates the Timer Server task. This task
-is responsible for executing all timers initiated via the``rtems_timer_server_fire_after`` or``rtems_timer_server_fire_when`` directives.
-
-**NOTES:**
-
-This directive could cause the calling task to be preempted.
-
-The Timer Server task is created using the``rtems_task_create`` service and must be accounted
-for when configuring the system.
-
-Even through this directive invokes the ``rtems_task_create``
-and ``rtems_task_start`` directives, it should only fail
-due to resource allocation problems.
-
-TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
---------------------------------------------------------------
-.. index:: fire task-based a timer after an interval
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_server_fire_after
-
-.. code:: c
-
- rtems_status_code rtems_timer_server_fire_after(
- rtems_id id,
- rtems_interval ticks,
- rtems_timer_service_routine_entry routine,
- void \*user_data
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer initiated successfully
-``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL
-``RTEMS_INVALID_ID`` - invalid timer id
-``RTEMS_INVALID_NUMBER`` - invalid interval
-``RTEMS_INCORRECT_STATE`` - Timer Server not initiated
-
-**DESCRIPTION:**
-
-This directive initiates the timer specified by id and specifies
-that when it fires it will be executed by the Timer Server.
-
-If the timer is running, it is automatically canceled before
-being initiated. The timer is scheduled to fire after an
-interval ticks clock ticks has passed. When the timer fires,
-the timer service routine routine will be invoked with the
-argument user_data.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
--------------------------------------------------------------
-.. index:: fire a task-based timer at wall time
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_server_fire_when
-
-.. code:: c
-
- rtems_status_code rtems_timer_server_fire_when(
- rtems_id id,
- rtems_time_of_day \*wall_time,
- rtems_timer_service_routine_entry routine,
- void \*user_data
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer initiated successfully
-``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL
-``RTEMS_INVALID_ID`` - invalid timer id
-``RTEMS_NOT_DEFINED`` - system date and time is not set
-``RTEMS_INVALID_CLOCK`` - invalid time of day
-``RTEMS_INCORRECT_STATE`` - Timer Server not initiated
-
-**DESCRIPTION:**
-
-This directive initiates the timer specified by id and specifies
-that when it fires it will be executed by the Timer Server.
-
-If the timer is running, it is automatically canceled before
-being initiated. The timer is scheduled to fire at the time of
-day specified by wall_time. When the timer fires, the timer
-service routine routine will be invoked with the argument
-user_data.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-TIMER_RESET - Reset an interval timer
--------------------------------------
-.. index:: reset a timer
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_timer_reset
-
-.. code:: c
-
- rtems_status_code rtems_timer_reset(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - timer reset successfully
-``RTEMS_INVALID_ID`` - invalid timer id
-``RTEMS_NOT_DEFINED`` - attempted to reset a when or newly created timer
-
-**DESCRIPTION:**
-
-This directive resets the timer associated with id.
-This timer must have been previously initiated with either the``rtems_timer_fire_after`` or``rtems_timer_server_fire_after``
-directive. If active the timer is canceled,
-after which the timer is reinitiated using the same interval and
-timer service routine which the original``rtems_timer_fire_after````rtems_timer_server_fire_after``
-directive used.
-
-**NOTES:**
-
-If the timer has not been used or the last usage of this timer
-was by a ``rtems_timer_fire_when`` or``rtems_timer_server_fire_when``
-directive, then the ``RTEMS_NOT_DEFINED`` error is
-returned.
-
-Restarting a cancelled after timer results in the timer being
-reinitiated with its previous timer service routine and interval.
-
-This directive will not cause the running task to be preempted.
-
-.. COMMENT: COPYRIGHT (c) 1988-2013.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: Open Issues
-
-.. COMMENT: - nicen up the tables
-
-.. COMMENT: - use math mode to print formulas
-
-Rate Monotonic Manager
-######################
-
-.. index:: rate mononitonic tasks
-.. index:: periodic tasks
-
-Introduction
-============
-
-The rate monotonic manager provides facilities to implement tasks which execute
-in a periodic fashion. Critically, it also gathers information about the
-execution of those periods and can provide important statistics to the
-user which can be used to analyze and tune the application. The directives
-provided by the rate monotonic manager are:
-
-- ``rtems_rate_monotonic_create`` - Create a rate monotonic period
-
-- ``rtems_rate_monotonic_ident`` - Get ID of a period
-
-- ``rtems_rate_monotonic_cancel`` - Cancel a period
-
-- ``rtems_rate_monotonic_delete`` - Delete a rate monotonic period
-
-- ``rtems_rate_monotonic_period`` - Conclude current/Start next period
-
-- ``rtems_rate_monotonic_get_status`` - Obtain status from a period
-
-- ``rtems_rate_monotonic_get_statistics`` - Obtain statistics from a period
-
-- ``rtems_rate_monotonic_reset_statistics`` - Reset statistics for a period
-
-- ``rtems_rate_monotonic_reset_all_statistics`` - Reset statistics for all periods
-
-- ``rtems_rate_monotonic_report_statistics`` - Print period statistics report
-
-Background
-==========
-
-The rate monotonic manager provides facilities to
-manage the execution of periodic tasks. This manager was
-designed to support application designers who utilize the Rate
-Monotonic Scheduling Algorithm (RMS) to ensure that their
-periodic tasks will meet their deadlines, even under transient
-overload conditions. Although designed for hard real-time
-systems, the services provided by the rate monotonic manager may
-be used by any application which requires periodic tasks.
-
-Rate Monotonic Manager Required Support
----------------------------------------
-
-A clock tick is required to support the functionality provided by this manager.
-
-Period Statistics
------------------
-
-This manager maintains a set of statistics on each period object. These
-statistics are reset implictly at period creation time and may be reset or
-obtained at any time by the application. The following is a list of the
-information kept:
-
-- ``owner``
- is the id of the thread that owns this period.
-
-- ``count``
- is the total number of periods executed.
-
-- ``missed_count``
- is the number of periods that were missed.
-
-- ``min_cpu_time``
- is the minimum amount of CPU execution time consumed
- on any execution of the periodic loop.
-
-- ``max_cpu_time``
- is the maximum amount of CPU execution time consumed
- on any execution of the periodic loop.
-
-- ``total_cpu_time``
- is the total amount of CPU execution time consumed
- by executions of the periodic loop.
-
-- ``min_wall_time``
- is the minimum amount of wall time that passed
- on any execution of the periodic loop.
-
-- ``max_wall_time``
- is the maximum amount of wall time that passed
- on any execution of the periodic loop.
-
-- ``total_wall_time``
- is the total amount of wall time that passed
- during executions of the periodic loop.
-
-Each period is divided into two consecutive phases. The period starts with the
-active phase of the task and is followed by the inactive phase of the task. In
-the inactive phase the task is blocked and waits for the start of the next
-period. The inactive phase is skipped in case of a period miss. The wall time
-includes the time during the active phase of the task on which the task is not
-executing on a processor. The task is either blocked (for example it waits for
-a resource) or a higher priority tasks executes, thus preventing it from
-executing. In case the wall time exceeds the period time, then this is a
-period miss. The gap between the wall time and the period time is the margin
-between a period miss or success.
-
-The period statistics information is inexpensive to maintain
-and can provide very useful insights into the execution
-characteristics of a periodic task loop. But it is just information.
-The period statistics reported must be analyzed by the user in terms
-of what the applications is. For example, in an application where
-priorities are assigned by the Rate Monotonic Algorithm, it would
-be very undesirable for high priority (i.e. frequency) tasks to
-miss their period. Similarly, in nearly any application, if a
-task were supposed to execute its periodic loop every 10 milliseconds
-and it averaged 11 milliseconds, then application requirements
-are not being met.
-
-The information reported can be used to determine the "hot spots"
-in the application. Given a period’s id, the user can determine
-the length of that period. From that information and the CPU usage,
-the user can calculate the percentage of CPU time consumed by that
-periodic task. For example, a task executing for 20 milliseconds
-every 200 milliseconds is consuming 10 percent of the processor’s
-execution time. This is usually enough to make it a good candidate
-for optimization.
-
-However, execution time alone is not enough to gauge the value of
-optimizing a particular task. It is more important to optimize
-a task executing 2 millisecond every 10 milliseconds (20 percent
-of the CPU) than one executing 10 milliseconds every 100 (10 percent
-of the CPU). As a general rule of thumb, the higher frequency at
-which a task executes, the more important it is to optimize that
-task.
-
-Rate Monotonic Manager Definitions
-----------------------------------
-.. index:: periodic task, definition
-
-A periodic task is one which must be executed at a
-regular interval. The interval between successive iterations of
-the task is referred to as its period. Periodic tasks can be
-characterized by the length of their period and execution time.
-The period and execution time of a task can be used to determine
-the processor utilization for that task. Processor utilization
-is the percentage of processor time used and can be calculated
-on a per-task or system-wide basis. Typically, the task’s
-worst-case execution time will be less than its period. For
-example, a periodic task’s requirements may state that it should
-execute for 10 milliseconds every 100 milliseconds. Although
-the execution time may be the average, worst, or best case, the
-worst-case execution time is more appropriate for use when
-analyzing system behavior under transient overload conditions... index:: aperiodic task, definition
-
-In contrast, an aperiodic task executes at irregular
-intervals and has only a soft deadline. In other words, the
-deadlines for aperiodic tasks are not rigid, but adequate
-response times are desirable. For example, an aperiodic task
-may process user input from a terminal... index:: sporadic task, definition
-
-Finally, a sporadic task is an aperiodic task with a
-hard deadline and minimum interarrival time. The minimum
-interarrival time is the minimum period of time which exists
-between successive iterations of the task. For example, a
-sporadic task could be used to process the pressing of a fire
-button on a joystick. The mechanical action of the fire button
-ensures a minimum time period between successive activations,
-but the missile must be launched by a hard deadline.
-
-Rate Monotonic Scheduling Algorithm
------------------------------------
-.. index:: Rate Monotonic Scheduling Algorithm, definition
-.. index:: RMS Algorithm, definition
-
-The Rate Monotonic Scheduling Algorithm (RMS) is
-important to real-time systems designers because it allows one
-to guarantee that a set of tasks is schedulable. A set of tasks
-is said to be schedulable if all of the tasks can meet their
-deadlines. RMS provides a set of rules which can be used to
-perform a guaranteed schedulability analysis for a task set.
-This analysis determines whether a task set is schedulable under
-worst-case conditions and emphasizes the predictability of the
-system’s behavior. It has been proven that:
-
-- *RMS is an optimal static priority algorithm for
- scheduling independent, preemptible, periodic tasks
- on a single processor.*
-
-RMS is optimal in the sense that if a set of tasks
-can be scheduled by any static priority algorithm, then RMS will
-be able to schedule that task set. RMS bases it schedulability
-analysis on the processor utilization level below which all
-deadlines can be met.
-
-RMS calls for the static assignment of task
-priorities based upon their period. The shorter a task’s
-period, the higher its priority. For example, a task with a 1
-millisecond period has higher priority than a task with a 100
-millisecond period. If two tasks have the same period, then RMS
-does not distinguish between the tasks. However, RTEMS
-specifies that when given tasks of equal priority, the task
-which has been ready longest will execute first. RMS’s priority
-assignment scheme does not provide one with exact numeric values
-for task priorities. For example, consider the following task
-set and priority assignments:
-
-+--------------------+---------------------+---------------------+
-| Task | Period | Priority |
-| | (in milliseconds) | |
-+====================+=====================+=====================+
-| 1 | 100 | Low |
-+--------------------+---------------------+---------------------+
-| 2 | 50 | Medium |
-+--------------------+---------------------+---------------------+
-| 3 | 50 | Medium |
-+--------------------+---------------------+---------------------+
-| 4 | 25 | High |
-+--------------------+---------------------+---------------------+
-
-RMS only calls for task 1 to have the lowest
-priority, task 4 to have the highest priority, and tasks 2 and 3
-to have an equal priority between that of tasks 1 and 4. The
-actual RTEMS priorities assigned to the tasks must only adhere
-to those guidelines.
-
-Many applications have tasks with both hard and soft
-deadlines. The tasks with hard deadlines are typically referred
-to as the critical task set, with the soft deadline tasks being
-the non-critical task set. The critical task set can be
-scheduled using RMS, with the non-critical tasks not executing
-under transient overload, by simply assigning priorities such
-that the lowest priority critical task (i.e. longest period) has
-a higher priority than the highest priority non-critical task.
-Although RMS may be used to assign priorities to the
-non-critical tasks, it is not necessary. In this instance,
-schedulability is only guaranteed for the critical task set.
-
-Schedulability Analysis
------------------------
-
-.. index:: RMS schedulability analysis
-
-RMS allows application designers to ensure that tasks
-can meet all deadlines, even under transient overload, without
-knowing exactly when any given task will execute by applying
-proven schedulability analysis rules.
-
-Assumptions
-~~~~~~~~~~~
-
-The schedulability analysis rules for RMS were
-developed based on the following assumptions:
-
-- The requests for all tasks for which hard deadlines
- exist are periodic, with a constant interval between requests.
-
-- Each task must complete before the next request for it
- occurs.
-
-- The tasks are independent in that a task does not depend
- on the initiation or completion of requests for other tasks.
-
-- The execution time for each task without preemption or
- interruption is constant and does not vary.
-
-- Any non-periodic tasks in the system are special. These
- tasks displace periodic tasks while executing and do not have
- hard, critical deadlines.
-
-Once the basic schedulability analysis is understood,
-some of the above assumptions can be relaxed and the
-side-effects accounted for.
-
-Processor Utilization Rule
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. index:: RMS Processor Utilization Rule
-
-The Processor Utilization Rule requires that
-processor utilization be calculated based upon the period and
-execution time of each task. The fraction of processor time
-spent executing task index is Time(index) / Period(index). The
-processor utilization can be calculated as follows:
-.. code:: c
-
- Utilization = 0
- for index = 1 to maximum_tasks
- Utilization = Utilization + (Time(index)/Period(index))
-
-To ensure schedulability even under transient
-overload, the processor utilization must adhere to the following
-rule:
-.. code:: c
-
- Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1)
-
-As the number of tasks increases, the above formula
-approaches ln(2) for a worst-case utilization factor of
-approximately 0.693. Many tasks sets can be scheduled with a
-greater utilization factor. In fact, the average processor
-utilization threshold for a randomly generated task set is
-approximately 0.88.
-
-Processor Utilization Rule Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This example illustrates the application of the
-Processor Utilization Rule to an application with three critical
-periodic tasks. The following table details the RMS priority,
-period, execution time, and processor utilization for each task:
-
-
-+------------+----------+--------+-----------+-------------+
-| Tas k | RMS | Period | Execution | Processor |
-| | Priority | | Time | Utilization |
-+============+==========+========+===========+=============+
-| 1 | High | 100 | 15 | 0.15 |
-+------------+----------+--------+-----------+-------------+
-| 2 | Medium | 200 | 50 | 0.25 |
-+------------+----------+--------+-----------+-------------+
-| 3 | Low | 300 | 100 | 0.33 |
-+------------+----------+--------+-----------+-------------+
-
-The total processor utilization for this task set is
-0.73 which is below the upper bound of 3 * (2**(1/3) - 1), or
-0.779, imposed by the Processor Utilization Rule. Therefore,
-this task set is guaranteed to be schedulable using RMS.
-
-First Deadline Rule
-~~~~~~~~~~~~~~~~~~~
-.. index:: RMS First Deadline Rule
-
-If a given set of tasks do exceed the processor
-utilization upper limit imposed by the Processor Utilization
-Rule, they can still be guaranteed to meet all their deadlines
-by application of the First Deadline Rule. This rule can be
-stated as follows:
-
-For a given set of independent periodic tasks, if
-each task meets its first deadline when all tasks are started at
-the same time, then the deadlines will always be met for any
-combination of start times.
-
-A key point with this rule is that ALL periodic tasks
-are assumed to start at the exact same instant in time.
-Although this assumption may seem to be invalid, RTEMS makes it
-quite easy to ensure. By having a non-preemptible user
-initialization task, all application tasks, regardless of
-priority, can be created and started before the initialization
-deletes itself. This technique ensures that all tasks begin to
-compete for execution time at the same instant – when the user
-initialization task deletes itself.
-
-First Deadline Rule Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The First Deadline Rule can ensure schedulability
-even when the Processor Utilization Rule fails. The example
-below is a modification of the Processor Utilization Rule
-example where task execution time has been increased from 15 to
-25 units. The following table details the RMS priority, period,
-execution time, and processor utilization for each task:
-.. code:: c
-
-+------------+----------+--------+-----------+-------------+
-| Task | RMS | Period | Execution | Processor |
-| | Priority | | Time | Utilization |
-+============+==========+========+===========+=============+
-| 1 | High | 100 | 25 | 0.25 |
-+------------+----------+--------+-----------+-------------+
-| 2 | Medium | 200 | 50 | 0.25 |
-+------------+----------+--------+-----------+-------------+
-| 3 | Low | 300 | 100 | 0.33 |
-+------------+----------+--------+-----------+-------------+
-
-The total processor utilization for the modified task
-set is 0.83 which is above the upper bound of 3 * (2**(1/3) - 1),
-or 0.779, imposed by the Processor Utilization Rule. Therefore,
-this task set is not guaranteed to be schedulable using RMS.
-However, the First Deadline Rule can guarantee the
-schedulability of this task set. This rule calls for one to
-examine each occurrence of deadline until either all tasks have
-met their deadline or one task failed to meet its first
-deadline. The following table details the time of each deadline
-occurrence, the maximum number of times each task may have run,
-the total execution time, and whether all the deadlines have
-been met.
-.. code:: c
-
-+----------+------+------+------+----------------------+---------------+
-| Deadline | Task | Task | Task | Total | All Deadlines |
-| Time | 1 | 2 | 3 | Execution Time | Met? |
-+==========+======+======+======+======================+===============+
-| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO |
-+----------+------+------+------+----------------------+---------------+
-| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES |
-+----------+------+------+------+----------------------+---------------+
-
-The key to this analysis is to recognize when each
-task will execute. For example at time 100, task 1 must have
-met its first deadline, but tasks 2 and 3 may also have begun
-execution. In this example, at time 100 tasks 1 and 2 have
-completed execution and thus have met their first deadline.
-Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100
-- 75) = 25 time units for task 3 to begin. Because task 3 takes
-100 ticks to execute, it will not have completed execution at
-time 100. Thus at time 100, all of the tasks except task 3 have
-met their first deadline.
-
-At time 200, task 1 must have met its second deadline
-and task 2 its first deadline. As a result, of the first 200
-time units, task 1 uses (2 * 25) = 50 and task 2 uses 50,
-leaving (200 - 100) time units for task 3. Task 3 requires 100
-time units to execute, thus it will have completed execution at
-time 200. Thus, all of the tasks have met their first deadlines
-at time 200, and the task set is schedulable using the First
-Deadline Rule.
-
-Relaxation of Assumptions
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The assumptions used to develop the RMS
-schedulability rules are uncommon in most real-time systems.
-For example, it was assumed that tasks have constant unvarying
-execution time. It is possible to relax this assumption, simply
-by using the worst-case execution time of each task.
-
-Another assumption is that the tasks are independent.
-This means that the tasks do not wait for one another or
-contend for resources. This assumption can be relaxed by
-accounting for the amount of time a task spends waiting to
-acquire resources. Similarly, each task’s execution time must
-account for any I/O performed and any RTEMS directive calls.
-
-In addition, the assumptions did not account for the
-time spent executing interrupt service routines. This can be
-accounted for by including all the processor utilization by
-interrupt service routines in the utilization calculation.
-Similarly, one should also account for the impact of delays in
-accessing local memory caused by direct memory access and other
-processors accessing local dual-ported memory.
-
-The assumption that nonperiodic tasks are used only
-for initialization or failure-recovery can be relaxed by placing
-all periodic tasks in the critical task set. This task set can
-be scheduled and analyzed using RMS. All nonperiodic tasks are
-placed in the non-critical task set. Although the critical task
-set can be guaranteed to execute even under transient overload,
-the non-critical task set is not guaranteed to execute.
-
-In conclusion, the application designer must be fully
-cognizant of the system and its run-time behavior when
-performing schedulability analysis for a system using RMS.
-Every hardware and software factor which impacts the execution
-time of each task must be accounted for in the schedulability
-analysis.
-
-Further Reading
-~~~~~~~~~~~~~~~
-
-For more information on Rate Monotonic Scheduling and
-its schedulability analysis, the reader is referred to the
-following:
-
-- *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
- Multiprogramming in a Hard Real Time Environment." *Journal of
- the Association of Computing Machinery*. January 1973. pp. 46-61.*
-
-- *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
- Scheduling Algorithm: Exact Characterization and Average Case
- Behavior." *IEEE Real-Time Systems Symposium*. 1989. pp. 166-171.*
-
-- *Lui Sha and John Goodenough. "Real-Time Scheduling
- theory and Ada." *IEEE Computer*. April 1990. pp. 53-62.*
-
-- *Alan Burns. "Scheduling hard real-time systems: a
- review." *Software Engineering Journal*. May 1991. pp. 116-128.*
-
-Operations
-==========
-
-Creating a Rate Monotonic Period
---------------------------------
-
-The ``rtems_rate_monotonic_create`` directive creates a rate
-monotonic period which is to be used by the calling task to
-delineate a period. RTEMS allocates a Period Control Block
-(PCB) from the PCB free list. This data structure is used by
-RTEMS to manage the newly created rate monotonic period. RTEMS
-returns a unique period ID to the application which is used by
-other rate monotonic manager directives to access this rate
-monotonic period.
-
-Manipulating a Period
----------------------
-
-The ``rtems_rate_monotonic_period`` directive is used to
-establish and maintain periodic execution utilizing a previously
-created rate monotonic period. Once initiated by the``rtems_rate_monotonic_period`` directive, the period is
-said to run until it either expires or is reinitiated. The state of the rate
-monotonic period results in one of the following scenarios:
-
-- If the rate monotonic period is running, the calling
- task will be blocked for the remainder of the outstanding period
- and, upon completion of that period, the period will be
- reinitiated with the specified period.
-
-- If the rate monotonic period is not currently running
- and has not expired, it is initiated with a length of period
- ticks and the calling task returns immediately.
-
-- If the rate monotonic period has expired before the task
- invokes the ``rtems_rate_monotonic_period`` directive,
- the period will be initiated with a length of period ticks and the calling task
- returns immediately with a timeout error status.
-
-Obtaining the Status of a Period
---------------------------------
-
-If the ``rtems_rate_monotonic_period`` directive is invoked
-with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current
-state of the specified rate monotonic period will be returned. The following
-table details the relationship between the period’s status and
-the directive status code returned by the``rtems_rate_monotonic_period``
-directive:
-
-- ``RTEMS_SUCCESSFUL`` - period is running
-
-- ``RTEMS_TIMEOUT`` - period has expired
-
-- ``RTEMS_NOT_DEFINED`` - period has never been initiated
-
-Obtaining the status of a rate monotonic period does
-not alter the state or length of that period.
-
-Canceling a Period
-------------------
-
-The ``rtems_rate_monotonic_cancel`` directive is used to stop
-the period maintained by the specified rate monotonic period.
-The period is stopped and the rate monotonic period can be
-reinitiated using the ``rtems_rate_monotonic_period`` directive.
-
-Deleting a Rate Monotonic Period
---------------------------------
-
-The ``rtems_rate_monotonic_delete`` directive is used to delete
-a rate monotonic period. If the period is running and has not
-expired, the period is automatically canceled. The rate
-monotonic period’s control block is returned to the PCB free
-list when it is deleted. A rate monotonic period can be deleted
-by a task other than the task which created the period.
-
-Examples
---------
-
-The following sections illustrate common uses of rate
-monotonic periods to construct periodic tasks.
-
-Simple Periodic Task
---------------------
-
-This example consists of a single periodic task
-which, after initialization, executes every 100 clock ticks.
-.. code:: c
-
- rtems_task Periodic_task(rtems_task_argument arg)
- {
- rtems_name name;
- rtems_id period;
- rtems_status_code status;
- name = rtems_build_name( 'P', 'E', 'R', 'D' );
- status = rtems_rate_monotonic_create( name, &period );
- if ( status != RTEMS_STATUS_SUCCESSFUL ) {
- printf( "rtems_monotonic_create failed with status of %d.\\n", rc );
- exit( 1 );
- }
- while ( 1 ) {
- if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT )
- break;
- /* Perform some periodic actions \*/
- }
- /* missed period so delete period and SELF \*/
- status = rtems_rate_monotonic_delete( period );
- if ( status != RTEMS_STATUS_SUCCESSFUL ) {
- printf( "rtems_rate_monotonic_delete failed with status of %d.\\n", status );
- exit( 1 );
- }
- status = rtems_task_delete( SELF ); /* should not return \*/
- printf( "rtems_task_delete returned with status of %d.\\n", status );
- exit( 1 );
- }
-
-The above task creates a rate monotonic period as
-part of its initialization. The first time the loop is
-executed, the ``rtems_rate_monotonic_period``
-directive will initiate the period for 100 ticks and return
-immediately. Subsequent invocations of the``rtems_rate_monotonic_period`` directive will result
-in the task blocking for the remainder of the 100 tick period.
-If, for any reason, the body of the loop takes more than 100
-ticks to execute, the ``rtems_rate_monotonic_period``
-directive will return the ``RTEMS_TIMEOUT`` status.
-If the above task misses its deadline, it will delete the rate
-monotonic period and itself.
-
-Task with Multiple Periods
---------------------------
-
-This example consists of a single periodic task
-which, after initialization, performs two sets of actions every
-100 clock ticks. The first set of actions is performed in the
-first forty clock ticks of every 100 clock ticks, while the
-second set of actions is performed between the fortieth and
-seventieth clock ticks. The last thirty clock ticks are not
-used by this task.
-.. code:: c
-
- rtems_task Periodic_task(rtems_task_argument arg)
- {
- rtems_name name_1, name_2;
- rtems_id period_1, period_2;
- rtems_status_code status;
- name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
- name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
- (void ) rtems_rate_monotonic_create( name_1, &period_1 );
- (void ) rtems_rate_monotonic_create( name_2, &period_2 );
- while ( 1 ) {
- if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
- break;
- if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
- break;
- /*
- * Perform first set of actions between clock
- * ticks 0 and 39 of every 100 ticks.
- \*/
- if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT )
- break;
- /*
- * Perform second set of actions between clock 40 and 69
- * of every 100 ticks. THEN ...
- *
- * Check to make sure we didn't miss the period_2 period.
- \*/
- if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
- break;
- (void) rtems_rate_monotonic_cancel( period_2 );
- }
- /* missed period so delete period and SELF \*/
- (void ) rtems_rate_monotonic_delete( period_1 );
- (void ) rtems_rate_monotonic_delete( period_2 );
- (void ) task_delete( SELF );
- }
-
-The above task creates two rate monotonic periods as
-part of its initialization. The first time the loop is
-executed, the ``rtems_rate_monotonic_period``
-directive will initiate the period_1 period for 100 ticks
-and return immediately. Subsequent invocations of the``rtems_rate_monotonic_period`` directive
-for period_1 will result in the task blocking for the remainder
-of the 100 tick period. The period_2 period is used to control
-the execution time of the two sets of actions within each 100
-tick period established by period_1. The``rtems_rate_monotonic_cancel( period_2 )``
-call is performed to ensure that the period_2 period
-does not expire while the task is blocked on the period_1
-period. If this cancel operation were not performed, every time
-the ``rtems_rate_monotonic_period( period_2, 40 )``
-call is executed, except for the initial one, a directive status
-of ``RTEMS_TIMEOUT`` is returned. It is important to
-note that every time this call is made, the period_2 period will be
-initiated immediately and the task will not block.
-
-If, for any reason, the task misses any deadline, the``rtems_rate_monotonic_period`` directive will
-return the ``RTEMS_TIMEOUT``
-directive status. If the above task misses its deadline, it
-will delete the rate monotonic periods and itself.
-
-Directives
-==========
-
-This section details the rate monotonic manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-RATE_MONOTONIC_CREATE - Create a rate monotonic period
-------------------------------------------------------
-.. index:: create a period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_create
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_create(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - rate monotonic period created successfully
-``RTEMS_INVALID_NAME`` - invalid period name
-``RTEMS_TOO_MANY`` - too many periods created
-
-**DESCRIPTION:**
-
-This directive creates a rate monotonic period. The
-assigned rate monotonic id is returned in id. This id is used
-to access the period with other rate monotonic manager
-directives. For control and maintenance of the rate monotonic
-period, RTEMS allocates a PCB from the local PCB free pool and
-initializes it.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-RATE_MONOTONIC_IDENT - Get ID of a period
------------------------------------------
-.. index:: get ID of a period
-.. index:: obtain ID of a period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_ident
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period identified successfully
-``RTEMS_INVALID_NAME`` - period name not found
-
-**DESCRIPTION:**
-
-This directive obtains the period id associated with
-the period name to be acquired. If the period name is not
-unique, then the period id will match one of the periods with
-that name. However, this period id is not guaranteed to
-correspond to the desired period. The period id is used to
-access this period in other rate monotonic manager directives.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-RATE_MONOTONIC_CANCEL - Cancel a period
----------------------------------------
-.. index:: cancel a period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_cancel
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_cancel(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period canceled successfully
-``RTEMS_INVALID_ID`` - invalid rate monotonic period id
-``RTEMS_NOT_OWNER_OF_RESOURCE`` - rate monotonic period not created by calling task
-
-**DESCRIPTION:**
-
-This directive cancels the rate monotonic period id.
-This period will be reinitiated by the next invocation of``rtems_rate_monotonic_period`` with id.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-The rate monotonic period specified by id must have
-been created by the calling task.
-
-RATE_MONOTONIC_DELETE - Delete a rate monotonic period
-------------------------------------------------------
-.. index:: delete a period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_delete
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period deleted successfully
-``RTEMS_INVALID_ID`` - invalid rate monotonic period id
-
-**DESCRIPTION:**
-
-This directive deletes the rate monotonic period
-specified by id. If the period is running, it is automatically
-canceled. The PCB for the deleted period is reclaimed by RTEMS.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-A rate monotonic period can be deleted by a task
-other than the task which created the period.
-
-RATE_MONOTONIC_PERIOD - Conclude current/Start next period
-----------------------------------------------------------
-.. index:: conclude current period
-.. index:: start current period
-.. index:: period initiation
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_period
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_period(
- rtems_id id,
- rtems_interval length
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period initiated successfully
-``RTEMS_INVALID_ID`` - invalid rate monotonic period id
-``RTEMS_NOT_OWNER_OF_RESOURCE`` - period not created by calling task
-``RTEMS_NOT_DEFINED`` - period has never been initiated (only
-possible when period is set to PERIOD_STATUS)
-``RTEMS_TIMEOUT`` - period has expired
-
-**DESCRIPTION:**
-
-This directive initiates the rate monotonic period id
-with a length of period ticks. If id is running, then the
-calling task will block for the remainder of the period before
-reinitiating the period with the specified period. If id was
-not running (either expired or never initiated), the period is
-immediately initiated and the directive returns immediately.
-
-If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the
-current state of id will be returned. The directive status
-indicates the current state of the period. This does not alter
-the state or period of the period.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-RATE_MONOTONIC_GET_STATUS - Obtain status from a period
--------------------------------------------------------
-.. index:: get status of period
-.. index:: obtain status of period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_get_status
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_get_status(
- rtems_id id,
- rtems_rate_monotonic_period_status \*status
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period initiated successfully
-``RTEMS_INVALID_ID`` - invalid rate monotonic period id
-``RTEMS_INVALID_ADDRESS`` - invalid address of status
-
-**DESCRIPTION:**
-
-This directive returns status information associated with
-the rate monotonic period id in the following data structure:.. index:: rtems_rate_monotonic_period_status
-
-.. code:: c
-
- typedef struct {
- rtems_id owner;
- rtems_rate_monotonic_period_states state;
- rtems_rate_monotonic_period_time_t since_last_period;
- rtems_thread_cpu_usage_t executed_since_last_period;
- } rtems_rate_monotonic_period_status;
-
-.. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
-
-A configure time option can be used to select whether the time information is
-given in ticks or seconds and nanoseconds. The default is seconds and
-nanoseconds. If the period’s state is ``RATE_MONOTONIC_INACTIVE``, both
-time values will be set to 0. Otherwise, both time values will contain
-time information since the last invocation of the``rtems_rate_monotonic_period`` directive. More
-specifically, the ticks_since_last_period value contains the elapsed time
-which has occurred since the last invocation of the``rtems_rate_monotonic_period`` directive and the
-ticks_executed_since_last_period contains how much processor time the
-owning task has consumed since the invocation of the``rtems_rate_monotonic_period`` directive.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
----------------------------------------------------------------
-.. index:: get statistics of period
-.. index:: obtain statistics of period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_get_statistics
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_get_statistics(
- rtems_id id,
- rtems_rate_monotonic_period_statistics \*statistics
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period initiated successfully
-``RTEMS_INVALID_ID`` - invalid rate monotonic period id
-``RTEMS_INVALID_ADDRESS`` - invalid address of statistics
-
-**DESCRIPTION:**
-
-This directive returns statistics information associated with
-the rate monotonic period id in the following data structure:.. index:: rtems_rate_monotonic_period_statistics
-
-.. code:: c
-
- typedef struct {
- uint32_t count;
- uint32_t missed_count;
- #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
- struct timespec min_cpu_time;
- struct timespec max_cpu_time;
- struct timespec total_cpu_time;
- #else
- uint32_t min_cpu_time;
- uint32_t max_cpu_time;
- uint32_t total_cpu_time;
- #endif
- #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
- struct timespec min_wall_time;
- struct timespec max_wall_time;
- struct timespec total_wall_time;
- #else
- uint32_t min_wall_time;
- uint32_t max_wall_time;
- uint32_t total_wall_time;
- #endif
- } rtems_rate_monotonic_period_statistics;
-
-This directive returns the current statistics information for
-the period instance assocaited with ``id``. The information
-returned is indicated by the structure above.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
----------------------------------------------------------------
-.. index:: reset statistics of period
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_reset_statistics
-
-.. code:: c
-
- rtems_status_code rtems_rate_monotonic_reset_statistics(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - period initiated successfully
-``RTEMS_INVALID_ID`` - invalid rate monotonic period id
-
-**DESCRIPTION:**
-
-This directive resets the statistics information associated with
-this rate monotonic period instance.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
-----------------------------------------------------------------------
-.. index:: reset statistics of all periods
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_reset_all_statistics
-
-.. code:: c
-
- void rtems_rate_monotonic_reset_all_statistics(void);
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive resets the statistics information associated with
-all rate monotonic period instances.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
------------------------------------------------------------------
-.. index:: print period statistics report
-.. index:: period statistics report
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_rate_monotonic_report_statistics
-
-.. code:: c
-
- void rtems_rate_monotonic_report_statistics(void);
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive prints a report on all active periods which have
-executed at least one period. The following is an example of the
-output generated by this directive... index:: rtems_rate_monotonic_period_statistics
-
-.. code:: c
-
- ID OWNER PERIODS MISSED CPU TIME WALL TIME
- MIN/MAX/AVG MIN/MAX/AVG
- 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00
- 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00
- 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00
- 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00
- 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-.. COMMENT: COPYRIGHT (c) 1988-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Semaphore Manager
-#################
-
-.. index:: semaphores
-.. index:: binary semaphores
-.. index:: counting semaphores
-.. index:: mutual exclusion
-
-Introduction
-============
-
-The semaphore manager utilizes standard Dijkstra
-counting semaphores to provide synchronization and mutual
-exclusion capabilities. The directives provided by the
-semaphore manager are:
-
-- ``rtems_semaphore_create`` - Create a semaphore
-
-- ``rtems_semaphore_ident`` - Get ID of a semaphore
-
-- ``rtems_semaphore_delete`` - Delete a semaphore
-
-- ``rtems_semaphore_obtain`` - Acquire a semaphore
-
-- ``rtems_semaphore_release`` - Release a semaphore
-
-- ``rtems_semaphore_flush`` - Unblock all tasks waiting on a semaphore
-
-- ``rtems_semaphore_set_priority`` - Set priority by
- scheduler for a semaphore
-
-Background
-==========
-
-A semaphore can be viewed as a protected variable
-whose value can be modified only with the``rtems_semaphore_create``,``rtems_semaphore_obtain``, and``rtems_semaphore_release`` directives. RTEMS
-supports both binary and counting semaphores. A binary semaphore
-is restricted to values of zero or one, while a counting
-semaphore can assume any non-negative integer value.
-
-A binary semaphore can be used to control access to a
-single resource. In particular, it can be used to enforce
-mutual exclusion for a critical section in user code. In this
-instance, the semaphore would be created with an initial count
-of one to indicate that no task is executing the critical
-section of code. Upon entry to the critical section, a task
-must issue the ``rtems_semaphore_obtain``
-directive to prevent other tasks from entering the critical section.
-Upon exit from the critical section, the task must issue the``rtems_semaphore_release`` directive to
-allow another task to execute the critical section.
-
-A counting semaphore can be used to control access to
-a pool of two or more resources. For example, access to three
-printers could be administered by a semaphore created with an
-initial count of three. When a task requires access to one of
-the printers, it issues the ``rtems_semaphore_obtain``
-directive to obtain access to a printer. If a printer is not currently
-available, the task can wait for a printer to become available or return
-immediately. When the task has completed printing, it should
-issue the ``rtems_semaphore_release``
-directive to allow other tasks access to the printer.
-
-Task synchronization may be achieved by creating a
-semaphore with an initial count of zero. One task waits for the
-arrival of another task by issuing a ``rtems_semaphore_obtain``
-directive when it reaches a synchronization point. The other task
-performs a corresponding ``rtems_semaphore_release``
-operation when it reaches its synchronization point, thus unblocking
-the pending task.
-
-Nested Resource Access
-----------------------
-
-Deadlock occurs when a task owning a binary semaphore
-attempts to acquire that same semaphore and blocks as result.
-Since the semaphore is allocated to a task, it cannot be
-deleted. Therefore, the task that currently holds the semaphore
-and is also blocked waiting for that semaphore will never
-execute again.
-
-RTEMS addresses this problem by allowing the task
-holding the binary semaphore to obtain the same binary semaphore
-multiple times in a nested manner. Each``rtems_semaphore_obtain`` must be accompanied with a``rtems_semaphore_release``. The semaphore will
-only be made available for acquisition by other tasks when the
-outermost ``rtems_semaphore_obtain`` is matched with
-a ``rtems_semaphore_release``.
-
-Simple binary semaphores do not allow nested access and so can be used for task synchronization.
-
-Priority Inversion
-------------------
-
-Priority inversion is a form of indefinite
-postponement which is common in multitasking, preemptive
-executives with shared resources. Priority inversion occurs
-when a high priority tasks requests access to shared resource
-which is currently allocated to low priority task. The high
-priority task must block until the low priority task releases
-the resource. This problem is exacerbated when the low priority
-task is prevented from executing by one or more medium priority
-tasks. Because the low priority task is not executing, it
-cannot complete its interaction with the resource and release
-that resource. The high priority task is effectively prevented
-from executing by lower priority tasks.
-
-
-Priority Inheritance
---------------------
-
-Priority inheritance is an algorithm that calls for
-the lower priority task holding a resource to have its priority
-increased to that of the highest priority task blocked waiting
-for that resource. Each time a task blocks attempting to obtain
-the resource, the task holding the resource may have its
-priority increased.
-
-On SMP configurations, in case the task holding the resource and the task that
-blocks attempting to obtain the resource are in different scheduler instances,
-the priority of the holder is raised to the pseudo-interrupt priority (priority
-boosting). The pseudo-interrupt priority is the highest priority.
-
-RTEMS supports priority inheritance for local, binary
-semaphores that use the priority task wait queue blocking
-discipline. When a task of higher priority than the task
-holding the semaphore blocks, the priority of the task holding
-the semaphore is increased to that of the blocking task. When
-the task holding the task completely releases the binary
-semaphore (i.e. not for a nested release), the holder’s priority
-is restored to the value it had before any higher priority was
-inherited.
-
-The RTEMS implementation of the priority inheritance
-algorithm takes into account the scenario in which a task holds
-more than one binary semaphore. The holding task will execute
-at the priority of the higher of the highest ceiling priority or
-at the priority of the highest priority task blocked waiting for
-any of the semaphores the task holds. Only when the task
-releases ALL of the binary semaphores it holds will its priority
-be restored to the normal value.
-
-Priority Ceiling
-----------------
-
-Priority ceiling is an algorithm that calls for the
-lower priority task holding a resource to have its priority
-increased to that of the highest priority task which will EVER
-block waiting for that resource. This algorithm addresses the
-problem of priority inversion although it avoids the possibility
-of changing the priority of the task holding the resource
-multiple times. The priority ceiling algorithm will only change
-the priority of the task holding the resource a maximum of one
-time. The ceiling priority is set at creation time and must be
-the priority of the highest priority task which will ever
-attempt to acquire that semaphore.
-
-RTEMS supports priority ceiling for local, binary
-semaphores that use the priority task wait queue blocking
-discipline. When a task of lower priority than the ceiling
-priority successfully obtains the semaphore, its priority is
-raised to the ceiling priority. When the task holding the task
-completely releases the binary semaphore (i.e. not for a nested
-release), the holder’s priority is restored to the value it had
-before any higher priority was put into effect.
-
-The need to identify the highest priority task which
-will attempt to obtain a particular semaphore can be a difficult
-task in a large, complicated system. Although the priority
-ceiling algorithm is more efficient than the priority
-inheritance algorithm with respect to the maximum number of task
-priority changes which may occur while a task holds a particular
-semaphore, the priority inheritance algorithm is more forgiving
-in that it does not require this apriori information.
-
-The RTEMS implementation of the priority ceiling
-algorithm takes into account the scenario in which a task holds
-more than one binary semaphore. The holding task will execute
-at the priority of the higher of the highest ceiling priority or
-at the priority of the highest priority task blocked waiting for
-any of the semaphores the task holds. Only when the task
-releases ALL of the binary semaphores it holds will its priority
-be restored to the normal value.
-
-
-Multiprocessor Resource Sharing Protocol
-----------------------------------------
-
-The Multiprocessor Resource Sharing Protocol (MrsP) is defined in *A.
-Burns and A.J. Wellings, A Schedulability Compatible Multiprocessor Resource
-Sharing Protocol - MrsP, Proceedings of the 25th Euromicro Conference on
-Real-Time Systems (ECRTS 2013), July 2013*. It is a generalization of the
-Priority Ceiling Protocol to SMP systems. Each MrsP semaphore uses a ceiling
-priority per scheduler instance. These ceiling priorities can be specified
-with ``rtems_semaphore_set_priority()``. A task obtaining or owning a MrsP
-semaphore will execute with the ceiling priority for its scheduler instance as
-specified by the MrsP semaphore object. Tasks waiting to get ownership of a
-MrsP semaphore will not relinquish the processor voluntarily. In case the
-owner of a MrsP semaphore gets preempted it can ask all tasks waiting for this
-semaphore to help out and temporarily borrow the right to execute on one of
-their assigned processors.
-
-Building a Semaphore Attribute Set
-----------------------------------
-
-In general, an attribute set is built by a bitwise OR
-of the desired attribute components. The following table lists
-the set of valid semaphore attributes:
-
-- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
-
-- ``RTEMS_PRIORITY`` - tasks wait by priority
-
-- ``RTEMS_BINARY_SEMAPHORE`` - restrict values to
- 0 and 1
-
-- ``RTEMS_COUNTING_SEMAPHORE`` - no restriction on values
- (default)
-
-- ``RTEMS_SIMPLE_BINARY_SEMAPHORE`` - restrict values to
- 0 and 1, do not allow nested access, allow deletion of locked semaphore.
-
-- ``RTEMS_NO_INHERIT_PRIORITY`` - do not use priority
- inheritance (default)
-
-- ``RTEMS_INHERIT_PRIORITY`` - use priority inheritance
-
-- ``RTEMS_NO_PRIORITY_CEILING`` - do not use priority
- ceiling (default)
-
-- ``RTEMS_PRIORITY_CEILING`` - use priority ceiling
-
-- ``RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING`` - do not use
- Multiprocessor Resource Sharing Protocol (default)
-
-- ``RTEMS_MULTIPROCESSOR_RESOURCE_SHARING`` - use
- Multiprocessor Resource Sharing Protocol
-
-- ``RTEMS_LOCAL`` - local semaphore (default)
-
-- ``RTEMS_GLOBAL`` - global semaphore
-
-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. An attribute listed as a default is not
-required to appear in the attribute list, although it is a good
-programming practice to specify default attributes. If all
-defaults are desired, the attribute``RTEMS_DEFAULT_ATTRIBUTES`` should be
-specified on this call.
-
-This example demonstrates the attribute_set parameter needed to create a
-local semaphore with the task priority waiting queue discipline. The
-attribute_set parameter passed to the``rtems_semaphore_create`` directive could be either``RTEMS_PRIORITY`` or ``RTEMS_LOCAL |
-RTEMS_PRIORITY``. The attribute_set parameter can be set to``RTEMS_PRIORITY`` because ``RTEMS_LOCAL`` is the
-default for all created tasks. If a similar semaphore were to be known
-globally, then the attribute_set parameter would be``RTEMS_GLOBAL | RTEMS_PRIORITY``.
-
-Some combinatinos of these attributes are invalid. For example, priority
-ordered blocking discipline must be applied to a binary semaphore in order
-to use either the priority inheritance or priority ceiling functionality.
-The following tree figure illustrates the valid combinations.
-
-.. code:: c
-
- Not available in ASCII representation
-
-Building a SEMAPHORE_OBTAIN Option Set
---------------------------------------
-
-In general, an option is built by a bitwise OR of the
-desired option components. The set of valid options for the``rtems_semaphore_obtain`` directive are listed
-in the following table:
-
-- ``RTEMS_WAIT`` - task will wait for semaphore (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-Option 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. An option
-listed as a default is not required to appear in the list, although it is
-a good programming practice to specify default options. If all defaults
-are desired, the option ``RTEMS_DEFAULT_OPTIONS`` should be
-specified on this call.
-
-This example demonstrates the option parameter needed
-to poll for a semaphore. The option parameter passed to the``rtems_semaphore_obtain``
-directive should be ``RTEMS_NO_WAIT``.
-
-Operations
-==========
-
-Creating a Semaphore
---------------------
-
-The ``rtems_semaphore_create`` directive creates a binary or
-counting semaphore with a user-specified name as well as an
-initial count. If a binary semaphore is created with a count of
-zero (0) to indicate that it has been allocated, then the task
-creating the semaphore is considered the current holder of the
-semaphore. At create time the method for ordering waiting tasks
-in the semaphore’s task wait queue (by FIFO or task priority) is
-specified. Additionally, the priority inheritance or priority
-ceiling algorithm may be selected for local, binary semaphores
-that use the priority task wait queue blocking discipline. If
-the priority ceiling algorithm is selected, then the highest
-priority of any task which will attempt to obtain this semaphore
-must be specified. RTEMS allocates a Semaphore Control Block
-(SMCB) from the SMCB free list. This data structure is used by
-RTEMS to manage the newly created semaphore. Also, a unique
-semaphore ID is generated and returned to the calling task.
-
-Obtaining Semaphore IDs
------------------------
-
-When a semaphore is created, RTEMS generates a unique
-semaphore ID and assigns it to the created semaphore until it is
-deleted. The semaphore ID may be obtained by either of two
-methods. First, as the result of an invocation of the``rtems_semaphore_create`` directive, the
-semaphore ID is stored in a user provided location. Second,
-the semaphore ID may be obtained later using the``rtems_semaphore_ident`` directive. The semaphore ID is
-used by other semaphore manager directives to access this
-semaphore.
-
-Acquiring a Semaphore
----------------------
-
-The ``rtems_semaphore_obtain`` directive is used to acquire the
-specified semaphore. A simplified version of the``rtems_semaphore_obtain`` directive can be described as follows:
-.. code:: c
-
- if semaphore's count is greater than zero
- then decrement semaphore's count
- else wait for release of semaphore
- return SUCCESSFUL
-
-When the semaphore cannot be immediately acquired,
-one of the following situations applies:
-
-- By default, the calling task will wait forever to
- acquire the semaphore.
-
-- Specifying ``RTEMS_NO_WAIT`` forces an immediate return
- with an error status code.
-
-- Specifying a timeout limits the interval the task will
- wait before returning with an error status code.
-
-If the task waits to acquire the semaphore, then it
-is placed in the semaphore’s task wait queue in either FIFO or
-task priority order. If the task blocked waiting for a binary
-semaphore using priority inheritance and the task’s priority is
-greater than that of the task currently holding the semaphore,
-then the holding task will inherit the priority of the blocking
-task. All tasks waiting on a semaphore are returned an error
-code when the semaphore is deleted.
-
-When a task successfully obtains a semaphore using
-priority ceiling and the priority ceiling for this semaphore is
-greater than that of the holder, then the holder’s priority will
-be elevated.
-
-Releasing a Semaphore
----------------------
-
-The ``rtems_semaphore_release`` directive is used to release
-the specified semaphore. A simplified version of the``rtems_semaphore_release`` directive can be described as
-follows:
-.. code:: c
-
- if no tasks are waiting on this semaphore
- then increment semaphore's count
- else assign semaphore to a waiting task
- return SUCCESSFUL
-
-If this is the outermost release of a binary
-semaphore that uses priority inheritance or priority ceiling and
-the task does not currently hold any other binary semaphores,
-then the task performing the ``rtems_semaphore_release``
-will have its priority restored to its normal value.
-
-Deleting a Semaphore
---------------------
-
-The ``rtems_semaphore_delete`` directive removes a semaphore
-from the system and frees its control block. A semaphore can be
-deleted by any local task that knows the semaphore’s ID. As a
-result of this directive, all tasks blocked waiting to acquire
-the semaphore will be readied and returned a status code which
-indicates that the semaphore was deleted. Any subsequent
-references to the semaphore’s name and ID are invalid.
-
-Directives
-==========
-
-This section details the semaphore manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-SEMAPHORE_CREATE - Create a semaphore
--------------------------------------
-.. index:: create a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_create
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_create(
- rtems_name name,
- uint32_t count,
- rtems_attribute attribute_set,
- rtems_task_priority priority_ceiling,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - semaphore created successfully
-``RTEMS_INVALID_NAME`` - invalid semaphore name
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_TOO_MANY`` - too many semaphores created
-``RTEMS_NOT_DEFINED`` - invalid attribute set
-``RTEMS_INVALID_NUMBER`` - invalid starting count for binary semaphore
-``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured
-``RTEMS_TOO_MANY`` - too many global objects
-
-**DESCRIPTION:**
-
-This directive creates a semaphore which resides on
-the local node. The created semaphore has the user-defined name
-specified in name and the initial count specified in count. For
-control and maintenance of the semaphore, RTEMS allocates and
-initializes a SMCB. The RTEMS-assigned semaphore id is returned
-in id. This semaphore id is used with other semaphore related
-directives to access the semaphore.
-
-Specifying PRIORITY in attribute_set causes tasks
-waiting for a semaphore to be serviced according to task
-priority. When FIFO is selected, tasks are serviced in First
-In-First Out order.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The priority inheritance and priority ceiling
-algorithms are only supported for local, binary semaphores that
-use the priority task wait queue blocking discipline.
-
-The following semaphore attribute constants are
-defined by RTEMS:
-
-- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
-
-- ``RTEMS_PRIORITY`` - tasks wait by priority
-
-- ``RTEMS_BINARY_SEMAPHORE`` - restrict values to
- 0 and 1
-
-- ``RTEMS_COUNTING_SEMAPHORE`` - no restriction on values
- (default)
-
-- ``RTEMS_SIMPLE_BINARY_SEMAPHORE`` - restrict values to
- 0 and 1, block on nested access, allow deletion of locked semaphore.
-
-- ``RTEMS_NO_INHERIT_PRIORITY`` - do not use priority
- inheritance (default)
-
-- ``RTEMS_INHERIT_PRIORITY`` - use priority inheritance
-
-- ``RTEMS_NO_PRIORITY_CEILING`` - do not use priority
- ceiling (default)
-
-- ``RTEMS_PRIORITY_CEILING`` - use priority ceiling
-
-- ``RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING`` - do not use
- Multiprocessor Resource Sharing Protocol (default)
-
-- ``RTEMS_MULTIPROCESSOR_RESOURCE_SHARING`` - use
- Multiprocessor Resource Sharing Protocol
-
-- ``RTEMS_LOCAL`` - local semaphore (default)
-
-- ``RTEMS_GLOBAL`` - global semaphore
-
-Semaphores should not be made global unless remote
-tasks must interact with the created semaphore. This is to
-avoid the system overhead incurred by the creation of a global
-semaphore. When a global semaphore is created, the semaphore’s
-name and id must be transmitted to every node in the system for
-insertion in the local copy of the global object table.
-
-Note that some combinations of attributes are not valid. See the
-earlier discussion on this.
-
-The total number of global objects, including semaphores, is limited by
-the maximum_global_objects field in the Configuration Table.
-
-It is not allowed to create an initially locked MrsP semaphore and the``RTEMS_INVALID_NUMBER`` status code will be returned on SMP
-configurations in this case. This prevents lock order reversal problems with
-the allocator mutex.
-
-SEMAPHORE_IDENT - Get ID of a semaphore
----------------------------------------
-.. index:: get ID of a semaphore
-.. index:: obtain ID of a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_ident
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_ident(
- rtems_name name,
- uint32_t node,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - semaphore identified successfully
-``RTEMS_INVALID_NAME`` - semaphore name not found
-``RTEMS_INVALID_NODE`` - invalid node id
-
-**DESCRIPTION:**
-
-This directive obtains the semaphore id associated
-with the semaphore name. If the semaphore name is not unique,
-then the semaphore id will match one of the semaphores with that
-name. However, this semaphore id is not guaranteed to
-correspond to the desired semaphore. The semaphore id is used
-by other semaphore related directives to access the semaphore.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched
-with the local node being searched first. All other nodes are
-searched with the lowest numbered node searched first.
-
-If node is a valid node number which does not
-represent the local node, then only the semaphores exported by
-the designated node are searched.
-
-This directive does not generate activity on remote
-nodes. It accesses only the local copy of the global object
-table.
-
-SEMAPHORE_DELETE - Delete a semaphore
--------------------------------------
-.. index:: delete a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_delete
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - semaphore deleted successfully
-``RTEMS_INVALID_ID`` - invalid semaphore id
-``RTEMS_RESOURCE_IN_USE`` - binary semaphore is in use
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote semaphore
-
-**DESCRIPTION:**
-
-This directive deletes the semaphore specified by ``id``.
-All tasks blocked waiting to acquire the semaphore will be
-readied and returned a status code which indicates that the
-semaphore was deleted. The SMCB for this semaphore is reclaimed
-by RTEMS.
-
-**NOTES:**
-
-The calling task will be preempted if it is enabled
-by the task’s execution mode and a higher priority local task is
-waiting on the deleted semaphore. The calling task will NOT be
-preempted if all of the tasks that are waiting on the semaphore
-are remote tasks.
-
-The calling task does not have to be the task that
-created the semaphore. Any local task that knows the semaphore
-id can delete the semaphore.
-
-When a global semaphore is deleted, the semaphore id
-must be transmitted to every node in the system for deletion
-from the local copy of the global object table.
-
-The semaphore must reside on the local node, even if
-the semaphore was created with the ``RTEMS_GLOBAL`` option.
-
-Proxies, used to represent remote tasks, are
-reclaimed when the semaphore is deleted.
-
-SEMAPHORE_OBTAIN - Acquire a semaphore
---------------------------------------
-.. index:: obtain a semaphore
-.. index:: lock a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_obtain
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_obtain(
- rtems_id id,
- rtems_option option_set,
- rtems_interval timeout
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - semaphore obtained successfully
-``RTEMS_UNSATISFIED`` - semaphore not available
-``RTEMS_TIMEOUT`` - timed out waiting for semaphore
-``RTEMS_OBJECT_WAS_DELETED`` - semaphore deleted while waiting
-``RTEMS_INVALID_ID`` - invalid semaphore id
-
-**DESCRIPTION:**
-
-This directive acquires the semaphore specified by
-id. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter
-indicate whether the calling task wants to wait for the
-semaphore to become available or return immediately if the
-semaphore is not currently available. With either ``RTEMS_WAIT`` or``RTEMS_NO_WAIT``, if the current semaphore count is positive, then it is
-decremented by one and the semaphore is successfully acquired by
-returning immediately with a successful return code.
-
-If the calling task chooses to return immediately and the current
-semaphore count is zero or negative, then a status code is returned
-indicating that the semaphore is not available. If the calling task
-chooses to wait for a semaphore and the current semaphore count is zero or
-negative, then it is decremented by one and the calling task is placed on
-the semaphore’s wait queue and blocked. If the semaphore was created with
-the ``RTEMS_PRIORITY`` attribute, then the calling task is
-inserted into the queue according to its priority. However, if the
-semaphore was created with the ``RTEMS_FIFO`` attribute, then
-the calling task is placed at the rear of the wait queue. If the binary
-semaphore was created with the ``RTEMS_INHERIT_PRIORITY``
-attribute, then the priority of the task currently holding the binary
-semaphore is guaranteed to be greater than or equal to that of the
-blocking task. If the binary semaphore was created with the``RTEMS_PRIORITY_CEILING`` attribute, a task successfully
-obtains the semaphore, and the priority of that task is greater than the
-ceiling priority for this semaphore, then the priority of the task
-obtaining the semaphore is elevated to that of the ceiling.
-
-The timeout parameter specifies the maximum interval the calling task is
-willing to be blocked waiting for the semaphore. If it is set to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
-If the semaphore is available or the ``RTEMS_NO_WAIT`` option
-component is set, then timeout is ignored.
-
-Deadlock situations are detected for MrsP semaphores and the``RTEMS_UNSATISFIED`` status code will be returned on SMP
-configurations in this case.
-
-**NOTES:**
-
-The following semaphore acquisition option constants
-are defined by RTEMS:
-
-- ``RTEMS_WAIT`` - task will wait for semaphore (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-Attempting to obtain a global semaphore which does not reside on the local
-node will generate a request to the remote node to access the semaphore.
-If the semaphore is not available and ``RTEMS_NO_WAIT`` was
-not specified, then the task must be blocked until the semaphore is
-released. A proxy is allocated on the remote node to represent the task
-until the semaphore is released.
-
-A clock tick is required to support the timeout functionality of
-this directive.
-
-It is not allowed to obtain a MrsP semaphore more than once by one task at a
-time (nested access) and the ``RTEMS_UNSATISFIED`` status code will
-be returned on SMP configurations in this case.
-
-SEMAPHORE_RELEASE - Release a semaphore
----------------------------------------
-.. index:: release a semaphore
-.. index:: unlock a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_release
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_release(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - semaphore released successfully
-``RTEMS_INVALID_ID`` - invalid semaphore id
-``RTEMS_NOT_OWNER_OF_RESOURCE`` - calling task does not own semaphore
-``RTEMS_INCORRECT_STATE`` - invalid unlock order
-
-**DESCRIPTION:**
-
-This directive releases the semaphore specified by
-id. The semaphore count is incremented by one. If the count is
-zero or negative, then the first task on this semaphore’s wait
-queue is removed and unblocked. The unblocked task may preempt
-the running task if the running task’s preemption mode is
-enabled and the unblocked task has a higher priority than the
-running task.
-
-**NOTES:**
-
-The calling task may be preempted if it causes a
-higher priority task to be made ready for execution.
-
-Releasing a global semaphore which does not reside on
-the local node will generate a request telling the remote node
-to release the semaphore.
-
-If the task to be unblocked resides on a different
-node from the semaphore, then the semaphore allocation is
-forwarded to the appropriate node, the waiting task is
-unblocked, and the proxy used to represent the task is reclaimed.
-
-The outermost release of a local, binary, priority
-inheritance or priority ceiling semaphore may result in the
-calling task having its priority lowered. This will occur if
-the calling task holds no other binary semaphores and it has
-inherited a higher priority.
-
-The MrsP semaphores must be released in the reversed obtain order, otherwise
-the ``RTEMS_INCORRECT_STATE`` status code will be returned on SMP
-configurations in this case.
-
-SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
-----------------------------------------------------------
-.. index:: flush a semaphore
-.. index:: unblock all tasks waiting on a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_flush
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_flush(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - semaphore released successfully
-``RTEMS_INVALID_ID`` - invalid semaphore id
-``RTEMS_NOT_DEFINED`` - operation not defined for the protocol of
-the semaphore
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported for remote semaphores
-
-**DESCRIPTION:**
-
-This directive unblocks all tasks waiting on the semaphore specified by
-id. Since there are tasks blocked on the semaphore, the semaphore’s
-count is not changed by this directive and thus is zero before and
-after this directive is executed. Tasks which are unblocked as the
-result of this directive will return from the``rtems_semaphore_obtain`` directive with a
-status code of ``RTEMS_UNSATISFIED`` to indicate
-that the semaphore was not obtained.
-
-This directive may unblock any number of tasks. Any of the unblocked
-tasks may preempt the running task if the running task’s preemption mode is
-enabled and an unblocked task has a higher priority than the
-running task.
-
-**NOTES:**
-
-The calling task may be preempted if it causes a
-higher priority task to be made ready for execution.
-
-If the task to be unblocked resides on a different
-node from the semaphore, then the waiting task is
-unblocked, and the proxy used to represent the task is reclaimed.
-
-It is not allowed to flush a MrsP semaphore and the``RTEMS_NOT_DEFINED`` status code will be returned on SMP
-configurations in this case.
-
-SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore
-------------------------------------------------------------------
-.. index:: set priority by scheduler for a semaphore
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_semaphore_set_priority
-
-.. code:: c
-
- rtems_status_code rtems_semaphore_set_priority(
- rtems_id semaphore_id,
- rtems_id scheduler_id,
- rtems_task_priority new_priority,
- rtems_task_priority \*old_priority
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ID`` - invalid semaphore or scheduler id
-``RTEMS_INVALID_ADDRESS`` - ``old_priority`` is NULL
-``RTEMS_INVALID_PRIORITY`` - invalid new priority value
-``RTEMS_NOT_DEFINED`` - operation not defined for the protocol of
-the semaphore
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported for remote semaphores
-
-**DESCRIPTION:**
-
-This directive sets the priority value with respect to the specified scheduler
-of a semaphore.
-
-The special priority value ``RTEMS_CURRENT_PRIORITY`` can be used to get the
-current priority value without changing it.
-
-The interpretation of the priority value depends on the protocol of the
-semaphore object.
-
-- The Multiprocessor Resource Sharing Protocol needs a ceiling priority per
- scheduler instance. This operation can be used to specify these priority
- values.
-
-- For the Priority Ceiling Protocol the ceiling priority is used with this
- operation.
-
-- For other protocols this operation is not defined.
-
-**EXAMPLE:**
-
-.. code:: c
-
- #include <assert.h>
- #include <stdlib.h>
- #include <rtems.h>
- #define SCHED_A rtems_build_name(' ', ' ', ' ', 'A')
- #define SCHED_B rtems_build_name(' ', ' ', ' ', 'B')
- static void Init(rtems_task_argument arg)
- {
- rtems_status_code sc;
- rtems_id semaphore_id;
- rtems_id scheduler_a_id;
- rtems_id scheduler_b_id;
- rtems_task_priority prio;
- /* Get the scheduler identifiers \*/
- sc = rtems_scheduler_ident(SCHED_A, &scheduler_a_id);
- assert(sc == RTEMS_SUCCESSFUL);
- sc = rtems_scheduler_ident(SCHED_B, &scheduler_b_id);
- assert(sc == RTEMS_SUCCESSFUL);
- /* Create a MrsP semaphore object \*/
- sc = rtems_semaphore_create(
- rtems_build_name('M', 'R', 'S', 'P'),
- 1,
- RTEMS_MULTIPROCESSOR_RESOURCE_SHARING
- | RTEMS_BINARY_SEMAPHORE,
- 1,
- &semaphore_id
- );
- assert(sc == RTEMS_SUCCESSFUL);
- /*
- * The ceiling priority values per scheduler are equal to the value specified
- * for object creation.
- \*/
- prio = RTEMS_CURRENT_PRIORITY;
- sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio);
- assert(sc == RTEMS_SUCCESSFUL);
- assert(prio == 1);
- /* Check the old value and set a new ceiling priority for scheduler B \*/
- prio = 2;
- sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio);
- assert(sc == RTEMS_SUCCESSFUL);
- assert(prio == 1);
- /* Check the ceiling priority values \*/
- prio = RTEMS_CURRENT_PRIORITY;
- sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio);
- assert(sc == RTEMS_SUCCESSFUL);
- assert(prio == 1);
- prio = RTEMS_CURRENT_PRIORITY;
- sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio);
- assert(sc == RTEMS_SUCCESSFUL);
- assert(prio == 2);
- sc = rtems_semaphore_delete(semaphore_id);
- assert(sc == RTEMS_SUCCESSFUL);
- exit(0);
- }
- #define CONFIGURE_SMP_APPLICATION
- #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
- #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
- #define CONFIGURE_MAXIMUM_TASKS 1
- #define CONFIGURE_MAXIMUM_SEMAPHORES 1
- #define CONFIGURE_MAXIMUM_MRSP_SEMAPHORES 1
- #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 2
- #define CONFIGURE_SCHEDULER_SIMPLE_SMP
- #include <rtems/scheduler.h>
- RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(a);
- RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(b);
- #define CONFIGURE_SCHEDULER_CONTROLS \\
- RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(a, SCHED_A), \\
- RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(b, SCHED_B)
- #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \\
- RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY)
- #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
- #define CONFIGURE_INIT
- #include <rtems/confdefs.h>
-
-.. COMMENT: COPYRIGHT (c) 1988-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Barrier Manager
-###############
-
-.. index:: barrier
-
-Introduction
-============
-
-The barrier manager provides a unique synchronization
-capability which can be used to have a set of tasks block
-and be unblocked as a set. The directives provided by the
-barrier manager are:
-
-- ``rtems_barrier_create`` - Create a barrier
-
-- ``rtems_barrier_ident`` - Get ID of a barrier
-
-- ``rtems_barrier_delete`` - Delete a barrier
-
-- ``rtems_barrier_wait`` - Wait at a barrier
-
-- ``rtems_barrier_release`` - Release a barrier
-
-Background
-==========
-
-A barrier can be viewed as a gate at which tasks wait until
-the gate is opened. This has many analogies in the real world.
-Horses and other farm animals may approach a closed gate and
-gather in front of it, waiting for someone to open the gate so
-they may proceed. Similarly, cticket holders gather at the gates
-of arenas before concerts or sporting events waiting for the
-arena personnel to open the gates so they may enter.
-
-Barriers are useful during application initialization. Each
-application task can perform its local initialization before
-waiting for the application as a whole to be initialized. Once
-all tasks have completed their independent initializations,
-the "application ready" barrier can be released.
-
-Automatic Versus Manual Barriers
---------------------------------
-
-Just as with a real-world gate, barriers may be configured to
-be manually opened or automatically opened. All tasks
-calling the ``rtems_barrier_wait`` directive
-will block until a controlling task invokes the``rtems_barrier_release`` directive.
-
-Automatic barriers are created with a limit to the number of
-tasks which may simultaneously block at the barrier. Once
-this limit is reached, all of the tasks are released. For
-example, if the automatic limit is ten tasks, then the first
-nine tasks calling the ``rtems_barrier_wait`` directive
-will block. When the tenth task calls the``rtems_barrier_wait`` directive, the nine
-blocked tasks will be released and the tenth task returns
-to the caller without blocking.
-
-Building a Barrier Attribute Set
---------------------------------
-
-In general, an attribute set is built by a bitwise OR
-of the desired attribute components. The following table lists
-the set of valid barrier attributes:
-
-- ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - automatically
- release the barrier when the configured number of tasks are blocked
-
-- ``RTEMS_BARRIER_MANUAL_RELEASE`` - only release
- the barrier when the application invokes the``rtems_barrier_release`` directive. (default)
-
-*NOTE*: Barriers only support FIFO blocking order because all
-waiting tasks are released as a set. Thus the released tasks
-will all become ready to execute at the same time and compete
-for the processor based upon their priority.
-
-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. An attribute listed as a default is not
-required to appear in the attribute list, although it is a good
-programming practice to specify default attributes. If all
-defaults are desired, the attribute``RTEMS_DEFAULT_ATTRIBUTES`` should be
-specified on this call.
-
-This example demonstrates the attribute_set parameter needed to create a
-barrier with the automatic release policy. The``attribute_set`` parameter passed to the``rtems_barrier_create`` directive will be``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the
-user must also specify the *maximum_waiters* parameter.
-
-Operations
-==========
-
-Creating a Barrier
-------------------
-
-The ``rtems_barrier_create`` directive creates
-a barrier with a user-specified name and the desired attributes.
-RTEMS allocates a Barrier Control Block (BCB) from the BCB free list.
-This data structure is used by RTEMS to manage the newly created
-barrier. Also, a unique barrier ID is generated and returned to
-the calling task.
-
-Obtaining Barrier IDs
----------------------
-
-When a barrier is created, RTEMS generates a unique
-barrier ID and assigns it to the created barrier until it is
-deleted. The barrier ID may be obtained by either of two
-methods. First, as the result of an invocation of the``rtems_barrier_create`` directive, the
-barrier ID is stored in a user provided location. Second,
-the barrier ID may be obtained later using the``rtems_barrier_ident`` directive. The barrier ID is
-used by other barrier manager directives to access this
-barrier.
-
-Waiting at a Barrier
---------------------
-
-The ``rtems_barrier_wait`` directive is used to wait at
-the specified barrier. Since a barrier is, by definition, never immediately,
-the task may wait forever for the barrier to be released or it may
-specify a timeout. Specifying a timeout limits the interval the task will
-wait before returning with an error status code.
-
-If the barrier is configured as automatic and there are already
-one less then the maximum number of waiters, then the call will
-unblock all tasks waiting at the barrier and the caller will
-return immediately.
-
-When the task does wait to acquire the barrier, then it
-is placed in the barrier’s task wait queue in FIFO order.
-All tasks waiting on a barrier are returned an error
-code when the barrier is deleted.
-
-Releasing a Barrier
--------------------
-
-The ``rtems_barrier_release`` directive is used to release
-the specified barrier. When the ``rtems_barrier_release``
-is invoked, all tasks waiting at the barrier are immediately made ready
-to execute and begin to compete for the processor to execute.
-
-Deleting a Barrier
-------------------
-
-The ``rtems_barrier_delete`` directive removes a barrier
-from the system and frees its control block. A barrier can be
-deleted by any local task that knows the barrier’s ID. As a
-result of this directive, all tasks blocked waiting for the
-barrier to be released, will be readied and returned a status code which
-indicates that the barrier was deleted. Any subsequent
-references to the barrier’s name and ID are invalid.
-
-Directives
-==========
-
-This section details the barrier manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-BARRIER_CREATE - Create a barrier
----------------------------------
-.. index:: create a barrier
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_barrier_create
-
-.. code:: c
-
- rtems_status_code rtems_barrier_create(
- rtems_name name,
- rtems_attribute attribute_set,
- uint32_t maximum_waiters,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - barrier created successfully
-``RTEMS_INVALID_NAME`` - invalid barrier name
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_TOO_MANY`` - too many barriers created 
-
-**DESCRIPTION:**
-
-This directive creates a barrier which resides on
-the local node. The created barrier has the user-defined name
-specified in ``name`` and the initial count specified in ``count``. For
-control and maintenance of the barrier, RTEMS allocates and
-initializes a BCB. The RTEMS-assigned barrier id is returned
-in ``id``. This barrier id is used with other barrier related
-directives to access the barrier.
-
-``RTEMS_BARRIER_MANUAL_RELEASE`` - only release
-
-Specifying ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` in``attribute_set`` causes tasks calling the``rtems_barrier_wait`` directive to block until
-there are ``maximum_waiters - 1`` tasks waiting at the barrier.
-When the ``maximum_waiters`` task invokes the``rtems_barrier_wait`` directive, the previous``maximum_waiters - 1`` tasks are automatically released
-and the caller returns.
-
-In contrast, when the ``RTEMS_BARRIER_MANUAL_RELEASE``
-attribute is specified, there is no limit on the number of
-tasks that will block at the barrier. Only when the``rtems_barrier_release`` directive is invoked,
-are the tasks waiting at the barrier unblocked.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-The following barrier attribute constants are defined by RTEMS:
-
-- ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - automatically
- release the barrier when the configured number of tasks are blocked
-
-- ``RTEMS_BARRIER_MANUAL_RELEASE`` - only release
- the barrier when the application invokes the``rtems_barrier_release`` directive. (default)
-
-BARRIER_IDENT - Get ID of a barrier
------------------------------------
-.. index:: get ID of a barrier
-.. index:: obtain ID of a barrier
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_barrier_ident
-
-.. code:: c
-
- rtems_status_code rtems_barrier_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - barrier identified successfully
-``RTEMS_INVALID_NAME`` - barrier name not found
-``RTEMS_INVALID_NODE`` - invalid node id
-
-**DESCRIPTION:**
-
-This directive obtains the barrier id associated
-with the barrier name. If the barrier name is not unique,
-then the barrier id will match one of the barriers with that
-name. However, this barrier id is not guaranteed to
-correspond to the desired barrier. The barrier id is used
-by other barrier related directives to access the barrier.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-BARRIER_DELETE - Delete a barrier
----------------------------------
-.. index:: delete a barrier
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_barrier_delete
-
-.. code:: c
-
- rtems_status_code rtems_barrier_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - barrier deleted successfully
-``RTEMS_INVALID_ID`` - invalid barrier id 
-
-**DESCRIPTION:**
-
-This directive deletes the barrier specified by ``id``.
-All tasks blocked waiting for the barrier to be released will be
-readied and returned a status code which indicates that the
-barrier was deleted. The BCB for this barrier is reclaimed
-by RTEMS.
-
-**NOTES:**
-
-The calling task will be preempted if it is enabled
-by the task’s execution mode and a higher priority local task is
-waiting on the deleted barrier. The calling task will NOT be
-preempted if all of the tasks that are waiting on the barrier
-are remote tasks.
-
-The calling task does not have to be the task that
-created the barrier. Any local task that knows the barrier
-id can delete the barrier.
-
-.. COMMENT: Barrier Obtain
-
-BARRIER_OBTAIN - Acquire a barrier
-----------------------------------
-.. index:: obtain a barrier
-.. index:: lock a barrier
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_barrier_wait
-
-.. code:: c
-
- rtems_status_code rtems_barrier_wait(
- rtems_id id,
- rtems_interval timeout
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - barrier released and task unblocked
-``RTEMS_UNSATISFIED`` - barrier not available
-``RTEMS_TIMEOUT`` - timed out waiting for barrier
-``RTEMS_OBJECT_WAS_DELETED`` - barrier deleted while waiting
-``RTEMS_INVALID_ID`` - invalid barrier id
-
-**DESCRIPTION:**
-
-This directive acquires the barrier specified by
-id. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT``
-components of the options parameter indicate whether the calling task
-wants to wait for the barrier to become available or return immediately
-if the barrier is not currently available. With either``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``,
-if the current barrier count is positive, then it is
-decremented by one and the barrier is successfully acquired by
-returning immediately with a successful return code.
-
-Conceptually, the calling task should always be thought
-of as blocking when it makes this call and being unblocked when
-the barrier is released. If the barrier is configured for
-manual release, this rule of thumb will always be valid.
-If the barrier is configured for automatic release, all callers
-will block except for the one which is the Nth task which trips
-the automatic release condition.
-
-The timeout parameter specifies the maximum interval the calling task is
-willing to be blocked waiting for the barrier. If it is set to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
-If the barrier is available or the ``RTEMS_NO_WAIT`` option
-component is set, then timeout is ignored.
-
-**NOTES:**
-
-The following barrier acquisition option constants are defined by RTEMS:
-
-- ``RTEMS_WAIT`` - task will wait for barrier (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-A clock tick is required to support the timeout functionality of
-this directive.
-
-.. COMMENT: Release Barrier
-
-BARRIER_RELEASE - Release a barrier
------------------------------------
-.. index:: wait at a barrier
-.. index:: release a barrier
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_barrier_release
-
-.. code:: c
-
- rtems_status_code rtems_barrier_release(
- rtems_id id,
- uint32_t \*released
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - barrier released successfully
-``RTEMS_INVALID_ID`` - invalid barrier id
-
-**DESCRIPTION:**
-
-This directive releases the barrier specified by id.
-All tasks waiting at the barrier will be unblocked.
-If the running task’s preemption mode is enabled and one of
-the unblocked tasks has a higher priority than the running task.
-
-**NOTES:**
-
-The calling task may be preempted if it causes a
-higher priority task to be made ready for execution.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Message Manager
-###############
-
-.. index:: messages
-.. index:: message queues
-
-Introduction
-============
-
-The message manager provides communication and
-synchronization capabilities using RTEMS message queues. The
-directives provided by the message manager are:
-
-- ``rtems_message_queue_create`` - Create a queue
-
-- ``rtems_message_queue_ident`` - Get ID of a queue
-
-- ``rtems_message_queue_delete`` - Delete a queue
-
-- ``rtems_message_queue_send`` - Put message at rear of a queue
-
-- ``rtems_message_queue_urgent`` - Put message at front of a queue
-
-- ``rtems_message_queue_broadcast`` - Broadcast N messages to a queue
-
-- ``rtems_message_queue_receive`` - Receive message from a queue
-
-- ``rtems_message_queue_get_number_pending`` - Get number of messages pending on a queue
-
-- ``rtems_message_queue_flush`` - Flush all messages on a queue
-
-Background
-==========
-
-Messages
---------
-
-A message is a variable length buffer where
-information can be stored to support communication. The length
-of the message and the information stored in that message are
-user-defined and can be actual data, pointer(s), or empty.
-
-Message Queues
---------------
-
-A message queue permits the passing of messages among
-tasks and ISRs. Message queues can contain a variable number of
-messages. Normally messages are sent to and received from the
-queue in FIFO order using the ``rtems_message_queue_send``
-directive. However, the ``rtems_message_queue_urgent``
-directive can be used to place
-messages at the head of a queue in LIFO order.
-
-Synchronization can be accomplished when a task can
-wait for a message to arrive at a queue. Also, a task may poll
-a queue for the arrival of a message.
-
-The maximum length message which can be sent is set
-on a per message queue basis. The message content must be copied in general
-to/from an internal buffer of the message queue or directly to a peer in
-certain cases. This copy operation is performed with interrupts disabled. So
-it is advisable to keep the messages as short as possible.
-
-Building a Message Queue Attribute Set
---------------------------------------
-.. index:: message queue attributes
-
-In general, an attribute set is built by a bitwise OR
-of the desired attribute components. The set of valid message
-queue attributes is provided in the following table:
-
-- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
-
-- ``RTEMS_PRIORITY`` - tasks wait by priority
-
-- ``RTEMS_LOCAL`` - local message queue (default)
-
-- ``RTEMS_GLOBAL`` - global message queue
-
-An attribute listed as a default is not required to
-appear in the attribute list, although it is a good programming
-practice to specify default attributes. If all defaults are
-desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES``
-should be specified on this call.
-
-This example demonstrates the attribute_set parameter
-needed to create a local message queue with the task priority
-waiting queue discipline. The attribute_set parameter to the``rtems_message_queue_create`` directive could be either``RTEMS_PRIORITY`` or``RTEMS_LOCAL | RTEMS_PRIORITY``.
-The attribute_set parameter can be set to ``RTEMS_PRIORITY``
-because ``RTEMS_LOCAL`` is the default for all created
-message queues. If a similar message queue were to be known globally, then the
-attribute_set parameter would be``RTEMS_GLOBAL | RTEMS_PRIORITY``.
-
-Building a MESSAGE_QUEUE_RECEIVE Option Set
--------------------------------------------
-
-In general, an option is built by a bitwise OR of the
-desired option components. The set of valid options for the``rtems_message_queue_receive`` directive are
-listed in the following table:
-
-- ``RTEMS_WAIT`` - task will wait for a message (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-An option listed as a default is not required to
-appear in the option OR list, although it is a good programming
-practice to specify default options. If all defaults are
-desired, the option ``RTEMS_DEFAULT_OPTIONS`` should
-be specified on this call.
-
-This example demonstrates the option parameter needed
-to poll for a message to arrive. The option parameter passed to
-the ``rtems_message_queue_receive`` directive should
-be ``RTEMS_NO_WAIT``.
-
-Operations
-==========
-
-Creating a Message Queue
-------------------------
-
-The ``rtems_message_queue_create`` directive creates a message
-queue with the user-defined name. The user specifies the
-maximum message size and maximum number of messages which can be
-placed in the message queue at one time. The user may select
-FIFO or task priority as the method for placing waiting tasks in
-the task wait queue. RTEMS allocates a Queue Control Block
-(QCB) from the QCB free list to maintain the newly created queue
-as well as memory for the message buffer pool associated with
-this message queue. RTEMS also generates a message queue ID
-which is returned to the calling task.
-
-For GLOBAL message queues, the maximum message size
-is effectively limited to the longest message which the MPCI is
-capable of transmitting.
-
-Obtaining Message Queue IDs
----------------------------
-
-When a message queue is created, RTEMS generates a
-unique message queue ID. The message queue ID may be obtained
-by either of two methods. First, as the result of an invocation
-of the ``rtems_message_queue_create`` directive, the
-queue ID is stored in a user provided location. Second, the queue
-ID may be obtained later using the ``rtems_message_queue_ident``
-directive. The queue ID is used by other message manager
-directives to access this message queue.
-
-Receiving a Message
--------------------
-
-The ``rtems_message_queue_receive`` directive attempts to
-retrieve a message from the specified message queue. If at
-least one message is in the queue, then the message is removed
-from the queue, copied to the caller’s message buffer, and
-returned immediately along with the length of the message. When
-messages are unavailable, one of the following situations
-applies:
-
-- By default, the calling task will wait forever for the
- message to arrive.
-
-- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return
- with an error status code.
-
-- Specifying a timeout limits the period the task will
- wait before returning with an error status.
-
-If the task waits for a message, then it is placed in
-the message queue’s task wait queue in either FIFO or task
-priority order. All tasks waiting on a message queue are
-returned an error code when the message queue is deleted.
-
-Sending a Message
------------------
-
-Messages can be sent to a queue with the``rtems_message_queue_send`` and``rtems_message_queue_urgent`` directives. These
-directives work identically when tasks are waiting to receive a
-message. A task is removed from the task waiting queue,
-unblocked, and the message is copied to a waiting task’s
-message buffer.
-
-When no tasks are waiting at the queue,``rtems_message_queue_send`` places the
-message at the rear of the message queue, while``rtems_message_queue_urgent`` places the message at the
-front of the queue. The message is copied to a message buffer
-from this message queue’s buffer pool and then placed in the
-message queue. Neither directive can successfully send a
-message to a message queue which has a full queue of pending
-messages.
-
-Broadcasting a Message
-----------------------
-
-The ``rtems_message_queue_broadcast`` directive sends the same
-message to every task waiting on the specified message queue as
-an atomic operation. The message is copied to each waiting
-task’s message buffer and each task is unblocked. The number of
-tasks which were unblocked is returned to the caller.
-
-Deleting a Message Queue
-------------------------
-
-The ``rtems_message_queue_delete`` directive removes a message
-queue from the system and frees its control block as well as the
-memory associated with this message queue’s message buffer pool.
-A message queue can be deleted by any local task that knows the
-message queue’s ID. As a result of this directive, all tasks
-blocked waiting to receive a message from the message queue will
-be readied and returned a status code which indicates that the
-message queue was deleted. Any subsequent references to the
-message queue’s name and ID are invalid. Any messages waiting
-at the message queue are also deleted and deallocated.
-
-Directives
-==========
-
-This section details the message manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-MESSAGE_QUEUE_CREATE - Create a queue
--------------------------------------
-.. index:: create a message queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_create
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_create(
- rtems_name name,
- uint32_t count,
- size_t max_message_size,
- rtems_attribute attribute_set,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - queue created successfully
-``RTEMS_INVALID_NAME`` - invalid queue name
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NUMBER`` - invalid message count
-``RTEMS_INVALID_SIZE`` - invalid message size
-``RTEMS_TOO_MANY`` - too many queues created
-``RTEMS_UNSATISFIED`` - unable to allocate message buffers
-``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured
-``RTEMS_TOO_MANY`` - too many global objects
-
-**DESCRIPTION:**
-
-This directive creates a message queue which resides
-on the local node with the user-defined name specified in name.
-For control and maintenance of the queue, RTEMS allocates and
-initializes a QCB. Memory is allocated from the RTEMS Workspace
-for the specified count of messages, each of max_message_size
-bytes in length. The RTEMS-assigned queue id, returned in id,
-is used to access the message queue.
-
-Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks
-waiting for a message to be serviced according to task priority.
-When ``RTEMS_FIFO`` is specified, waiting tasks are serviced
-in First In-First Out order.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The following message queue attribute constants are
-defined by RTEMS:
-
-- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
-
-- ``RTEMS_PRIORITY`` - tasks wait by priority
-
-- ``RTEMS_LOCAL`` - local message queue (default)
-
-- ``RTEMS_GLOBAL`` - global message queue
-
-Message queues should not be made global unless
-remote tasks must interact with the created message queue. This
-is to avoid the system overhead incurred by the creation of a
-global message queue. When a global message queue is created,
-the message queue’s name and id must be transmitted to every
-node in the system for insertion in the local copy of the global
-object table.
-
-For GLOBAL message queues, the maximum message size
-is effectively limited to the longest message which the MPCI is
-capable of transmitting.
-
-The total number of global objects, including message
-queues, is limited by the maximum_global_objects field in the
-configuration table.
-
-MESSAGE_QUEUE_IDENT - Get ID of a queue
----------------------------------------
-.. index:: get ID of a message queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_ident
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_ident(
- rtems_name name,
- uint32_t node,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - queue identified successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - queue name not found
-``RTEMS_INVALID_NODE`` - invalid node id
-
-**DESCRIPTION:**
-
-This directive obtains the queue id associated with
-the queue name specified in name. If the queue name is not
-unique, then the queue id will match one of the queues with that
-name. However, this queue id is not guaranteed to correspond to
-the desired queue. The queue id is used with other message
-related directives to access the message queue.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched
-with the local node being searched first. All other nodes are
-searched with the lowest numbered node searched first.
-
-If node is a valid node number which does not
-represent the local node, then only the message queues exported
-by the designated node are searched.
-
-This directive does not generate activity on remote
-nodes. It accesses only the local copy of the global object
-table.
-
-MESSAGE_QUEUE_DELETE - Delete a queue
--------------------------------------
-.. index:: delete a message queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_delete
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - queue deleted successfully
-``RTEMS_INVALID_ID`` - invalid queue id
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote queue
-
-**DESCRIPTION:**
-
-This directive deletes the message queue specified by
-id. As a result of this directive, all tasks blocked waiting to
-receive a message from this queue will be readied and returned a
-status code which indicates that the message queue was deleted.
-If no tasks are waiting, but the queue contains messages, then
-RTEMS returns these message buffers back to the system message
-buffer pool. The QCB for this queue as well as the memory for
-the message buffers is reclaimed by RTEMS.
-
-**NOTES:**
-
-The calling task will be preempted if its preemption
-mode is enabled and one or more local tasks with a higher
-priority than the calling task are waiting on the deleted queue.
-The calling task will NOT be preempted if the tasks that are
-waiting are remote tasks.
-
-The calling task does not have to be the task that
-created the queue, although the task and queue must reside on
-the same node.
-
-When the queue is deleted, any messages in the queue
-are returned to the free message buffer pool. Any information
-stored in those messages is lost.
-
-When a global message queue is deleted, the message
-queue id must be transmitted to every node in the system for
-deletion from the local copy of the global object table.
-
-Proxies, used to represent remote tasks, are
-reclaimed when the message queue is deleted.
-
-MESSAGE_QUEUE_SEND - Put message at rear of a queue
----------------------------------------------------
-.. index:: send message to a queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_send
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_send(
- rtems_id id,
- cons void \*buffer,
- size_t size
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - message sent successfully
-``RTEMS_INVALID_ID`` - invalid queue id
-``RTEMS_INVALID_SIZE`` - invalid message size
-``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
-``RTEMS_UNSATISFIED`` - out of message buffers
-``RTEMS_TOO_MANY`` - queue’s limit has been reached
-
-**DESCRIPTION:**
-
-This directive sends the message buffer of size bytes
-in length to the queue specified by id. If a task is waiting at
-the queue, then the message is copied to the waiting task’s
-buffer and the task is unblocked. If no tasks are waiting at the
-queue, then the message is copied to a message buffer which is
-obtained from this message queue’s message buffer pool. The
-message buffer is then placed at the rear of the queue.
-
-**NOTES:**
-
-The calling task will be preempted if it has
-preemption enabled and a higher priority task is unblocked as
-the result of this directive.
-
-Sending a message to a global message queue which
-does not reside on the local node will generate a request to the
-remote node to post the message on the specified message queue.
-
-If the task to be unblocked resides on a different
-node from the message queue, then the message is forwarded to
-the appropriate node, the waiting task is unblocked, and the
-proxy used to represent the task is reclaimed.
-
-MESSAGE_QUEUE_URGENT - Put message at front of a queue
-------------------------------------------------------
-.. index:: put message at front of queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_urgent
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_urgent(
- rtems_id id,
- const void \*buffer,
- size_t size
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - message sent successfully
-``RTEMS_INVALID_ID`` - invalid queue id
-``RTEMS_INVALID_SIZE`` - invalid message size
-``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
-``RTEMS_UNSATISFIED`` - out of message buffers
-``RTEMS_TOO_MANY`` - queue’s limit has been reached
-
-**DESCRIPTION:**
-
-This directive sends the message buffer of size bytes
-in length to the queue specified by id. If a task is waiting on
-the queue, then the message is copied to the task’s buffer and
-the task is unblocked. If no tasks are waiting on the queue,
-then the message is copied to a message buffer which is obtained
-from this message queue’s message buffer pool. The message
-buffer is then placed at the front of the queue.
-
-**NOTES:**
-
-The calling task will be preempted if it has
-preemption enabled and a higher priority task is unblocked as
-the result of this directive.
-
-Sending a message to a global message queue which
-does not reside on the local node will generate a request
-telling the remote node to post the message on the specified
-message queue.
-
-If the task to be unblocked resides on a different
-node from the message queue, then the message is forwarded to
-the appropriate node, the waiting task is unblocked, and the
-proxy used to represent the task is reclaimed.
-
-MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
----------------------------------------------------------
-.. index:: broadcast message to a queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_broadcast
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_broadcast(
- rtems_id id,
- const void \*buffer,
- size_t size,
- uint32_t \*count
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - message broadcasted successfully
-``RTEMS_INVALID_ID`` - invalid queue id
-``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``count`` is NULL
-``RTEMS_INVALID_SIZE`` - invalid message size
-
-**DESCRIPTION:**
-
-This directive causes all tasks that are waiting at
-the queue specified by id to be unblocked and sent the message
-contained in buffer. Before a task is unblocked, the message
-buffer of size byes in length is copied to that task’s message
-buffer. The number of tasks that were unblocked is returned in
-count.
-
-**NOTES:**
-
-The calling task will be preempted if it has
-preemption enabled and a higher priority task is unblocked as
-the result of this directive.
-
-The execution time of this directive is directly
-related to the number of tasks waiting on the message queue,
-although it is more efficient than the equivalent number of
-invocations of ``rtems_message_queue_send``.
-
-Broadcasting a message to a global message queue
-which does not reside on the local node will generate a request
-telling the remote node to broadcast the message to the
-specified message queue.
-
-When a task is unblocked which resides on a different
-node from the message queue, a copy of the message is forwarded
-to the appropriate node, the waiting task is unblocked, and the
-proxy used to represent the task is reclaimed.
-
-MESSAGE_QUEUE_RECEIVE - Receive message from a queue
-----------------------------------------------------
-.. index:: receive message from a queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_receive
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_receive(
- rtems_id id,
- void \*buffer,
- size_t \*size,
- rtems_option option_set,
- rtems_interval timeout
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - message received successfully
-``RTEMS_INVALID_ID`` - invalid queue id
-``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``size`` is NULL
-``RTEMS_UNSATISFIED`` - queue is empty
-``RTEMS_TIMEOUT`` - timed out waiting for message
-``RTEMS_OBJECT_WAS_DELETED`` - queue deleted while waiting
-
-**DESCRIPTION:**
-
-This directive receives a message from the message
-queue specified in id. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the
-options parameter allow the calling task to specify whether to
-wait for a message to become available or return immediately.
-For either option, if there is at least one message in the
-queue, then it is copied to buffer, size is set to return the
-length of the message in bytes, and this directive returns
-immediately with a successful return code. The buffer has to be big enough to
-receive a message of the maximum length with respect to this message queue.
-
-If the calling task chooses to return immediately and
-the queue is empty, then a status code indicating this condition
-is returned. If the calling task chooses to wait at the message
-queue and the queue is empty, then the calling task is placed on
-the message wait queue and blocked. If the queue was created
-with the ``RTEMS_PRIORITY`` option specified, then
-the calling task is inserted into the wait queue according to
-its priority. But, if the queue was created with the``RTEMS_FIFO`` option specified, then the
-calling task is placed at the rear of the wait queue.
-
-A task choosing to wait at the queue can optionally
-specify a timeout value in the timeout parameter. The timeout
-parameter specifies the maximum interval to wait before the
-calling task desires to be unblocked. If it is set to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
-
-**NOTES:**
-
-The following message receive option constants are
-defined by RTEMS:
-
-- ``RTEMS_WAIT`` - task will wait for a message (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-Receiving a message from a global message queue which
-does not reside on the local node will generate a request to the
-remote node to obtain a message from the specified message
-queue. If no message is available and ``RTEMS_WAIT`` was specified, then
-the task must be blocked until a message is posted. A proxy is
-allocated on the remote node to represent the task until the
-message is posted.
-
-A clock tick is required to support the timeout functionality of
-this directive.
-
-MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue
-----------------------------------------------------------------------------
-.. index:: get number of pending messages
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_get_number_pending
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_get_number_pending(
- rtems_id id,
- uint32_t \*count
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - number of messages pending returned successfully
-``RTEMS_INVALID_ADDRESS`` - ``count`` is NULL
-``RTEMS_INVALID_ID`` - invalid queue id
-
-**DESCRIPTION:**
-
-This directive returns the number of messages pending on this
-message queue in count. If no messages are present
-on the queue, count is set to zero.
-
-**NOTES:**
-
-Getting the number of pending messages on a global message queue which
-does not reside on the local node will generate a request to the
-remote node to actually obtain the pending message count for
-the specified message queue.
-
-MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
----------------------------------------------------
-.. index:: flush messages on a queue
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_message_queue_flush
-
-.. code:: c
-
- rtems_status_code rtems_message_queue_flush(
- rtems_id id,
- uint32_t \*count
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - message queue flushed successfully
-``RTEMS_INVALID_ADDRESS`` - ``count`` is NULL
-``RTEMS_INVALID_ID`` - invalid queue id
-
-**DESCRIPTION:**
-
-This directive removes all pending messages from the
-specified queue id. The number of messages removed is returned
-in count. If no messages are present on the queue, count is set
-to zero.
-
-**NOTES:**
-
-Flushing all messages on a global message queue which
-does not reside on the local node will generate a request to the
-remote node to actually flush the specified message queue.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Event Manager
-#############
-
-.. index:: events
-
-Introduction
-============
-
-The event manager provides a high performance method
-of intertask communication and synchronization. The directives
-provided by the event manager are:
-
-- ``rtems_event_send`` - Send event set to a task
-
-- ``rtems_event_receive`` - Receive event condition
-
-Background
-==========
-
-Event Sets
-----------
-.. index:: event flag, definition
-.. index:: event set, definition
-.. index:: rtems_event_set
-
-An event flag is used by a task (or ISR) to inform
-another task of the occurrence of a significant situation.
-Thirty-two event flags are associated with each task. A
-collection of one or more event flags is referred to as an event
-set. The data type ``rtems_event_set`` is used to manage
-event sets.
-
-The application developer should remember the following
-key characteristics of event operations when utilizing the event
-manager:
-
-- Events provide a simple synchronization facility.
-
-- Events are aimed at tasks.
-
-- Tasks can wait on more than one event simultaneously.
-
-- Events are independent of one another.
-
-- Events do not hold or transport data.
-
-- Events are not queued. In other words, if an event is
- sent more than once to a task before being received, the second and
- subsequent send operations to that same task have no effect.
-
-An event set is posted when it is directed (or sent) to a task. A
-pending event is an event that has been posted but not received. An event
-condition is used to specify the event set which the task desires to receive
-and the algorithm which will be used to determine when the request is
-satisfied. An event condition is satisfied based upon one of two
-algorithms which are selected by the user. The``RTEMS_EVENT_ANY`` algorithm states that an event condition
-is satisfied when at least a single requested event is posted. The``RTEMS_EVENT_ALL`` algorithm states that an event condition
-is satisfied when every requested event is posted.
-
-Building an Event Set or Condition
-----------------------------------
-.. index:: event condition, building
-.. index:: event set, building
-
-An event set or condition is built by a bitwise OR of
-the desired events. The set of valid events is ``RTEMS_EVENT_0`` through``RTEMS_EVENT_31``. If an event is not explicitly specified in the set or
-condition, then it is not present. Events are specifically
-designed to be mutually exclusive, therefore bitwise OR and
-addition operations are equivalent as long as each event appears
-exactly once in the event set list.
-
-For example, when sending the event set consisting of``RTEMS_EVENT_6``, ``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``,
-the event parameter to the ``rtems_event_send``
-directive should be ``RTEMS_EVENT_6 |
-RTEMS_EVENT_15 | RTEMS_EVENT_31``.
-
-Building an EVENT_RECEIVE Option Set
-------------------------------------
-
-In general, an option is built by a bitwise OR of the
-desired option components. The set of valid options for the``rtems_event_receive`` directive are listed
-in the following table:
-
-- ``RTEMS_WAIT`` - task will wait for event (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-- ``RTEMS_EVENT_ALL`` - return after all events (default)
-
-- ``RTEMS_EVENT_ANY`` - return after any events
-
-Option values are specifically designed to be
-mutually exclusive, therefore bitwise OR and addition operations
-are equivalent as long as each option appears exactly once in
-the component list. An option listed as a default is not
-required to appear in the option list, although it is a good
-programming practice to specify default options. If all
-defaults are desired, the option ``RTEMS_DEFAULT_OPTIONS`` should be
-specified on this call.
-
-This example demonstrates the option parameter needed
-to poll for all events in a particular event condition to
-arrive. The option parameter passed to the``rtems_event_receive`` directive should be either``RTEMS_EVENT_ALL | RTEMS_NO_WAIT``
-or ``RTEMS_NO_WAIT``. The option parameter can be set to``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the
-default condition for ``rtems_event_receive``.
-
-Operations
-==========
-
-Sending an Event Set
---------------------
-
-The ``rtems_event_send`` directive allows a task (or an ISR) to
-direct an event set to a target task. Based upon the state of
-the target task, one of the following situations applies:
-
-- Target Task is Blocked Waiting for Events
-
- - If the waiting task’s input event condition is
- satisfied, then the task is made ready for execution.
-
- - If the waiting task’s input event condition is not
- satisfied, then the event set is posted but left pending and the
- task remains blocked.
-
-- Target Task is Not Waiting for Events
-
- - The event set is posted and left pending.
-
-Receiving an Event Set
-----------------------
-
-The ``rtems_event_receive`` directive is used by tasks to
-accept a specific input event condition. The task also
-specifies whether the request is satisfied when all requested
-events are available or any single requested event is available.
-If the requested event condition is satisfied by pending
-events, then a successful return code and the satisfying event
-set are returned immediately. If the condition is not
-satisfied, then one of the following situations applies:
-
-- By default, the calling task will wait forever for the
- event condition to be satisfied.
-
-- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return
- with an error status code.
-
-- Specifying a timeout limits the period the task will
- wait before returning with an error status code.
-
-Determining the Pending Event Set
----------------------------------
-
-A task can determine the pending event set by calling
-the ``rtems_event_receive`` directive with a value of``RTEMS_PENDING_EVENTS`` for the input event condition.
-The pending events are returned to the calling task but the event
-set is left unaltered.
-
-Receiving all Pending Events
-----------------------------
-
-A task can receive all of the currently pending
-events by calling the ``rtems_event_receive``
-directive with a value of ``RTEMS_ALL_EVENTS``
-for the input event condition and``RTEMS_NO_WAIT | RTEMS_EVENT_ANY``
-for the option set. The pending events are returned to the
-calling task and the event set is cleared. If no events are
-pending then the ``RTEMS_UNSATISFIED`` status code will be returned.
-
-Directives
-==========
-
-This section details the event manager’s directives.
-A subsection is dedicated to each of this manager’s directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-EVENT_SEND - Send event set to a task
--------------------------------------
-.. index:: send event set to a task
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_event_send
-
-.. code:: c
-
- rtems_status_code rtems_event_send (
- rtems_id id,
- rtems_event_set event_in
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - event set sent successfully
-``RTEMS_INVALID_ID`` - invalid task id
-
-**DESCRIPTION:**
-
-This directive sends an event set, event_in, to the
-task specified by id. If a blocked task’s input event condition
-is satisfied by this directive, then it will be made ready. If
-its input event condition is not satisfied, then the events
-satisfied are updated and the events not satisfied are left
-pending. If the task specified by id is not blocked waiting for
-events, then the events sent are left pending.
-
-**NOTES:**
-
-Specifying ``RTEMS_SELF`` for id results in the event set being
-sent to the calling task.
-
-Identical events sent to a task are not queued. In
-other words, the second, and subsequent, posting of an event to
-a task before it can perform an ``rtems_event_receive``
-has no effect.
-
-The calling task will be preempted if it has
-preemption enabled and a higher priority task is unblocked as
-the result of this directive.
-
-Sending an event set to a global task which does not
-reside on the local node will generate a request telling the
-remote node to send the event set to the appropriate task.
-
-EVENT_RECEIVE - Receive event condition
----------------------------------------
-.. index:: receive event condition
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_event_receive
-
-.. code:: c
-
- rtems_status_code rtems_event_receive (
- rtems_event_set event_in,
- rtems_option option_set,
- rtems_interval ticks,
- rtems_event_set \*event_out
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - event received successfully
-``RTEMS_UNSATISFIED`` - input event not satisfied (``RTEMS_NO_WAIT``)
-``RTEMS_INVALID_ADDRESS`` - ``event_out`` is NULL
-``RTEMS_TIMEOUT`` - timed out waiting for event
-
-**DESCRIPTION:**
-
-This directive attempts to receive the event
-condition specified in event_in. If event_in is set to``RTEMS_PENDING_EVENTS``, then the current pending events are returned in
-event_out and left pending. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options in the
-option_set parameter are used to specify whether or not the task
-is willing to wait for the event condition to be satisfied.``RTEMS_EVENT_ANY`` and ``RTEMS_EVENT_ALL`` are used in the option_set parameter are
-used to specify whether a single event or the complete event set
-is necessary to satisfy the event condition. The event_out
-parameter is returned to the calling task with the value that
-corresponds to the events in event_in that were satisfied.
-
-If pending events satisfy the event condition, then
-event_out is set to the satisfied events and the pending events
-in the event condition are cleared. If the event condition is
-not satisfied and ``RTEMS_NO_WAIT`` is specified, then event_out is set to
-the currently satisfied events. If the calling task chooses to
-wait, then it will block waiting for the event condition.
-
-If the calling task must wait for the event condition
-to be satisfied, then the timeout parameter is used to specify
-the maximum interval to wait. If it is set to ``RTEMS_NO_TIMEOUT``, then
-the calling task will wait forever.
-
-**NOTES:**
-
-This directive only affects the events specified in
-event_in. Any pending events that do not correspond to any of
-the events specified in event_in will be left pending.
-
-The following event receive option constants are defined by
-RTEMS:
-
-- ``RTEMS_WAIT`` task will wait for event (default)
-
-- ``RTEMS_NO_WAIT`` task should not wait
-
-- ``RTEMS_EVENT_ALL`` return after all events (default)
-
-- ``RTEMS_EVENT_ANY`` return after any events
-
-A clock tick is required to support the functionality of this directive.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Signal Manager
-##############
-
-.. index:: signals
-
-Introduction
-============
-
-The signal manager provides the capabilities required
-for asynchronous communication. The directives provided by the
-signal manager are:
-
-- ``rtems_signal_catch`` - Establish an ASR
-
-- ``rtems_signal_send`` - Send signal set to a task
-
-Background
-==========
-
-Signal Manager Definitions
---------------------------
-.. index:: asynchronous signal routine
-.. index:: ASR
-
-The signal manager allows a task to optionally define
-an asynchronous signal routine (ASR). An ASR is to a task what
-an ISR is to an application’s set of tasks. When the processor
-is interrupted, the execution of an application is also
-interrupted and an ISR is given control. Similarly, when a
-signal is sent to a task, that task’s execution path will be
-"interrupted" by the ASR. Sending a signal to a task has no
-effect on the receiving task’s current execution state... index:: rtems_signal_set
-
-A signal flag is used by a task (or ISR) to inform
-another task of the occurrence of a significant situation.
-Thirty-two signal flags are associated with each task. A
-collection of one or more signals is referred to as a signal
-set. The data type ``rtems_signal_set``
-is used to manipulate signal sets.
-
-A signal set is posted when it is directed (or sent) to a
-task. A pending signal is a signal that has been sent to a task
-with a valid ASR, but has not been processed by that task’s ASR.
-
-A Comparison of ASRs and ISRs
------------------------------
-.. index:: ASR vs. ISR
-.. index:: ISR vs. ASR
-
-The format of an ASR is similar to that of an ISR
-with the following exceptions:
-
-- ISRs are scheduled by the processor hardware. ASRs are
- scheduled by RTEMS.
-
-- ISRs do not execute in the context of a task and may
- invoke only a subset of directives. ASRs execute in the context
- of a task and may execute any directive.
-
-- When an ISR is invoked, it is passed the vector number
- as its argument. When an ASR is invoked, it is passed the
- signal set as its argument.
-
-- An ASR has a task mode which can be different from that
- of the task. An ISR does not execute as a task and, as a
- result, does not have a task mode.
-
-Building a Signal Set
----------------------
-.. index:: signal set, building
-
-A signal set is built by a bitwise OR of the desired
-signals. The set of valid signals is ``RTEMS_SIGNAL_0`` through``RTEMS_SIGNAL_31``. If a signal is not explicitly specified in the
-signal set, then it is not present. Signal values are
-specifically designed to be mutually exclusive, therefore
-bitwise OR and addition operations are equivalent as long as
-each signal appears exactly once in the component list.
-
-This example demonstrates the signal parameter used
-when sending the signal set consisting of``RTEMS_SIGNAL_6``,``RTEMS_SIGNAL_15``, and``RTEMS_SIGNAL_31``. The signal parameter provided
-to the ``rtems_signal_send`` directive should be``RTEMS_SIGNAL_6 |
-RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
-
-Building an ASR Mode
---------------------
-.. index:: ASR mode, building
-
-In general, an ASR’s mode is built by a bitwise OR of
-the desired mode components. The set of valid mode components
-is the same as those allowed with the task_create and task_mode
-directives. A complete list of mode options is provided in the
-following table:
-
-- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption
-
-- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption
-
-- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing
-
-- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing
-
-- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing
-
-- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing
-
-- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts
-
-- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
-
-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 list, although it is a good
-programming practice to specify default components. If all
-defaults are desired, the mode DEFAULT_MODES should be specified
-on this call.
-
-This example demonstrates the mode parameter used
-with the ``rtems_signal_catch``
-to establish an ASR which executes at
-interrupt level three and is non-preemptible. The mode should
-be set to``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT``
-to indicate the
-desired processor mode and interrupt level.
-
-Operations
-==========
-
-Establishing an ASR
--------------------
-
-The ``rtems_signal_catch`` directive establishes an ASR for the
-calling task. The address of the ASR and its execution mode are
-specified to this directive. The ASR’s mode is distinct from
-the task’s mode. For example, the task may allow preemption,
-while that task’s ASR may have preemption disabled. Until a
-task calls ``rtems_signal_catch`` the first time,
-its ASR is invalid, and no signal sets can be sent to the task.
-
-A task may invalidate its ASR and discard all pending
-signals by calling ``rtems_signal_catch``
-with a value of NULL for the ASR’s address. When a task’s
-ASR is invalid, new signal sets sent to this task are discarded.
-
-A task may disable ASR processing (``RTEMS_NO_ASR``) via the
-task_mode directive. When a task’s ASR is disabled, the signals
-sent to it are left pending to be processed later when the ASR
-is enabled.
-
-Any directive that can be called from a task can also
-be called from an ASR. A task is only allowed one active ASR.
-Thus, each call to ``rtems_signal_catch``
-replaces the previous one.
-
-Normally, signal processing is disabled for the ASR’s
-execution mode, but if signal processing is enabled for the ASR,
-the ASR must be reentrant.
-
-Sending a Signal Set
---------------------
-
-The ``rtems_signal_send`` directive allows both
-tasks and ISRs to send signals to a target task. The target task and
-a set of signals are specified to the``rtems_signal_send`` directive. The sending
-of a signal to a task has no effect on the execution state of
-that task. If the task is not the currently running task, then
-the signals are left pending and processed by the task’s ASR the
-next time the task is dispatched to run. The ASR is executed
-immediately before the task is dispatched. If the currently
-running task sends a signal to itself or is sent a signal from
-an ISR, its ASR is immediately dispatched to run provided signal
-processing is enabled.
-
-If an ASR with signals enabled is preempted by
-another task or an ISR and a new signal set is sent, then a new
-copy of the ASR will be invoked, nesting the preempted ASR.
-Upon completion of processing the new signal set, control will
-return to the preempted ASR. In this situation, the ASR must be
-reentrant.
-
-Like events, identical signals sent to a task are not
-queued. In other words, sending the same signal multiple times
-to a task (without any intermediate signal processing occurring
-for the task), has the same result as sending that signal to
-that task once.
-
-Processing an ASR
------------------
-
-Asynchronous signals were designed to provide the
-capability to generate software interrupts. The processing of
-software interrupts parallels that of hardware interrupts. As a
-result, the differences between the formats of ASRs and ISRs is
-limited to the meaning of the single argument passed to an ASR.
-The ASR should have the following calling sequence and adhere to
-C calling conventions:.. index:: rtems_asr
-
-.. code:: c
-
- rtems_asr user_routine(
- rtems_signal_set signals
- );
-
-When the ASR returns to RTEMS the mode and execution
-path of the interrupted task (or ASR) is restored to the context
-prior to entering the ASR.
-
-Directives
-==========
-
-This section details the signal manager’s directives.
-A subsection is dedicated to each of this manager’s directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-SIGNAL_CATCH - Establish an ASR
--------------------------------
-.. index:: establish an ASR
-.. index:: install an ASR
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_signal_catch
-
-.. code:: c
-
- rtems_status_code rtems_signal_catch(
- rtems_asr_entry asr_handler,
- rtems_mode mode
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - always successful
-
-**DESCRIPTION:**
-
-This directive establishes an asynchronous signal
-routine (ASR) for the calling task. The asr_handler parameter
-specifies the entry point of the ASR. If asr_handler is NULL,
-the ASR for the calling task is invalidated and all pending
-signals are cleared. Any signals sent to a task with an invalid
-ASR are discarded. The mode parameter specifies the execution
-mode for the ASR. This execution mode supersedes the task’s
-execution mode while the ASR is executing.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The following task mode constants are defined by RTEMS:
-
-- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption
-
-- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption
-
-- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing
-
-- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing
-
-- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing
-
-- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing
-
-- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts
-
-- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
-
-SIGNAL_SEND - Send signal set to a task
----------------------------------------
-.. index:: send signal set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_signal_send
-
-.. code:: c
-
- rtems_status_code rtems_signal_send(
- rtems_id id,
- rtems_signal_set signal_set
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - signal sent successfully
-``RTEMS_INVALID_ID`` - task id invalid
-``RTEMS_INVALID_NUMBER`` - empty signal set
-``RTEMS_NOT_DEFINED`` - ASR invalid
-
-**DESCRIPTION:**
-
-This directive sends a signal set to the task
-specified in id. The signal_set parameter contains the signal
-set to be sent to the task.
-
-If a caller sends a signal set to a task with an
-invalid ASR, then an error code is returned to the caller. If a
-caller sends a signal set to a task whose ASR is valid but
-disabled, then the signal set will be caught and left pending
-for the ASR to process when it is enabled. If a caller sends a
-signal set to a task with an ASR that is both valid and enabled,
-then the signal set is caught and the ASR will execute the next
-time the task is dispatched to run.
-
-**NOTES:**
-
-Sending a signal set to a task has no effect on that
-task’s state. If a signal set is sent to a blocked task, then
-the task will remain blocked and the signals will be processed
-when the task becomes the running task.
-
-Sending a signal set to a global task which does not
-reside on the local node will generate a request telling the
-remote node to send the signal set to the specified task.
-
-.. COMMENT: COPYRIGHT (c) 1988-2010.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Partition Manager
-#################
-
-.. index:: partitions
-
-Introduction
-============
-
-The partition manager provides facilities to
-dynamically allocate memory in fixed-size units. The directives
-provided by the partition manager are:
-
-- ``rtems_partition_create`` - Create a partition
-
-- ``rtems_partition_ident`` - Get ID of a partition
-
-- ``rtems_partition_delete`` - Delete a partition
-
-- ``rtems_partition_get_buffer`` - Get buffer from a partition
-
-- ``rtems_partition_return_buffer`` - Return buffer to a partition
-
-Background
-==========
-
-Partition Manager Definitions
------------------------------
-.. index:: partition, definition
-
-A partition is a physically contiguous memory area
-divided into fixed-size buffers that can be dynamically
-allocated and deallocated... index:: buffers, definition
-
-Partitions are managed and maintained as a list of
-buffers. Buffers are obtained from the front of the partition’s
-free buffer chain and returned to the rear of the same chain.
-When a buffer is on the free buffer chain, RTEMS uses two
-pointers of memory from each buffer as the free buffer chain.
-When a buffer is allocated, the entire buffer is available for application use.
-Therefore, modifying memory that is outside of an allocated
-buffer could destroy the free buffer chain or the contents of an
-adjacent allocated buffer.
-
-Building a Partition Attribute Set
-----------------------------------
-.. index:: partition attribute set, building
-
-In general, an attribute set is built by a bitwise OR
-of the desired attribute components. The set of valid partition
-attributes is provided in the following table:
-
-- ``RTEMS_LOCAL`` - local partition (default)
-
-- ``RTEMS_GLOBAL`` - global partition
-
-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. An attribute listed as a default is not
-required to appear in the attribute list, although it is a good
-programming practice to specify default attributes. If all
-defaults are desired, the attribute``RTEMS_DEFAULT_ATTRIBUTES`` should be
-specified on this call. The attribute_set parameter should be``RTEMS_GLOBAL`` to indicate that the partition
-is to be known globally.
-
-Operations
-==========
-
-Creating a Partition
---------------------
-
-The ``rtems_partition_create`` directive creates a partition
-with a user-specified name. The partition’s name, starting
-address, length and buffer size are all specified to the``rtems_partition_create`` directive.
-RTEMS allocates a Partition Control
-Block (PTCB) from the PTCB free list. This data structure is
-used by RTEMS to manage the newly created partition. The number
-of buffers in the partition is calculated based upon the
-specified partition length and buffer size. If successful,the
-unique partition ID is returned to the calling task.
-
-Obtaining Partition IDs
------------------------
-
-When a partition is created, RTEMS generates a unique
-partition ID and assigned it to the created partition until it
-is deleted. The partition ID may be obtained by either of two
-methods. First, as the result of an invocation of the``rtems_partition_create`` directive, the partition
-ID is stored in a user provided location. Second, the partition
-ID may be obtained later using the ``rtems_partition_ident``
-directive. The partition ID is used by other partition manager directives
-to access this partition.
-
-Acquiring a Buffer
-------------------
-
-A buffer can be obtained by calling the``rtems_partition_get_buffer`` directive.
-If a buffer is available, then
-it is returned immediately with a successful return code.
-Otherwise, an unsuccessful return code is returned immediately
-to the caller. Tasks cannot block to wait for a buffer to
-become available.
-
-Releasing a Buffer
-------------------
-
-Buffers are returned to a partition’s free buffer
-chain with the ``rtems_partition_return_buffer`` directive. This
-directive returns an error status code if the returned buffer
-was not previously allocated from this partition.
-
-Deleting a Partition
---------------------
-
-The ``rtems_partition_delete`` directive allows a partition to
-be removed and returned to RTEMS. When a partition is deleted,
-the PTCB for that partition is returned to the PTCB free list.
-A partition with buffers still allocated cannot be deleted. Any
-task attempting to do so will be returned an error status code.
-
-Directives
-==========
-
-This section details the partition manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-PARTITION_CREATE - Create a partition
--------------------------------------
-.. index:: create a partition
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_partition_create
-
-.. code:: c
-
- rtems_status_code rtems_partition_create(
- rtems_name name,
- void \*starting_address,
- uint32_t length,
- uint32_t buffer_size,
- rtems_attribute attribute_set,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - partition created successfully
-``RTEMS_INVALID_NAME`` - invalid partition name
-``RTEMS_TOO_MANY`` - too many partitions created
-``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary
-``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_SIZE`` - length or buffer size is 0
-``RTEMS_INVALID_SIZE`` - length is less than the buffer size
-``RTEMS_INVALID_SIZE`` - buffer size not a multiple of 4
-``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured
-``RTEMS_TOO_MANY`` - too many global objects
-
-**DESCRIPTION:**
-
-This directive creates a partition of fixed size
-buffers from a physically contiguous memory space which starts
-at starting_address and is length bytes in size. Each allocated
-buffer is to be of ``buffer_size`` in bytes. The assigned
-partition id is returned in ``id``. This partition id is used to
-access the partition with other partition related directives.
-For control and maintenance of the partition, RTEMS allocates a
-PTCB from the local PTCB free pool and initializes it.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The ``starting_address`` must be properly aligned for the
-target architecture.
-
-The ``buffer_size`` parameter must be a multiple of
-the CPU alignment factor. Additionally, ``buffer_size``
-must be large enough to hold two pointers on the target
-architecture. This is required for RTEMS to manage the
-buffers when they are free.
-
-Memory from the partition is not used by RTEMS to
-store the Partition Control Block.
-
-The following partition attribute constants are
-defined by RTEMS:
-
-- ``RTEMS_LOCAL`` - local partition (default)
-
-- ``RTEMS_GLOBAL`` - global partition
-
-The PTCB for a global partition is allocated on the
-local node. The memory space used for the partition must reside
-in shared memory. Partitions should not be made global unless
-remote tasks must interact with the partition. This is to avoid
-the overhead incurred by the creation of a global partition.
-When a global partition is created, the partition’s name and id
-must be transmitted to every node in the system for insertion in
-the local copy of the global object table.
-
-The total number of global objects, including
-partitions, is limited by the maximum_global_objects field in
-the Configuration Table.
-
-PARTITION_IDENT - Get ID of a partition
----------------------------------------
-.. index:: get ID of a partition
-.. index:: obtain ID of a partition
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_partition_ident
-
-.. code:: c
-
- rtems_status_code rtems_partition_ident(
- rtems_name name,
- uint32_t node,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - partition identified successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - partition name not found
-``RTEMS_INVALID_NODE`` - invalid node id
-
-**DESCRIPTION:**
-
-This directive obtains the partition id associated
-with the partition name. If the partition name is not unique,
-then the partition id will match one of the partitions with that
-name. However, this partition id is not guaranteed to
-correspond to the desired partition. The partition id is used
-with other partition related directives to access the partition.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched
-with the local node being searched first. All other nodes are
-searched with the lowest numbered node searched first.
-
-If node is a valid node number which does not
-represent the local node, then only the partitions exported by
-the designated node are searched.
-
-This directive does not generate activity on remote
-nodes. It accesses only the local copy of the global object
-table.
-
-PARTITION_DELETE - Delete a partition
--------------------------------------
-.. index:: delete a partition
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_partition_delete
-
-.. code:: c
-
- rtems_status_code rtems_partition_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - partition deleted successfully
-``RTEMS_INVALID_ID`` - invalid partition id
-``RTEMS_RESOURCE_IN_USE`` - buffers still in use
-``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote partition
-
-**DESCRIPTION:**
-
-This directive deletes the partition specified by id.
-The partition cannot be deleted if any of its buffers are still
-allocated. The PTCB for the deleted partition is reclaimed by
-RTEMS.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The calling task does not have to be the task that
-created the partition. Any local task that knows the partition
-id can delete the partition.
-
-When a global partition is deleted, the partition id
-must be transmitted to every node in the system for deletion
-from the local copy of the global object table.
-
-The partition must reside on the local node, even if
-the partition was created with the ``RTEMS_GLOBAL`` option.
-
-PARTITION_GET_BUFFER - Get buffer from a partition
---------------------------------------------------
-.. index:: get buffer from partition
-.. index:: obtain buffer from partition
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_partition_get_buffer
-
-.. code:: c
-
- rtems_status_code rtems_partition_get_buffer(
- rtems_id id,
- void \**buffer
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - buffer obtained successfully
-``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
-``RTEMS_INVALID_ID`` - invalid partition id
-``RTEMS_UNSATISFIED`` - all buffers are allocated
-
-**DESCRIPTION:**
-
-This directive allows a buffer to be obtained from
-the partition specified in id. The address of the allocated
-buffer is returned in buffer.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-All buffers begin on a four byte boundary.
-
-A task cannot wait on a buffer to become available.
-
-Getting a buffer from a global partition which does
-not reside on the local node will generate a request telling the
-remote node to allocate a buffer from the specified partition.
-
-PARTITION_RETURN_BUFFER - Return buffer to a partition
-------------------------------------------------------
-.. index:: return buffer to partitition
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_partition_return_buffer
-
-.. code:: c
-
- rtems_status_code rtems_partition_return_buffer(
- rtems_id id,
- void \*buffer
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - buffer returned successfully
-``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
-``RTEMS_INVALID_ID`` - invalid partition id
-``RTEMS_INVALID_ADDRESS`` - buffer address not in partition
-
-**DESCRIPTION:**
-
-This directive returns the buffer specified by buffer
-to the partition specified by id.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-Returning a buffer to a global partition which does
-not reside on the local node will generate a request telling the
-remote node to return the buffer to the specified partition.
-
-Returning a buffer multiple times is an error. It will corrupt the internal
-state of the partition.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Region Manager
-##############
-
-.. index:: regions
-
-Introduction
-============
-
-The region manager provides facilities to dynamically
-allocate memory in variable sized units. The directives
-provided by the region manager are:
-
-- ``rtems_region_create`` - Create a region
-
-- ``rtems_region_ident`` - Get ID of a region
-
-- ``rtems_region_delete`` - Delete a region
-
-- ``rtems_region_extend`` - Add memory to a region
-
-- ``rtems_region_get_segment`` - Get segment from a region
-
-- ``rtems_region_return_segment`` - Return segment to a region
-
-- ``rtems_region_get_segment_size`` - Obtain size of a segment
-
-- ``rtems_region_resize_segment`` - Change size of a segment
-
-Background
-==========
-
-Region Manager Definitions
---------------------------
-.. index:: region, definition
-.. index:: segment, definition
-
-A region makes up a physically contiguous memory
-space with user-defined boundaries from which variable-sized
-segments are dynamically allocated and deallocated. A segment
-is a variable size section of memory which is allocated in
-multiples of a user-defined page size. This page size is
-required to be a multiple of four greater than or equal to four.
-For example, if a request for a 350-byte segment is made in a
-region with 256-byte pages, then a 512-byte segment is allocated.
-
-Regions are organized as doubly linked chains of
-variable sized memory blocks. Memory requests are allocated
-using a first-fit algorithm. If available, the requester
-receives the number of bytes requested (rounded up to the next
-page size). RTEMS requires some overhead from the region’s
-memory for each segment that is allocated. Therefore, an
-application should only modify the memory of a segment that has
-been obtained from the region. The application should NOT
-modify the memory outside of any obtained segments and within
-the region’s boundaries while the region is currently active in
-the system.
-
-Upon return to the region, the free block is
-coalesced with its neighbors (if free) on both sides to produce
-the largest possible unused block.
-
-Building an Attribute Set
--------------------------
-.. index:: region attribute set, building
-
-In general, an attribute set is built by a bitwise OR
-of the desired attribute components. The set of valid region
-attributes is provided in the following table:
-
-- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
-
-- ``RTEMS_PRIORITY`` - tasks wait by priority
-
-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. An attribute listed as a default is not
-required to appear in the attribute list, although it is a good
-programming practice to specify default attributes. If all
-defaults are desired, the attribute``RTEMS_DEFAULT_ATTRIBUTES`` should be
-specified on this call.
-
-This example demonstrates the attribute_set parameter
-needed to create a region with the task priority waiting queue
-discipline. The attribute_set parameter to the``rtems_region_create``
-directive should be ``RTEMS_PRIORITY``.
-
-Building an Option Set
-----------------------
-
-In general, an option is built by a bitwise OR of the
-desired option components. The set of valid options for the``rtems_region_get_segment`` directive are
-listed in the following table:
-
-- ``RTEMS_WAIT`` - task will wait for segment (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-Option values are specifically designed to be
-mutually exclusive, therefore bitwise OR and addition operations
-are equivalent as long as each option appears exactly once in
-the component list. An option listed as a default is not
-required to appear in the option list, although it is a good
-programming practice to specify default options. If all
-defaults are desired, the option``RTEMS_DEFAULT_OPTIONS`` should be
-specified on this call.
-
-This example demonstrates the option parameter needed
-to poll for a segment. The option parameter passed to the``rtems_region_get_segment`` directive should
-be ``RTEMS_NO_WAIT``.
-
-Operations
-==========
-
-Creating a Region
------------------
-
-The ``rtems_region_create`` directive creates a region with the
-user-defined name. The user may select FIFO or task priority as
-the method for placing waiting tasks in the task wait queue.
-RTEMS allocates a Region Control Block (RNCB) from the RNCB free
-list to maintain the newly created region. RTEMS also generates
-a unique region ID which is returned to the calling task.
-
-It is not possible to calculate the exact number of
-bytes available to the user since RTEMS requires overhead for
-each segment allocated. For example, a region with one segment
-that is the size of the entire region has more available bytes
-than a region with two segments that collectively are the size
-of the entire region. This is because the region with one
-segment requires only the overhead for one segment, while the
-other region requires the overhead for two segments.
-
-Due to automatic coalescing, the number of segments
-in the region dynamically changes. Therefore, the total
-overhead required by RTEMS dynamically changes.
-
-Obtaining Region IDs
---------------------
-
-When a region is created, RTEMS generates a unique
-region ID and assigns it to the created region until it is
-deleted. The region ID may be obtained by either of two
-methods. First, as the result of an invocation of the``rtems_region_create`` directive,
-the region ID is stored in a user
-provided location. Second, the region ID may be obtained later
-using the ``rtems_region_ident`` directive.
-The region ID is used by other region manager directives to
-access this region.
-
-Adding Memory to a Region
--------------------------
-
-The ``rtems_region_extend`` directive may be used to add memory
-to an existing region. The caller specifies the size in bytes
-and starting address of the memory being added.
-
-NOTE: Please see the release notes or RTEMS source
-code for information regarding restrictions on the location of
-the memory being added in relation to memory already in the
-region.
-
-Acquiring a Segment
--------------------
-
-The ``rtems_region_get_segment`` directive attempts to acquire
-a segment from a specified region. If the region has enough
-available free memory, then a segment is returned successfully
-to the caller. When the segment cannot be allocated, one of the
-following situations applies:
-
-- By default, the calling task will wait forever to acquire the segment.
-
-- Specifying the ``RTEMS_NO_WAIT`` option forces
- an immediate return with an error status code.
-
-- Specifying a timeout limits the interval the task will
- wait before returning with an error status code.
-
-If the task waits for the segment, then it is placed
-in the region’s task wait queue in either FIFO or task priority
-order. All tasks waiting on a region are returned an error when
-the message queue is deleted.
-
-Releasing a Segment
--------------------
-
-When a segment is returned to a region by the``rtems_region_return_segment`` directive, it is merged with its
-unallocated neighbors to form the largest possible segment. The
-first task on the wait queue is examined to determine if its
-segment request can now be satisfied. If so, it is given a
-segment and unblocked. This process is repeated until the first
-task’s segment request cannot be satisfied.
-
-Obtaining the Size of a Segment
--------------------------------
-
-The ``rtems_region_get_segment_size`` directive returns the
-size in bytes of the specified segment. The size returned
-includes any "extra" memory included in the segment because of
-rounding up to a page size boundary.
-
-Changing the Size of a Segment
-------------------------------
-
-The ``rtems_region_resize_segment`` directive is used
-to change the size in bytes of the specified segment. The size may be
-increased or decreased. When increasing the size of a segment, it is
-possible that the request cannot be satisfied. This directive provides
-functionality similar to the ``realloc()`` function in the Standard
-C Library.
-
-Deleting a Region
------------------
-
-A region can be removed from the system and returned
-to RTEMS with the ``rtems_region_delete``
-directive. When a region is
-deleted, its control block is returned to the RNCB free list. A
-region with segments still allocated is not allowed to be
-deleted. Any task attempting to do so will be returned an
-error. As a result of this directive, all tasks blocked waiting
-to obtain a segment from the region will be readied and returned
-a status code which indicates that the region was deleted.
-
-Directives
-==========
-
-This section details the region manager’s directives.
-A subsection is dedicated to each of this manager’s directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-REGION_CREATE - Create a region
--------------------------------
-.. index:: create a region
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_create
-
-.. code:: c
-
- rtems_status_code rtems_region_create(
- rtems_name name,
- void \*starting_address,
- intptr_t length,
- uint32_t page_size,
- rtems_attribute attribute_set,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - region created successfully
-``RTEMS_INVALID_NAME`` - invalid region name
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL
-``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary
-``RTEMS_TOO_MANY`` - too many regions created
-``RTEMS_INVALID_SIZE`` - invalid page size
-
-**DESCRIPTION:**
-
-This directive creates a region from a physically
-contiguous memory space which starts at starting_address and is
-length bytes long. Segments allocated from the region will be a
-multiple of page_size bytes in length. The assigned region id
-is returned in id. This region id is used as an argument to
-other region related directives to access the region.
-
-For control and maintenance of the region, RTEMS
-allocates and initializes an RNCB from the RNCB free pool. Thus
-memory from the region is not used to store the RNCB. However,
-some overhead within the region is required by RTEMS each time a
-segment is constructed in the region.
-
-Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks
-waiting for a segment to be serviced according to task priority.
-Specifying ``RTEMS_FIFO`` in attribute_set or selecting``RTEMS_DEFAULT_ATTRIBUTES`` will cause waiting tasks to
-be serviced in First In-First Out order.
-
-The ``starting_address`` parameter must be aligned on a
-four byte boundary. The ``page_size`` parameter must be a multiple
-of four greater than or equal to eight.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The following region attribute constants are defined
-by RTEMS:
-
-- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
-
-- ``RTEMS_PRIORITY`` - tasks wait by priority
-
-REGION_IDENT - Get ID of a region
----------------------------------
-.. index:: get ID of a region
-.. index:: obtain ID of a region
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_ident
-
-.. code:: c
-
- rtems_status_code rtems_region_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - region identified successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - region name not found
-
-**DESCRIPTION:**
-
-This directive obtains the region id associated with
-the region name to be acquired. If the region name is not
-unique, then the region id will match one of the regions with
-that name. However, this region id is not guaranteed to
-correspond to the desired region. The region id is used to
-access this region in other region manager directives.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
-
-REGION_DELETE - Delete a region
--------------------------------
-.. index:: delete a region
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_delete
-
-.. code:: c
-
- rtems_status_code rtems_region_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - region deleted successfully
-``RTEMS_INVALID_ID`` - invalid region id
-``RTEMS_RESOURCE_IN_USE`` - segments still in use
-
-**DESCRIPTION:**
-
-This directive deletes the region specified by id.
-The region cannot be deleted if any of its segments are still
-allocated. The RNCB for the deleted region is reclaimed by
-RTEMS.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-The calling task does not have to be the task that
-created the region. Any local task that knows the region id can
-delete the region.
-
-REGION_EXTEND - Add memory to a region
---------------------------------------
-.. index:: add memory to a region
-.. index:: region, add memory
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_extend
-
-.. code:: c
-
- rtems_status_code rtems_region_extend(
- rtems_id id,
- void \*starting_address,
- intptr_t length
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - region extended successfully
-``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL
-``RTEMS_INVALID_ID`` - invalid region id
-``RTEMS_INVALID_ADDRESS`` - invalid address of area to add
-
-**DESCRIPTION:**
-
-This directive adds the memory which starts at
-starting_address for length bytes to the region specified by id.
-
-**NOTES:**
-
-This directive will not cause the calling task to be preempted.
-
-The calling task does not have to be the task that
-created the region. Any local task that knows the region id can
-extend the region.
-
-REGION_GET_SEGMENT - Get segment from a region
-----------------------------------------------
-.. index:: get segment from region
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_get_segment
-
-.. code:: c
-
- rtems_status_code rtems_region_get_segment(
- rtems_id id,
- intptr_t size,
- rtems_option option_set,
- rtems_interval timeout,
- void \**segment
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - segment obtained successfully
-``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
-``RTEMS_INVALID_ID`` - invalid region id
-``RTEMS_INVALID_SIZE`` - request is for zero bytes or exceeds
-the size of maximum segment which is possible for this region
-``RTEMS_UNSATISFIED`` - segment of requested size not available
-``RTEMS_TIMEOUT`` - timed out waiting for segment
-``RTEMS_OBJECT_WAS_DELETED`` - region deleted while waiting
-
-**DESCRIPTION:**
-
-This directive obtains a variable size segment from
-the region specified by id. The address of the allocated
-segment is returned in segment. The ``RTEMS_WAIT``
-and ``RTEMS_NO_WAIT`` components
-of the options parameter are used to specify whether the calling
-tasks wish to wait for a segment to become available or return
-immediately if no segment is available. For either option, if a
-sufficiently sized segment is available, then the segment is
-successfully acquired by returning immediately with the``RTEMS_SUCCESSFUL`` status code.
-
-If the calling task chooses to return immediately and
-a segment large enough is not available, then an error code
-indicating this fact is returned. If the calling task chooses
-to wait for the segment and a segment large enough is not
-available, then the calling task is placed on the region’s
-segment wait queue and blocked. If the region was created with
-the ``RTEMS_PRIORITY`` option, then the calling
-task is inserted into the
-wait queue according to its priority. However, if the region
-was created with the ``RTEMS_FIFO`` option, then the calling
-task is placed at the rear of the wait queue.
-
-The timeout parameter specifies the maximum interval
-that a task is willing to wait to obtain a segment. If timeout
-is set to ``RTEMS_NO_TIMEOUT``, then the
-calling task will wait forever.
-
-**NOTES:**
-
-The actual length of the allocated segment may be
-larger than the requested size because a segment size is always
-a multiple of the region’s page size.
-
-The following segment acquisition option constants
-are defined by RTEMS:
-
-- ``RTEMS_WAIT`` - task will wait for segment (default)
-
-- ``RTEMS_NO_WAIT`` - task should not wait
-
-A clock tick is required to support the timeout functionality of
-this directive.
-
-REGION_RETURN_SEGMENT - Return segment to a region
---------------------------------------------------
-.. index:: return segment to region
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_return_segment
-
-.. code:: c
-
- rtems_status_code rtems_region_return_segment(
- rtems_id id,
- void \*segment
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - segment returned successfully
-``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
-``RTEMS_INVALID_ID`` - invalid region id
-``RTEMS_INVALID_ADDRESS`` - segment address not in region
-
-**DESCRIPTION:**
-
-This directive returns the segment specified by
-segment to the region specified by id. The returned segment is
-merged with its neighbors to form the largest possible segment.
-The first task on the wait queue is examined to determine if its
-segment request can now be satisfied. If so, it is given a
-segment and unblocked. This process is repeated until the first
-task’s segment request cannot be satisfied.
-
-**NOTES:**
-
-This directive will cause the calling task to be
-preempted if one or more local tasks are waiting for a segment
-and the following conditions exist:
-
-- a waiting task has a higher priority than the calling task
-
-- the size of the segment required by the waiting task
- is less than or equal to the size of the segment returned.
-
-REGION_GET_SEGMENT_SIZE - Obtain size of a segment
---------------------------------------------------
-.. index:: get size of segment
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_get_segment_size
-
-.. code:: c
-
- rtems_status_code rtems_region_get_segment_size(
- rtems_id id,
- void \*segment,
- ssize_t \*size
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - segment obtained successfully
-``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``size`` is NULL
-``RTEMS_INVALID_ID`` - invalid region id
-``RTEMS_INVALID_ADDRESS`` - segment address not in region
-
-**DESCRIPTION:**
-
-This directive obtains the size in bytes of the specified segment.
-
-**NOTES:**
-
-The actual length of the allocated segment may be
-larger than the requested size because a segment size is always
-a multiple of the region’s page size.
-
-REGION_RESIZE_SEGMENT - Change size of a segment
-------------------------------------------------
-.. index:: resize segment
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_region_resize_segment
-
-.. code:: c
-
- rtems_status_code rtems_region_resize_segment(
- rtems_id id,
- void \*segment,
- ssize_t size,
- ssize_t \*old_size
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - segment obtained successfully
-``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
-``RTEMS_INVALID_ADDRESS`` - ``old_size`` is NULL
-``RTEMS_INVALID_ID`` - invalid region id
-``RTEMS_INVALID_ADDRESS`` - segment address not in region``RTEMS_UNSATISFIED`` - unable to make segment larger
-
-**DESCRIPTION:**
-
-This directive is used to increase or decrease the size of
-a segment. When increasing the size of a segment, it
-is possible that there is not memory available contiguous
-to the segment. In this case, the request is unsatisfied.
-
-**NOTES:**
-
-If an attempt to increase the size of a segment fails, then
-the application may want to allocate a new segment of the desired
-size, copy the contents of the original segment to the new, larger
-segment and then return the original segment.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Dual-Ported Memory Manager
-##########################
-
-.. index:: ports
-.. index:: dual ported memory
-
-Introduction
-============
-
-The dual-ported memory manager provides a mechanism
-for converting addresses between internal and external
-representations for multiple dual-ported memory areas (DPMA).
-The directives provided by the dual-ported memory manager are:
-
-- ``rtems_port_create`` - Create a port
-
-- ``rtems_port_ident`` - Get ID of a port
-
-- ``rtems_port_delete`` - Delete a port
-
-- ``rtems_port_external_to_internal`` - Convert external to internal address
-
-- ``rtems_port_internal_to_external`` - Convert internal to external address
-
-Background
-==========
-.. index:: dual ported memory, definition
-.. index:: external addresses, definition
-.. index:: internal addresses, definition
-
-A dual-ported memory area (DPMA) is an contiguous
-block of RAM owned by a particular processor but which can be
-accessed by other processors in the system. The owner accesses
-the memory using internal addresses, while other processors must
-use external addresses. RTEMS defines a port as a particular
-mapping of internal and external addresses.
-
-There are two system configurations in which
-dual-ported memory is commonly found. The first is
-tightly-coupled multiprocessor computer systems where the
-dual-ported memory is shared between all nodes and is used for
-inter-node communication. The second configuration is computer
-systems with intelligent peripheral controllers. These
-controllers typically utilize the DPMA for high-performance data
-transfers.
-
-Operations
-==========
-
-Creating a Port
----------------
-
-The ``rtems_port_create`` directive creates a port into a DPMA
-with the user-defined name. The user specifies the association
-between internal and external representations for the port being
-created. RTEMS allocates a Dual-Ported Memory Control Block
-(DPCB) from the DPCB free list to maintain the newly created
-DPMA. RTEMS also generates a unique dual-ported memory port ID
-which is returned to the calling task. RTEMS does not
-initialize the dual-ported memory area or access any memory
-within it.
-
-Obtaining Port IDs
-------------------
-
-When a port is created, RTEMS generates a unique port
-ID and assigns it to the created port until it is deleted. The
-port ID may be obtained by either of two methods. First, as the
-result of an invocation of the``rtems_port_create`` directive, the task
-ID is stored in a user provided location. Second, the port ID
-may be obtained later using the``rtems_port_ident`` directive. The port
-ID is used by other dual-ported memory manager directives to
-access this port.
-
-Converting an Address
----------------------
-
-The ``rtems_port_external_to_internal`` directive is used to
-convert an address from external to internal representation for
-the specified port.
-The ``rtems_port_internal_to_external`` directive is
-used to convert an address from internal to external
-representation for the specified port. If an attempt is made to
-convert an address which lies outside the specified DPMA, then
-the address to be converted will be returned.
-
-Deleting a DPMA Port
---------------------
-
-A port can be removed from the system and returned to
-RTEMS with the ``rtems_port_delete`` directive. When a port is deleted,
-its control block is returned to the DPCB free list.
-
-Directives
-==========
-
-This section details the dual-ported memory manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-PORT_CREATE - Create a port
----------------------------
-.. index:: create a port
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_port_create
-
-.. code:: c
-
- rtems_status_code rtems_port_create(
- rtems_name name,
- void \*internal_start,
- void \*external_start,
- uint32_t length,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - port created successfully
-``RTEMS_INVALID_NAME`` - invalid port name
-``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_TOO_MANY`` - too many DP memory areas created
-
-**DESCRIPTION:**
-
-This directive creates a port which resides on the
-local node for the specified DPMA. The assigned port id is
-returned in id. This port id is used as an argument to other
-dual-ported memory manager directives to convert addresses
-within this DPMA.
-
-For control and maintenance of the port, RTEMS
-allocates and initializes an DPCB from the DPCB free pool. Thus
-memory from the dual-ported memory area is not used to store the
-DPCB.
-
-**NOTES:**
-
-The internal_address and external_address parameters
-must be on a four byte boundary.
-
-This directive will not cause the calling task to be
-preempted.
-
-PORT_IDENT - Get ID of a port
------------------------------
-.. index:: get ID of a port
-.. index:: obtain ID of a port
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_port_ident
-
-.. code:: c
-
- rtems_status_code rtems_port_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - port identified successfully
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - port name not found
-
-**DESCRIPTION:**
-
-This directive obtains the port id associated with
-the specified name to be acquired. If the port name is not
-unique, then the port id will match one of the DPMAs with that
-name. However, this port id is not guaranteed to correspond to
-the desired DPMA. The port id is used to access this DPMA in
-other dual-ported memory area related directives.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-PORT_DELETE - Delete a port
----------------------------
-.. index:: delete a port
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_port_delete
-
-.. code:: c
-
- rtems_status_code rtems_port_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - port deleted successfully
-``RTEMS_INVALID_ID`` - invalid port id
-
-**DESCRIPTION:**
-
-This directive deletes the dual-ported memory area
-specified by id. The DPCB for the deleted dual-ported memory
-area is reclaimed by RTEMS.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-The calling task does not have to be the task that
-created the port. Any local task that knows the port id can
-delete the port.
-
-PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
-----------------------------------------------------------------
-.. index:: convert external to internal address
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_port_external_to_internal
-
-.. code:: c
-
- rtems_status_code rtems_port_external_to_internal(
- rtems_id id,
- void \*external,
- void \**internal
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_INVALID_ADDRESS`` - ``internal`` is NULL
-``RTEMS_SUCCESSFUL`` - successful conversion
-
-**DESCRIPTION:**
-
-This directive converts a dual-ported memory address
-from external to internal representation for the specified port.
-If the given external address is invalid for the specified
-port, then the internal address is set to the given external
-address.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the calling task to be
-preempted.
-
-PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
-----------------------------------------------------------------
-.. index:: convert internal to external address
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_port_internal_to_external
-
-.. code:: c
-
- rtems_status_code rtems_port_internal_to_external(
- rtems_id id,
- void \*internal,
- void \**external
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_INVALID_ADDRESS`` - ``external`` is NULL
-``RTEMS_SUCCESSFUL`` - successful conversion
-
-**DESCRIPTION:**
-
-This directive converts a dual-ported memory address
-from internal to external representation so that it can be
-passed to owner of the DPMA represented by the specified port.
-If the given internal address is an invalid dual-ported address,
-then the external address is set to the given internal address.
-
-**NOTES:**
-
-This directive is callable from an ISR.
-
-This directive will not cause the calling task to be
-preempted.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-I/O Manager
-###########
-
-.. index:: device drivers
-.. index:: IO Manager
-
-Introduction
-============
-
-The input/output interface manager provides a
-well-defined mechanism for accessing device drivers and a
-structured methodology for organizing device drivers. The
-directives provided by the I/O manager are:
-
-- ``rtems_io_initialize`` - Initialize a device driver
-
-- ``rtems_io_register_driver`` - Register a device driver
-
-- ``rtems_io_unregister_driver`` - Unregister a device driver
-
-- ``rtems_io_register_name`` - Register a device name
-
-- ``rtems_io_lookup_name`` - Look up a device name
-
-- ``rtems_io_open`` - Open a device
-
-- ``rtems_io_close`` - Close a device
-
-- ``rtems_io_read`` - Read from a device
-
-- ``rtems_io_write`` - Write to a device
-
-- ``rtems_io_control`` - Special device services
-
-Background
-==========
-
-Device Driver Table
--------------------
-.. index:: Device Driver Table
-
-Each application utilizing the RTEMS I/O manager must specify the
-address of a Device Driver Table in its Configuration Table. This table
-contains each device driver’s entry points that is to be initialised by
-RTEMS during initialization. Each device driver may contain the
-following entry points:
-
-- Initialization
-
-- Open
-
-- Close
-
-- Read
-
-- Write
-
-- Control
-
-If the device driver does not support a particular
-entry point, then that entry in the Configuration Table should
-be NULL. RTEMS will return``RTEMS_SUCCESSFUL`` as the executive’s and
-zero (0) as the device driver’s return code for these device
-driver entry points.
-
-Applications can register and unregister drivers with the RTEMS I/O
-manager avoiding the need to have all drivers statically defined and
-linked into this table.
-
-The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures
-the number of driver slots available to the application.
-
-Major and Minor Device Numbers
-------------------------------
-.. index:: major device number
-.. index:: minor device number
-
-Each call to the I/O manager must provide a device’s
-major and minor numbers as arguments. The major number is the
-index of the requested driver’s entry points in the Device
-Driver Table, and is used to select a specific device driver.
-The exact usage of the minor number is driver specific, but is
-commonly used to distinguish between a number of devices
-controlled by the same driver... index:: rtems_device_major_number
-.. index:: rtems_device_minor_number
-
-The data types ``rtems_device_major_number`` and``rtems_device_minor_number`` are used to
-manipulate device major and minor numbers, respectively.
-
-Device Names
-------------
-.. index:: device names
-
-The I/O Manager provides facilities to associate a
-name with a particular device. Directives are provided to
-register the name of a device and to look up the major/minor
-number pair associated with a device name.
-
-Device Driver Environment
--------------------------
-
-Application developers, as well as device driver
-developers, must be aware of the following regarding the RTEMS
-I/O Manager:
-
-- A device driver routine executes in the context of the
- invoking task. Thus if the driver blocks, the invoking task
- blocks.
-
-- The device driver is free to change the modes of the
- invoking task, although the driver should restore them to their
- original values.
-
-- Device drivers may be invoked from ISRs.
-
-- Only local device drivers are accessible through the I/O
- manager.
-
-- A device driver routine may invoke all other RTEMS
- directives, including I/O directives, on both local and global
- objects.
-
-Although the RTEMS I/O manager provides a framework
-for device drivers, it makes no assumptions regarding the
-construction or operation of a device driver.
-
-Runtime Driver Registration
----------------------------
-.. index:: runtime driver registration
-
-Board support package and application developers can select wether a
-device driver is statically entered into the default device table or
-registered at runtime.
-
-Dynamic registration helps applications where:
-
-# The BSP and kernel libraries are common to a range of applications
- for a specific target platform. An application may be built upon a
- common library with all drivers. The application selects and registers
- the drivers. Uniform driver name lookup protects the application.
-
-# The type and range of drivers may vary as the application probes a
- bus during initialization.
-
-# Support for hot swap bus system such as Compact PCI.
-
-# Support for runtime loadable driver modules.
-
-Device Driver Interface
------------------------
-.. index:: device driver interface
-
-When an application invokes an I/O manager directive,
-RTEMS determines which device driver entry point must be
-invoked. The information passed by the application to RTEMS is
-then passed to the correct device driver entry point. RTEMS
-will invoke each device driver entry point assuming it is
-compatible with the following prototype:
-.. code:: c
-
- rtems_device_driver io_entry(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument_block
- );
-
-The format and contents of the parameter block are
-device driver and entry point dependent.
-
-It is recommended that a device driver avoid
-generating error codes which conflict with those used by
-application components. A common technique used to generate
-driver specific error codes is to make the most significant part
-of the status indicate a driver specific code.
-
-Device Driver Initialization
-----------------------------
-
-RTEMS automatically initializes all device drivers
-when multitasking is initiated via the``rtems_initialize_executive``
-directive. RTEMS initializes the device drivers by invoking
-each device driver initialization entry point with the following
-parameters:
-
-major
- the major device number for this device driver.
-
-minor
- zero.
-
-argument_block
- will point to the Configuration Table.
-
-The returned status will be ignored by RTEMS. If the driver
-cannot successfully initialize the device, then it should invoke
-the fatal_error_occurred directive.
-
-Operations
-==========
-
-Register and Lookup Name
-------------------------
-
-The ``rtems_io_register`` directive associates a name with the
-specified device (i.e. major/minor number pair). Device names
-are typically registered as part of the device driver
-initialization sequence. The ``rtems_io_lookup``
-directive is used to
-determine the major/minor number pair associated with the
-specified device name. The use of these directives frees the
-application from being dependent on the arbitrary assignment of
-major numbers in a particular application. No device naming
-conventions are dictated by RTEMS.
-
-Accessing an Device Driver
---------------------------
-
-The I/O manager provides directives which enable the
-application program to utilize device drivers in a standard
-manner. There is a direct correlation between the RTEMS I/O
-manager directives``rtems_io_initialize``,``rtems_io_open``,``rtems_io_close``,``rtems_io_read``,``rtems_io_write``, and``rtems_io_control``
-and the underlying device driver entry points.
-
-Directives
-==========
-
-This section details the I/O manager’s directives. A
-subsection is dedicated to each of this manager’s directives and
-describes the calling sequence, related constants, usage, and
-status codes.
-
-IO_REGISTER_DRIVER - Register a device driver
----------------------------------------------
-.. index:: register a device driver
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_register_driver
-
-.. code:: c
-
- rtems_status_code rtems_io_register_driver(
- rtems_device_major_number major,
- rtems_driver_address_table \*driver_table,
- rtems_device_major_number \*registered_major
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully registered
-``RTEMS_INVALID_ADDRESS`` - invalid registered major pointer
-``RTEMS_INVALID_ADDRESS`` - invalid driver table
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-``RTEMS_TOO_MANY`` - no available major device table slot
-``RTEMS_RESOURCE_IN_USE`` - major device number entry in use
-
-**DESCRIPTION:**
-
-This directive attempts to add a new device driver to the Device Driver
-Table. The user can specify a specific major device number via the
-directive’s ``major`` parameter, or let the registration routine find
-the next available major device number by specifing a major number of``0``. The selected major device number is returned via the``registered_major`` directive parameter. The directive automatically
-allocation major device numbers from the highest value down.
-
-This directive automatically invokes the IO_INITIALIZE directive if
-the driver address table has an initialization and open entry.
-
-The directive returns RTEMS_TOO_MANY if Device Driver Table is
-full, and RTEMS_RESOURCE_IN_USE if a specific major device
-number is requested and it is already in use.
-
-**NOTES:**
-
-The Device Driver Table size is specified in the Configuration Table
-condiguration. This needs to be set to maximum size the application
-requires.
-
-IO_UNREGISTER_DRIVER - Unregister a device driver
--------------------------------------------------
-.. index:: unregister a device driver
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_unregister_driver
-
-.. code:: c
-
- rtems_status_code rtems_io_unregister_driver(
- rtems_device_major_number major
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully registered
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive removes a device driver from the Device Driver Table.
-
-**NOTES:**
-
-Currently no specific checks are made and the driver is not closed.
-
-IO_INITIALIZE - Initialize a device driver
-------------------------------------------
-.. index:: initialize a device driver
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_initialize
-
-.. code:: c
-
- rtems_status_code rtems_io_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive calls the device driver initialization
-routine specified in the Device Driver Table for this major
-number. This directive is automatically invoked for each device
-driver when multitasking is initiated via the
-initialize_executive directive.
-
-A device driver initialization module is responsible
-for initializing all hardware and data structures associated
-with a device. If necessary, it can allocate memory to be used
-during other operations.
-
-**NOTES:**
-
-This directive may or may not cause the calling task
-to be preempted. This is dependent on the device driver being
-initialized.
-
-IO_REGISTER_NAME - Register a device
-------------------------------------
-.. index:: register device
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_register_name
-
-.. code:: c
-
- rtems_status_code rtems_io_register_name(
- const char \*name,
- rtems_device_major_number major,
- rtems_device_minor_number minor
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_TOO_MANY`` - too many devices registered
-
-**DESCRIPTION:**
-
-This directive associates name with the specified
-major/minor number pair.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-IO_LOOKUP_NAME - Lookup a device
---------------------------------
-.. index:: lookup device major and minor number
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_lookup_name
-
-.. code:: c
-
- rtems_status_code rtems_io_lookup_name(
- const char \*name,
- rtems_driver_name_t \*device_info
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_UNSATISFIED`` - name not registered
-
-**DESCRIPTION:**
-
-This directive returns the major/minor number pair
-associated with the given device name in ``device_info``.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-IO_OPEN - Open a device
------------------------
-.. index:: open a devive
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_open
-
-.. code:: c
-
- rtems_status_code rtems_io_open(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive calls the device driver open routine
-specified in the Device Driver Table for this major number. The
-open entry point is commonly used by device drivers to provide
-exclusive access to a device.
-
-**NOTES:**
-
-This directive may or may not cause the calling task
-to be preempted. This is dependent on the device driver being
-invoked.
-
-IO_CLOSE - Close a device
--------------------------
-.. index:: close a device
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_close
-
-.. code:: c
-
- rtems_status_code rtems_io_close(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive calls the device driver close routine
-specified in the Device Driver Table for this major number. The
-close entry point is commonly used by device drivers to
-relinquish exclusive access to a device.
-
-**NOTES:**
-
-This directive may or may not cause the calling task
-to be preempted. This is dependent on the device driver being
-invoked.
-
-IO_READ - Read from a device
-----------------------------
-.. index:: read from a device
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_read
-
-.. code:: c
-
- rtems_status_code rtems_io_read(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive calls the device driver read routine
-specified in the Device Driver Table for this major number.
-Read operations typically require a buffer address as part of
-the argument parameter block. The contents of this buffer will
-be replaced with data from the device.
-
-**NOTES:**
-
-This directive may or may not cause the calling task
-to be preempted. This is dependent on the device driver being
-invoked.
-
-IO_WRITE - Write to a device
-----------------------------
-.. index:: write to a device
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_write
-
-.. code:: c
-
- rtems_status_code rtems_io_write(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive calls the device driver write routine
-specified in the Device Driver Table for this major number.
-Write operations typically require a buffer address as part of
-the argument parameter block. The contents of this buffer will
-be sent to the device.
-
-**NOTES:**
-
-This directive may or may not cause the calling task
-to be preempted. This is dependent on the device driver being
-invoked.
-
-IO_CONTROL - Special device services
-------------------------------------
-.. index:: special device services
-.. index:: IO Control
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_io_control
-
-.. code:: c
-
- rtems_status_code rtems_io_control(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void \*argument
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successfully initialized
-``RTEMS_INVALID_NUMBER`` - invalid major device number
-
-**DESCRIPTION:**
-
-This directive calls the device driver I/O control
-routine specified in the Device Driver Table for this major
-number. The exact functionality of the driver entry called by
-this directive is driver dependent. It should not be assumed
-that the control entries of two device drivers are compatible.
-For example, an RS-232 driver I/O control operation may change
-the baud rate of a serial line, while an I/O control operation
-for a floppy disk driver may cause a seek operation.
-
-**NOTES:**
-
-This directive may or may not cause the calling task
-to be preempted. This is dependent on the device driver being
-invoked.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Fatal Error Manager
-###################
-
-.. index:: fatal errors
-
-Introduction
-============
-
-The fatal error manager processes all fatal or irrecoverable errors and other
-sources of system termination (for example after exit()). The directives
-provided by the fatal error manager are:
-
-- ``rtems_fatal_error_occurred`` - Invoke the fatal error handler
-
-- ``rtems_fatal`` - Invoke the fatal error handler with error source
-
-Background
-==========
-.. index:: fatal error detection
-.. index:: fatal error processing
-.. index:: fatal error user extension
-
-The fatal error manager is called upon detection of
-an irrecoverable error condition by either RTEMS or the
-application software. Fatal errors can be detected from three
-sources:
-
-- the executive (RTEMS)
-
-- user system code
-
-- user application code
-
-RTEMS automatically invokes the fatal error manager
-upon detection of an error it considers to be fatal. Similarly,
-the user should invoke the fatal error manager upon detection of
-a fatal error.
-
-Each static or dynamic user extension set may include
-a fatal error handler. The fatal error handler in the static
-extension set can be used to provide access to debuggers and
-monitors which may be present on the target hardware. If any
-user-supplied fatal error handlers are installed, the fatal
-error manager will invoke them. If no user handlers are
-configured or if all the user handler return control to the
-fatal error manager, then the RTEMS default fatal error handler
-is invoked. If the default fatal error handler is invoked, then
-the system state is marked as failed.
-
-Although the precise behavior of the default fatal
-error handler is processor specific, in general, it will disable
-all maskable interrupts, place the error code in a known
-processor dependent place (generally either on the stack or in a
-register), and halt the processor. The precise actions of the
-RTEMS fatal error are discussed in the Default Fatal Error
-Processing chapter of the Applications Supplement document for
-a specific target processor.
-
-Operations
-==========
-
-
-Announcing a Fatal Error
-------------------------
-.. index:: _Internal_errors_What_happened
-
-The ``rtems_fatal_error_occurred`` directive is invoked when a
-fatal error is detected. Before invoking any user-supplied
-fatal error handlers or the RTEMS fatal error handler, the``rtems_fatal_error_occurred``
-directive stores useful information in the
-variable ``_Internal_errors_What_happened``. This structure
-contains three pieces of information:
-
-- the source of the error (API or executive core),
-
-- whether the error was generated internally by the
- executive, and a
-
-- a numeric code to indicate the error type.
-
-The error type indicator is dependent on the source
-of the error and whether or not the error was internally
-generated by the executive. If the error was generated
-from an API, then the error code will be of that API’s
-error or status codes. The status codes for the RTEMS
-API are in cpukit/rtems/include/rtems/rtems/status.h. Those
-for the POSIX API can be found in <errno.h>.
-
-The ``rtems_fatal_error_occurred`` directive is responsible
-for invoking an optional user-supplied fatal error handler
-and/or the RTEMS fatal error handler. All fatal error handlers
-are passed an error code to describe the error detected.
-
-Occasionally, an application requires more
-sophisticated fatal error processing such as passing control to
-a debugger. For these cases, a user-supplied fatal error
-handler can be specified in the RTEMS configuration table. The
-User Extension Table field fatal contains the address of the
-fatal error handler to be executed when the``rtems_fatal_error_occurred``
-directive is called. If the field is set to NULL or if the
-configured fatal error handler returns to the executive, then
-the default handler provided by RTEMS is executed. This default
-handler will halt execution on the processor where the error
-occurred.
-
-Directives
-==========
-
-This section details the fatal error manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-FATAL_ERROR_OCCURRED - Invoke the fatal error handler
------------------------------------------------------
-.. index:: announce fatal error
-.. index:: fatal error, announce
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_fatal_error_occurred
-
-.. code:: c
-
- void rtems_fatal_error_occurred(
- uint32_t the_error
- );
-
-**DIRECTIVE STATUS CODES**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive processes fatal errors. If the FATAL
-error extension is defined in the configuration table, then the
-user-defined error extension is called. If configured and the
-provided FATAL error extension returns, then the RTEMS default
-error handler is invoked. This directive can be invoked by
-RTEMS or by the user’s application code including initialization
-tasks, other tasks, and ISRs.
-
-**NOTES:**
-
-This directive supports local operations only.
-
-Unless the user-defined error extension takes special
-actions such as restarting the calling task, this directive WILL
-NOT RETURN to the caller.
-
-The user-defined extension for this directive may
-wish to initiate a global shutdown.
-
-FATAL - Invoke the fatal error handler with error source
---------------------------------------------------------
-.. index:: announce fatal error
-.. index:: fatal error, announce
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_fatal
-
-.. code:: c
-
- void rtems_fatal(
- rtems_fatal_source source,
- rtems_fatal_code error
- );
-
-**DIRECTIVE STATUS CODES**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive invokes the internal error handler with is internal set to
-false. See also ``rtems_fatal_error_occurred``.
-
-EXCEPTION_FRAME_PRINT - Prints the exception frame
---------------------------------------------------
-.. index:: exception frame
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_exception_frame_print
-
-.. code:: c
-
- void rtems_exception_frame_print(
- const rtems_exception_frame \*frame
- );
-
-**DIRECTIVE STATUS CODES**
-
-NONE
-
-**DESCRIPTION:**
-
-Prints the exception frame via printk().
-
-FATAL_SOURCE_TEXT - Returns a text for a fatal source
------------------------------------------------------
-.. index:: fatal error
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_fatal_source_text
-
-.. code:: c
-
- const char \*rtems_fatal_source_text(
- rtems_fatal_source source
- );
-
-**DIRECTIVE STATUS CODES**
-
-The fatal source text or "?" in case the passed fatal source is invalid.
-
-**DESCRIPTION:**
-
-Returns a text for a fatal source. The text for fatal source is the enumerator
-constant.
-
-INTERNAL_ERROR_TEXT - Returns a text for an internal error code
----------------------------------------------------------------
-.. index:: fatal error
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_internal_error_text
-
-.. code:: c
-
- const char \*rtems_internal_error_text(
- rtems_fatal_code error
- );
-
-**DIRECTIVE STATUS CODES**
-
-The error code text or "?" in case the passed error code is invalid.
-
-**DESCRIPTION:**
-
-Returns a text for an internal error code. The text for each internal error
-code is the enumerator constant.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Board Support Packages
-######################
-
-.. index:: Board Support Packages
-.. index:: BSPs
-
-Introduction
-============
-.. index:: BSP, definition
-
-A board support package (BSP) is a collection of
-user-provided facilities which interface RTEMS and an
-application with a specific hardware platform. These facilities
-may include hardware initialization, device drivers, user
-extensions, and a Multiprocessor Communications Interface
-(MPCI). However, a minimal BSP need only support processor
-reset and initialization and, if needed, a clock tick.
-
-Reset and Initialization
-========================
-
-An RTEMS based application is initiated or
-re-initiated when the processor is reset. This initialization
-code is responsible for preparing the target platform for the
-RTEMS application. Although the exact actions performed by the
-initialization code are highly processor and target dependent,
-the logical functionality of these actions are similar across a
-variety of processors and target platforms.
-
-Normally, the BSP and some of the application initialization is
-intertwined in the RTEMS initialization sequence controlled by
-the shared function ``boot_card()``.
-
-The reset application initialization code is executed
-first when the processor is reset. All of the hardware must be
-initialized to a quiescent state by this software before
-initializing RTEMS. When in quiescent state, devices do not
-generate any interrupts or require any servicing by the
-application. Some of the hardware components may be initialized
-in this code as well as any application initialization that does
-not involve calls to RTEMS directives.
-
-The processor’s Interrupt Vector Table which will be used by the
-application may need to be set to the required value by the reset
-application initialization code. Because interrupts are enabled
-automatically by RTEMS as part of the context switch to the first task,
-the Interrupt Vector Table MUST be set before this directive is invoked
-to ensure correct interrupt vectoring. The processor’s Interrupt Vector
-Table must be accessible by RTEMS as it will be modified by the when
-installing user Interrupt Service Routines (ISRs) On some CPUs, RTEMS
-installs it’s own Interrupt Vector Table as part of initialization and
-thus these requirements are met automatically. The reset code which is
-executed before the call to any RTEMS initialization routines has the
-following requirements:
-
-- Must not make any blocking RTEMS directive calls.
-
-- If the processor supports multiple privilege levels, must leave
- the processor in the most privileged, or supervisory, state.
-
-- Must allocate a stack of sufficient size to execute the initialization
- and shutdown of the system. This stack area will NOT be used by any task
- once the system is initialized. This stack is often reserved via the
- linker script or in the assembly language start up file.
-
-- Must initialize the stack pointer for the initialization process to
- that allocated.
-
-- Must initialize the processor’s Interrupt Vector Table.
-
-- Must disable all maskable interrupts.
-
-- If the processor supports a separate interrupt stack, must allocate
- the interrupt stack and initialize the interrupt stack pointer.
-
-At the end of the initialization sequence, RTEMS does not return to the
-BSP initialization code, but instead context switches to the highest
-priority task to begin application execution. This task is typically
-a User Initialization Task which is responsible for performing both
-local and global application initialization which is dependent on RTEMS
-facilities. It is also responsible for initializing any higher level
-RTEMS services the application uses such as networking and blocking
-device drivers.
-
-Interrupt Stack Requirements
-----------------------------
-
-The worst-case stack usage by interrupt service
-routines must be taken into account when designing an
-application. If the processor supports interrupt nesting, the
-stack usage must include the deepest nest level. The worst-case
-stack usage must account for the following requirements:
-
-- Processor’s interrupt stack frame
-
-- Processor’s subroutine call stack frame
-
-- RTEMS system calls
-
-- Registers saved on stack
-
-- Application subroutine calls
-
-The size of the interrupt stack must be greater than or equal to the
-confugured minimum stack size.
-
-Processors with a Separate Interrupt Stack
-------------------------------------------
-
-Some processors support a separate stack for interrupts. When an
-interrupt is vectored and the interrupt is not nested, the processor
-will automatically switch from the current stack to the interrupt stack.
-The size of this stack is based solely on the worst-case stack usage by
-interrupt service routines.
-
-The dedicated interrupt stack for the entire application on some
-architectures is supplied and initialized by the reset and initialization
-code of the user’s Board Support Package. Whether allocated and
-initialized by the BSP or RTEMS, since all ISRs use this stack, the
-stack size must take into account the worst case stack usage by any
-combination of nested ISRs.
-
-Processors Without a Separate Interrupt Stack
----------------------------------------------
-
-Some processors do not support a separate stack for interrupts. In this
-case, without special assistance every task’s stack must include
-enough space to handle the task’s worst-case stack usage as well as
-the worst-case interrupt stack usage. This is necessary because the
-worst-case interrupt nesting could occur while any task is executing.
-
-On many processors without dedicated hardware managed interrupt stacks,
-RTEMS manages a dedicated interrupt stack in software. If this capability
-is supported on a CPU, then it is logically equivalent to the processor
-supporting a separate interrupt stack in hardware.
-
-Device Drivers
-==============
-
-Device drivers consist of control software for
-special peripheral devices and provide a logical interface for
-the application developer. The RTEMS I/O manager provides
-directives which allow applications to access these device
-drivers in a consistent fashion. A Board Support Package may
-include device drivers to access the hardware on the target
-platform. These devices typically include serial and parallel
-ports, counter/timer peripherals, real-time clocks, disk
-interfaces, and network controllers.
-
-For more information on device drivers, refer to the
-I/O Manager chapter.
-
-Clock Tick Device Driver
-------------------------
-
-Most RTEMS applications will include a clock tick
-device driver which invokes the ``rtems_clock_tick``
-directive at regular intervals. The clock tick is necessary if
-the application is to utilize timeslicing, the clock manager, the
-timer manager, the rate monotonic manager, or the timeout option on blocking
-directives.
-
-The clock tick is usually provided as an interrupt from a counter/timer
-or a real-time clock device. When a counter/timer is used to provide the
-clock tick, the device is typically programmed to operate in continuous
-mode. This mode selection causes the device to automatically reload the
-initial count and continue the countdown without programmer intervention.
-This reduces the overhead required to manipulate the counter/timer in
-the clock tick ISR and increases the accuracy of tick occurrences.
-The initial count can be based on the microseconds_per_tick field
-in the RTEMS Configuration Table. An alternate approach is to set
-the initial count for a fixed time period (such as one millisecond)
-and have the ISR invoke ``rtems_clock_tick`` on the
-configured ``microseconds_per_tick`` boundaries. Obviously, this
-can induce some error if the configured ``microseconds_per_tick``
-is not evenly divisible by the chosen clock interrupt quantum.
-
-It is important to note that the interval between
-clock ticks directly impacts the granularity of RTEMS timing
-operations. In addition, the frequency of clock ticks is an
-important factor in the overall level of system overhead. A
-high clock tick frequency results in less processor time being
-available for task execution due to the increased number of
-clock tick ISRs.
-
-User Extensions
-===============
-
-RTEMS allows the application developer to augment
-selected features by invoking user-supplied extension routines
-when the following system events occur:
-
-- Task creation
-
-- Task initiation
-
-- Task reinitiation
-
-- Task deletion
-
-- Task context switch
-
-- Post task context switch
-
-- Task begin
-
-- Task exits
-
-- Fatal error detection
-
-User extensions can be used to implement a wide variety of
-functions including execution profiling, non-standard
-coprocessor support, debug support, and error detection and
-recovery. For example, the context of a non-standard numeric
-coprocessor may be maintained via the user extensions. In this
-example, the task creation and deletion extensions are
-responsible for allocating and deallocating the context area,
-the task initiation and reinitiation extensions would be
-responsible for priming the context area, and the task context
-switch extension would save and restore the context of the
-device.
-
-For more information on user extensions, refer to `User Extensions Manager`_.
-
-Multiprocessor Communications Interface (MPCI)
-==============================================
-
-RTEMS requires that an MPCI layer be provided when a
-multiple node application is developed. This MPCI layer must
-provide an efficient and reliable communications mechanism
-between the multiple nodes. Tasks on different nodes
-communicate and synchronize with one another via the MPCI. Each
-MPCI layer must be tailored to support the architecture of the
-target platform.
-
-For more information on the MPCI, refer to the
-Multiprocessing Manager chapter.
-
-Tightly-Coupled Systems
------------------------
-
-A tightly-coupled system is a multiprocessor
-configuration in which the processors communicate solely via
-shared global memory. The MPCI can simply place the RTEMS
-packets in the shared memory space. The two primary
-considerations when designing an MPCI for a tightly-coupled
-system are data consistency and informing another node of a
-packet.
-
-The data consistency problem may be solved using
-atomic "test and set" operations to provide a "lock" in the
-shared memory. It is important to minimize the length of time
-any particular processor locks a shared data structure.
-
-The problem of informing another node of a packet can
-be addressed using one of two techniques. The first technique
-is to use an interprocessor interrupt capability to cause an
-interrupt on the receiving node. This technique requires that
-special support hardware be provided by either the processor
-itself or the target platform. The second technique is to have
-a node poll for arrival of packets. The drawback to this
-technique is the overhead associated with polling.
-
-Loosely-Coupled Systems
------------------------
-
-A loosely-coupled system is a multiprocessor
-configuration in which the processors communicate via some type
-of communications link which is not shared global memory. The
-MPCI sends the RTEMS packets across the communications link to
-the destination node. The characteristics of the communications
-link vary widely and have a significant impact on the MPCI
-layer. For example, the bandwidth of the communications link
-has an obvious impact on the maximum MPCI throughput.
-
-The characteristics of a shared network, such as
-Ethernet, lend themselves to supporting an MPCI layer. These
-networks provide both the point-to-point and broadcast
-capabilities which are expected by RTEMS.
-
-Systems with Mixed Coupling
----------------------------
-
-A mixed-coupling system is a multiprocessor
-configuration in which the processors communicate via both
-shared memory and communications links. A unique characteristic
-of mixed-coupling systems is that a node may not have access to
-all communication methods. There may be multiple shared memory
-areas and communication links. Therefore, one of the primary
-functions of the MPCI layer is to efficiently route RTEMS
-packets between nodes. This routing may be based on numerous
-algorithms. In addition, the router may provide alternate
-communications paths in the event of an overload or a partial
-failure.
-
-Heterogeneous Systems
----------------------
-
-Designing an MPCI layer for a heterogeneous system
-requires special considerations by the developer. RTEMS is
-designed to eliminate many of the problems associated with
-sharing data in a heterogeneous environment. The MPCI layer
-need only address the representation of thirty-two (32) bit
-unsigned quantities.
-
-For more information on supporting a heterogeneous
-system, refer the Supporting Heterogeneous Environments in the
-Multiprocessing Manager chapter.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-
-User Extensions Manager
-#######################
-
-.. index:: user extensions
-
-Introduction
-============
-
-The RTEMS User Extensions Manager allows the
-application developer to augment the executive by allowing them
-to supply extension routines which are invoked at critical
-system events. The directives provided by the user extensions
-manager are:
-
-- ``rtems_extension_create`` - Create an extension set
-
-- ``rtems_extension_ident`` - Get ID of an extension set
-
-- ``rtems_extension_delete`` - Delete an extension set
-
-Background
-==========
-
-User extension routines are invoked when the
-following system events occur:
-
-- Task creation
-
-- Task initiation
-
-- Task reinitiation
-
-- Task deletion
-
-- Task context switch
-
-- Post task context switch
-
-- Task begin
-
-- Task exits
-
-- Fatal error detection
-
-These extensions are invoked as a function with
-arguments that are appropriate to the system event.
-
-Extension Sets
---------------
-.. index:: extension set
-
-An extension set is defined as a set of routines
-which are invoked at each of the critical system events at which
-user extension routines are invoked. Together a set of these
-routines typically perform a specific functionality such as
-performance monitoring or debugger support. RTEMS is informed of
-the entry points which constitute an extension set via the
-following structure:.. index:: rtems_extensions_table
-
-.. code:: c
-
- typedef struct {
- rtems_task_create_extension thread_create;
- rtems_task_start_extension thread_start;
- rtems_task_restart_extension thread_restart;
- rtems_task_delete_extension thread_delete;
- rtems_task_switch_extension thread_switch;
- rtems_task_begin_extension thread_begin;
- rtems_task_exitted_extension thread_exitted;
- rtems_fatal_extension fatal;
- } rtems_extensions_table;
-
-RTEMS allows the user to have multiple extension sets
-active at the same time. First, a single static extension set
-may be defined as the application’s User Extension Table which
-is included as part of the Configuration Table. This extension
-set is active for the entire life of the system and may not be
-deleted. This extension set is especially important because it
-is the only way the application can provided a FATAL error
-extension which is invoked if RTEMS fails during the
-initialize_executive directive. The static extension set is
-optional and may be configured as NULL if no static extension
-set is required.
-
-Second, the user can install dynamic extensions using
-the ``rtems_extension_create``
-directive. These extensions are RTEMS
-objects in that they have a name, an ID, and can be dynamically
-created and deleted. In contrast to the static extension set,
-these extensions can only be created and installed after the
-initialize_executive directive successfully completes execution.
-Dynamic extensions are useful for encapsulating the
-functionality of an extension set. For example, the application
-could use extensions to manage a special coprocessor, do
-performance monitoring, and to do stack bounds checking. Each
-of these extension sets could be written and installed
-independently of the others.
-
-All user extensions are optional and RTEMS places no
-naming restrictions on the user. The user extension entry points
-are copied into an internal RTEMS structure. This means the user
-does not need to keep the table after creating it, and changing the
-handler entry points dynamically in a table once created has no
-effect. Creating a table local to a function can save space in
-space limited applications.
-
-Extension switches do not effect the context switch overhead if
-no switch handler is installed.
-
-TCB Extension Area
-------------------
-.. index:: TCB extension area
-
-RTEMS provides for a pointer to a user-defined data
-area for each extension set to be linked to each task’s control
-block. This set of pointers is an extension of the TCB and can
-be used to store additional data required by the user’s
-extension functions.
-
-The TCB extension is an array of pointers in the TCB. The
-index into the table can be obtained from the extension id
-returned when the extension is created:.. index:: rtems extensions table index
-
-.. code:: c
-
- index = rtems_object_id_get_index(extension_id);
-
-The number of pointers in the area is the same as the number of
-user extension sets configured. This allows an application to
-augment the TCB with user-defined information. For example, an
-application could implement task profiling by storing timing
-statistics in the TCB’s extended memory area. When a task
-context switch is being executed, the TASK_SWITCH extension
-could read a real-time clock to calculate how long the task
-being swapped out has run as well as timestamp the starting time
-for the task being swapped in.
-
-If used, the extended memory area for the TCB should
-be allocated and the TCB extension pointer should be set at the
-time the task is created or started by either the TASK_CREATE or
-TASK_START extension. The application is responsible for
-managing this extended memory area for the TCBs. The memory may
-be reinitialized by the TASK_RESTART extension and should be
-deallocated by the TASK_DELETE extension when the task is
-deleted. Since the TCB extension buffers would most likely be
-of a fixed size, the RTEMS partition manager could be used to
-manage the application’s extended memory area. The application
-could create a partition of fixed size TCB extension buffers and
-use the partition manager’s allocation and deallocation
-directives to obtain and release the extension buffers.
-
-Extensions
-----------
-
-The sections that follow will contain a description
-of each extension. Each section will contain a prototype of a
-function with the appropriate calling sequence for the
-corresponding extension. The names given for the C
-function and
-its arguments are all defined by the user. The names used in
-the examples were arbitrarily chosen and impose no naming
-conventions on the user.
-
-TASK_CREATE Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The TASK_CREATE extension directly corresponds to the``rtems_task_create`` directive. If this extension
-is defined in any
-static or dynamic extension set and a task is being created,
-then the extension routine will automatically be invoked by
-RTEMS. The extension should have a prototype similar to the
-following:.. index:: rtems_task_create_extension
-.. index:: rtems_extension
-
-.. code:: c
-
- bool user_task_create(
- rtems_tcb \*current_task,
- rtems_tcb \*new_task
- );
-
-where ``current_task`` can be used to access the TCB for
-the currently executing task, and new_task can be used to access
-the TCB for the new task being created. This extension is
-invoked from the ``rtems_task_create``
-directive after ``new_task`` has been
-completely initialized, but before it is placed on a ready TCB
-chain.
-
-The user extension is expected to return the boolean
-value ``true`` if it successfully executed and``false`` otherwise. A task create user extension
-will frequently attempt to allocate resources. If this
-allocation fails, then the extension should return``false`` and the entire task create operation
-will fail.
-
-TASK_START Extension
-~~~~~~~~~~~~~~~~~~~~
-
-The TASK_START extension directly corresponds to the
-task_start directive. If this extension is defined in any
-static or dynamic extension set and a task is being started,
-then the extension routine will automatically be invoked by
-RTEMS. The extension should have a prototype similar to the
-following:.. index:: rtems_task_start_extension
-
-.. code:: c
-
- void user_task_start(
- rtems_tcb \*current_task,
- rtems_tcb \*started_task
- );
-
-where current_task can be used to access the TCB for
-the currently executing task, and started_task can be used to
-access the TCB for the dormant task being started. This
-extension is invoked from the task_start directive after
-started_task has been made ready to start execution, but before
-it is placed on a ready TCB chain.
-
-TASK_RESTART Extension
-~~~~~~~~~~~~~~~~~~~~~~
-
-The TASK_RESTART extension directly corresponds to
-the task_restart directive. If this extension is defined in any
-static or dynamic extension set and a task is being restarted,
-then the extension should have a prototype similar to the
-following:.. index:: rtems_task_restart_extension
-
-.. code:: c
-
- void user_task_restart(
- rtems_tcb \*current_task,
- rtems_tcb \*restarted_task
- );
-
-where current_task can be used to access the TCB for
-the currently executing task, and restarted_task can be used to
-access the TCB for the task being restarted. This extension is
-invoked from the task_restart directive after restarted_task has
-been made ready to start execution, but before it is placed on a
-ready TCB chain.
-
-TASK_DELETE Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The TASK_DELETE extension is associated with the
-task_delete directive. If this extension is defined in any
-static or dynamic extension set and a task is being deleted,
-then the extension routine will automatically be invoked by
-RTEMS. The extension should have a prototype similar to the
-following:.. index:: rtems_task_delete_extension
-
-.. code:: c
-
- void user_task_delete(
- rtems_tcb \*current_task,
- rtems_tcb \*deleted_task
- );
-
-where current_task can be used to access the TCB for
-the currently executing task, and deleted_task can be used to
-access the TCB for the task being deleted. This extension is
-invoked from the task_delete directive after the TCB has been
-removed from a ready TCB chain, but before all its resources
-including the TCB have been returned to their respective free
-pools. This extension should not call any RTEMS directives if a
-task is deleting itself (current_task is equal to deleted_task).
-
-TASK_SWITCH Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The TASK_SWITCH extension corresponds to a task
-context switch. If this extension is defined in any static or
-dynamic extension set and a task context switch is in progress,
-then the extension routine will automatically be invoked by
-RTEMS. The extension should have a prototype similar to the
-following:.. index:: rtems_task_switch_extension
-
-.. code:: c
-
- void user_task_switch(
- rtems_tcb \*current_task,
- rtems_tcb \*heir_task
- );
-
-where current_task can be used to access the TCB for
-the task that is being swapped out, and heir_task can be used to
-access the TCB for the task being swapped in. This extension is
-invoked from RTEMS’ dispatcher routine after the current_task
-context has been saved, but before the heir_task context has
-been restored. This extension should not call any RTEMS
-directives.
-
-TASK_BEGIN Extension
-~~~~~~~~~~~~~~~~~~~~
-
-The TASK_BEGIN extension is invoked when a task
-begins execution. It is invoked immediately before the body of
-the starting procedure and executes in the context in the task.
-This user extension have a prototype similar to the following:.. index:: rtems_task_begin_extension
-
-.. code:: c
-
- void user_task_begin(
- rtems_tcb \*current_task
- );
-
-where current_task can be used to access the TCB for
-the currently executing task which has begun. The distinction
-between the TASK_BEGIN and TASK_START extension is that the
-TASK_BEGIN extension is executed in the context of the actual
-task while the TASK_START extension is executed in the context
-of the task performing the task_start directive. For most
-extensions, this is not a critical distinction.
-
-TASK_EXITTED Extension
-~~~~~~~~~~~~~~~~~~~~~~
-
-The TASK_EXITTED extension is invoked when a task
-exits the body of the starting procedure by either an implicit
-or explicit return statement. This user extension have a
-prototype similar to the following:.. index:: rtems_task_exitted_extension
-
-.. code:: c
-
- void user_task_exitted(
- rtems_tcb \*current_task
- );
-
-where current_task can be used to access the TCB for
-the currently executing task which has just exitted.
-
-Although exiting of task is often considered to be a
-fatal error, this extension allows recovery by either restarting
-or deleting the exiting task. If the user does not wish to
-recover, then a fatal error may be reported. If the user does
-not provide a TASK_EXITTED extension or the provided handler
-returns control to RTEMS, then the RTEMS default handler will be
-used. This default handler invokes the directive
-fatal_error_occurred with the ``RTEMS_TASK_EXITTED`` directive status.
-
-FATAL Error Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The FATAL error extension is associated with the
-fatal_error_occurred directive. If this extension is defined in
-any static or dynamic extension set and the fatal_error_occurred
-directive has been invoked, then this extension will be called.
-This extension should have a prototype similar to the following:.. index:: rtems_fatal_extension
-
-.. code:: c
-
- void user_fatal_error(
- Internal_errors_Source the_source,
- bool is_internal,
- uint32_t the_error
- );
-
-where the_error is the error code passed to the
-fatal_error_occurred directive. This extension is invoked from
-the fatal_error_occurred directive.
-
-If defined, the user’s FATAL error extension is
-invoked before RTEMS’ default fatal error routine is invoked and
-the processor is stopped. For example, this extension could be
-used to pass control to a debugger when a fatal error occurs.
-This extension should not call any RTEMS directives.
-
-Order of Invocation
--------------------
-
-When one of the critical system events occur, the
-user extensions are invoked in either "forward" or "reverse"
-order. Forward order indicates that the static extension set is
-invoked followed by the dynamic extension sets in the order in
-which they were created. Reverse order means that the dynamic
-extension sets are invoked in the opposite of the order in which
-they were created followed by the static extension set. By
-invoking the extension sets in this order, extensions can be
-built upon one another. At the following system events, the
-extensions are invoked in forward order:
-
-- Task creation
-
-- Task initiation
-
-- Task reinitiation
-
-- Task deletion
-
-- Task context switch
-
-- Post task context switch
-
-- Task begins to execute
-
-At the following system events, the extensions are
-invoked in reverse order:
-
-- Task deletion
-
-- Fatal error detection
-
-At these system events, the extensions are invoked in
-reverse order to insure that if an extension set is built upon
-another, the more complicated extension is invoked before the
-extension set it is built upon. For example, by invoking the
-static extension set last it is known that the "system" fatal
-error extension will be the last fatal error extension executed.
-Another example is use of the task delete extension by the
-Standard C Library. Extension sets which are installed after
-the Standard C Library will operate correctly even if they
-utilize the C Library because the C Library’s TASK_DELETE
-extension is invoked after that of the other extensions.
-
-Operations
-==========
-
-Creating an Extension Set
--------------------------
-
-The ``rtems_extension_create`` directive creates and installs
-an extension set by allocating a Extension Set Control Block
-(ESCB), assigning the extension set a user-specified name, and
-assigning it an extension set ID. Newly created extension sets
-are immediately installed and are invoked upon the next system
-even supporting an extension.
-
-Obtaining Extension Set IDs
----------------------------
-
-When an extension set is created, RTEMS generates a
-unique extension set ID and assigns it to the created extension
-set until it is deleted. The extension ID may be obtained by
-either of two methods. First, as the result of an invocation of
-the ``rtems_extension_create``
-directive, the extension set ID is stored
-in a user provided location. Second, the extension set ID may
-be obtained later using the ``rtems_extension_ident``
-directive. The extension set ID is used by other directives
-to manipulate this extension set.
-
-Deleting an Extension Set
--------------------------
-
-The ``rtems_extension_delete`` directive is used to delete an
-extension set. The extension set’s control block is returned to
-the ESCB free list when it is deleted. An extension set can be
-deleted by a task other than the task which created the
-extension set. Any subsequent references to the extension’s
-name and ID are invalid.
-
-Directives
-==========
-
-This section details the user extension manager’s
-directives. A subsection is dedicated to each of this manager’s
-directives and describes the calling sequence, related
-constants, usage, and status codes.
-
-EXTENSION_CREATE - Create a extension set
------------------------------------------
-.. index:: create an extension set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_extension_create
-
-.. code:: c
-
- rtems_status_code rtems_extension_create(
- rtems_name name,
- rtems_extensions_table \*table,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - extension set created successfully
-``RTEMS_INVALID_NAME`` - invalid extension set name
-``RTEMS_TOO_MANY`` - too many extension sets created
-
-**DESCRIPTION:**
-
-This directive creates a extension set. The assigned
-extension set id is returned in id. This id is used to access
-the extension set with other user extension manager directives.
-For control and maintenance of the extension set, RTEMS
-allocates an ESCB from the local ESCB free pool and initializes
-it.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-EXTENSION_IDENT - Get ID of a extension set
--------------------------------------------
-.. index:: get ID of an extension set
-.. index:: obtain ID of an extension set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_extension_ident
-
-.. code:: c
-
- rtems_status_code rtems_extension_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - extension set identified successfully
-``RTEMS_INVALID_NAME`` - extension set name not found
-
-**DESCRIPTION:**
-
-This directive obtains the extension set id
-associated with the extension set name to be acquired. If the
-extension set name is not unique, then the extension set id will
-match one of the extension sets with that name. However, this
-extension set id is not guaranteed to correspond to the desired
-extension set. The extension set id is used to access this
-extension set in other extension set related directives.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-EXTENSION_DELETE - Delete a extension set
------------------------------------------
-.. index:: delete an extension set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_extension_delete
-
-.. code:: c
-
- rtems_status_code rtems_extension_delete(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - extension set deleted successfully
-``RTEMS_INVALID_ID`` - invalid extension set id
-
-**DESCRIPTION:**
-
-This directive deletes the extension set specified by
-id. If the extension set is running, it is automatically
-canceled. The ESCB for the deleted extension set is reclaimed
-by RTEMS.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-A extension set can be deleted by a task other than
-the task which created the extension set.
-
-**NOTES:**
-
-This directive will not cause the running task to be
-preempted.
-
-.. COMMENT: COPYRIGHT (c) 1988-2015.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: TODO:
-
-.. COMMENT: + Ensure all macros are documented.
-
-.. COMMENT: + Verify which structures may actually be defined by a user
-
-.. COMMENT: + Add Go configuration.
-
-.. COMMENT: Questions:
-
-.. COMMENT: + Should there be examples of defining your own
-
-.. COMMENT: Device Driver Table, Init task table, etc.?
-
-
-Configuring a System
-####################
-
-.. COMMENT: === Introduction ===
-
-Introduction
-============
-
-RTEMS must be configured for an application. This configuration
-encompasses a variety of information including the length of each clock
-tick, the maximum number of each information RTEMS object that can
-be created, the application initialization tasks, the task scheduling
-algorithm to be used, and the device drivers in the application.
-
-Although this information is contained in data structures that are used
-by RTEMS at system initialization time, the data structures themselves
-should only rarely to be generated by hand. RTEMS provides a set of
-macros system which provides a simple standard mechanism to automate
-the generation of these structures.
-.. index:: confdefs.h
-.. index:: confdefs.h
-.. index:: <rtems/confdefs.h>
-.. index:: <rtems/confdefs.h>
-
-The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the
-automatic generation of system configuration. It is based on the idea
-of setting macros which define configuration parameters of interest to
-the application and defaulting or calculating all others. This variety
-of macros can automatically produce all of the configuration data
-required for an RTEMS application.
-
-Trivia: ``confdefs`` is shorthand for a *Configuration Defaults*.
-
-As a general rule, application developers only specify values
-for the configuration parameters of interest to them. They define what
-resources or features they require. In most cases, when a parameter is
-not specified, it defaults to zero (0) instances, a standards compliant
-value, or disabled as appropriate. For example, by default there will be
-256 task priority levels but this can be lowered by the application. This
-number of priority levels is required to be compliant with the RTEID/ORKID
-standards upon which the Classic API is based. There are similar cases
-where the default is selected to be compliant with with the POSIX standard.
-
-For each configuration parameter in the configuration tables, the macro
-corresponding to that field is discussed. The RTEMS Maintainers
-expect that all systems can be easily configured using the``<rtems/confdefs.h>`` mechanism and that using this mechanism will
-avoid internal RTEMS configuration changes impacting applications.
-
-.. COMMENT: === Philosophy ===
-
-Default Value Selection Philosophy
-==================================
-
-The user should be aware that the defaults are intentionally set as
-low as possible. By default, no application resources are configured.
-The ``<rtems/confdefs.h>`` file ensures that at least one application
-task or thread is configured and that at least one of the initialization
-task/thread tables is configured.
-
-.. COMMENT: === Sizing the RTEMS Workspace ===
-
-Sizing the RTEMS Workspace
-==========================
-
-The RTEMS Workspace is a user-specified block of memory reserved for
-use by RTEMS. The application should NOT modify this memory. This area
-consists primarily of the RTEMS data structures whose exact size depends
-upon the values specified in the Configuration Table. In addition,
-task stacks and floating point context areas are dynamically allocated
-from the RTEMS Workspace.
-
-The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS
-Workspace automatically. It assumes that all tasks are floating point and
-that all will be allocated the minimum stack space. This calculation
-includes the amount of memory that will be allocated for internal use
-by RTEMS. The automatic calculation may underestimate the workspace
-size truly needed by the application, in which case one can use the``CONFIGURE_MEMORY_OVERHEAD`` macro to add a value to the estimate. See `Specify Memory Overhead`_ for more details.
-
-The memory area for the RTEMS Workspace is determined by the BSP. In case the
-RTEMS Workspace is too large for the available memory, then a fatal run-time
-error occurs and the system terminates.
-
-The file ``<rtems/confdefs.h>`` will calculate the value of the``work_space_size`` parameter of the Configuration Table. There
-are many parameters the application developer can specify to
-help ``<rtems/confdefs.h>`` in its calculations. Correctly
-specifying the application requirements via parameters such as``CONFIGURE_EXTRA_TASK_STACKS`` and ``CONFIGURE_MAXIMUM_TASKS``
-is critical for production software.
-
-For each class of objects, the allocation can operate in one of two ways.
-The default way has an ceiling on the maximum number of object instances
-which can concurrently exist in the system. Memory for all instances of
-that object class is reserved at system initialization. The second
-way allocates memory for an initial number of objects and increases the
-current allocation by a fixed increment when required. Both ways allocate
-space from inside the RTEMS Workspace.
-
-See `Unlimited Objects`_ for more details about
-the second way, which allows for dynamic allocation of objects and
-therefore does not provide determinism. This mode is useful mostly for
-when the number of objects cannot be determined ahead of time or when
-porting software for which you do not know the object requirements.
-
-The space needed for stacks and for RTEMS objects will vary from
-one version of RTEMS and from one target processor to another.
-Therefore it is safest to use ``<rtems/confdefs.h>`` and specify
-your application’s requirements in terms of the numbers of objects and
-multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as is possible. The
-automatic estimates of space required will in general change when:
-
-- a configuration parameter is changed,
-
-- task or interrupt stack sizes change,
-
-- the floating point attribute of a task changes,
-
-- task floating point attribute is altered,
-
-- RTEMS is upgraded, or
-
-- the target processor is changed.
-
-Failure to provide enough space in the RTEMS Workspace may result in fatal
-run-time errors terminating the system.
-
-.. COMMENT: === Potential Issues ===
-
-Potential Issues with RTEMS Workspace Size Estimation
-=====================================================
-
-The ``<rtems/confdefs.h>`` file estimates the amount of memory
-required for the RTEMS Workspace. This estimate is only as accurate
-as the information given to ``<rtems/confdefs.h>`` and may be either
-too high or too low for a variety of reasons. Some of the reasons that``<rtems/confdefs.h>`` may reserve too much memory for RTEMS are:
-
-- All tasks/threads are assumed to be floating point.
-
-Conversely, there are many more reasons that the resource estimate could be
-too low:
-
-- Task/thread stacks greater than minimum size must be
- accounted for explicitly by developer.
-
-- Memory for messages is not included.
-
-- Device driver requirements are not included.
-
-- Network stack requirements are not included.
-
-- Requirements for add-on libraries are not included.
-
-In general, ``<rtems/confdefs.h>`` is very accurate when given enough
-information. However, it is quite easy to use a library and forget to
-account for its resources.
-
-.. COMMENT: === Format to be followed for making changes in this file ===
-
-Format to be followed for making changes in this file
-=====================================================
-
-- MACRO NAME
- Should be alphanumeric. Can have ’_’ (underscore).
-
-- DATA TYPE
- Please refer to all existing formats.
-
-- RANGE:
-
- The range depends on the Data Type of the macro.
-
- - − If the data type is of type task priority, then its value should
- be an integer in the range of 1 to 255.
- - − If the data type is an integer, then it can have numbers, characters
- (in case the value is defined using another macro) and arithmetic operations
- (+, -, \*, /).
- - − If the data type is a function pointer the first character
- should be an alphabet or an underscore. The rest of the string
- can be alphanumeric.
- - − If the data type is RTEMS Attributes or RTEMS Mode then
- the string should be alphanumeric.
- - − If the data type is RTEMS NAME then the value should be
- an integer>=0 or RTEMS_BUILD_NAME( ’U’, ’I’, ’1’, ’ ’ )
-
-- DEFAULT VALUE
-
- The default value should be in the following formats-
- Please note that the ’.’ (full stop) is necessary.
-
- - − In case the value is not defined then:
- This is not defined by default.
- - − If we know the default value then:
- The default value is XXX.
- - − If the default value is BSP Specific then:
- This option is BSP specific.
-
-- DESCRIPTION
- The description of the macro. (No specific format)
-
-- NOTES
- Any further notes. (No specific format)
-
-.. COMMENT: === Configuration Example ===
-
-Configuration Example
-=====================
-
-In the following example, the configuration information for a system
-with a single message queue, four (4) tasks, and a timeslice of
-fifty (50) milliseconds is as follows:
-.. code:: c
-
- #include <bsp.h>
- #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
- #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
- #define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond \*/
- #define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds \*/
- #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
- #define CONFIGURE_MAXIMUM_TASKS 4
- #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1
- #define CONFIGURE_MESSAGE_BUFFER_MEMORY \\
- CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE))
- #define CONFIGURE_INIT
- #include <rtems/confdefs.h>
-
-In this example, only a few configuration parameters are specified. The
-impact of these are as follows:
-
-- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE``
- but did not specify any additional parameters. This results in a
- configuration of an application which will begin execution of a single
- initialization task named ``Init`` which is non-preemptible and at
- priority one (1).
-
-- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``,
- this application is configured to have a clock tick device
- driver. Without a clock tick device driver, RTEMS has no way to know
- that time is passing and will be unable to support delays and wall
- time. Further configuration details about time are
- provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a
- clock tick to occur each millisecond, and that the length of a timeslice
- would be fifty (50) milliseconds.
-
-- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
- the application will include a console device driver. Although the
- console device driver may support a combination of multiple serial
- ports and display and keyboard combinations, it is only required to
- provide a single device named ``/dev/console``. This device will
- be used for Standard Input, Output and Error I/O Streams. Thus when``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is specified, implicitly
- three (3) file descriptors are reserved for the Standard I/O Streams and
- those file descriptors are associated with ``/dev/console`` during
- initialization. All console devices are expected to support the POSIX*termios* interface.
-
-- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS``
- that the application requires a maximum of four (4)
- simultaneously existing Classic API tasks. Similarly, by specifying``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, there may be a maximum of only
- one (1) concurrently existent Classic API message queues.
-
-- The most surprising configuration parameter in this example is the
- use of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is
- allocated from the RTEMS Workspace and must be accounted for. In this
- example, the single message queue will have up to twenty (20) messages
- of type ``struct USER_MESSAGE``.
-
-- The ``CONFIGURE_INIT`` constant must be defined in order to
- make ``<rtems/confdefs.h>`` instantiate the configuration data
- structures. This can only be defined in one source file per
- application that includes ``<rtems/confdefs.h>`` or the symbol
- table will be instantiated multiple times and linking errors
- produced.
-
-This example illustrates that parameters have default values. Among
-other things, the application implicitly used the following defaults:
-
-- All unspecified types of communications and synchronization objects
- in the Classic and POSIX Threads API have maximums of zero (0).
-
-- The filesystem will be the default filesystem which is the In-Memory File
- System (IMFS).
-
-- The application will have the default number of priority levels.
-
-- The minimum task stack size will be that recommended by RTEMS for
- the target architecture.
-
-.. COMMENT: === Unlimited Objects ===
-
-
-Unlimited Objects
------------------
-
-In real-time embedded systems the RAM is normally a limited, critical
-resource and dynamic allocation is avoided as much as possible to
-ensure predictable, deterministic execution times. For such cases, see `Sizing the RTEMS Workspace`_ for an overview
-of how to tune the size of the workspace. Frequently when users are
-porting software to RTEMS the precise resource requirements of the
-software is unknown. In these situations users do not need to control
-the size of the workspace very tightly because they just want to get
-the new software to run; later they can tune the workspace size as needed.
-
-The following API-independent object classes can be configured in
-unlimited mode:
-
-- POSIX Keys
-
-- POSIX Key Value Pairs
-
-The following object classes in the Classic API can be configured in
-unlimited mode:
-
-- Tasks
-
-- Timers
-
-- Semaphores
-
-- Message Queues
-
-- Periods
-
-- Barriers
-
-- Partitions
-
-- Regions
-
-- Ports
-
-Additionally, the following object classes from the POSIX API can be
-configured in unlimited mode:
-
-- Threads
-
-- Mutexes
-
-- Condition Variables
-
-- Timers
-
-- Message Queues
-
-- Message Queue Descriptors
-
-- Semaphores
-
-- Barriers
-
-- Read/Write Locks
-
-- Spinlocks
-
-The following object classes can *not* be configured in unlimited mode:
-
-- Drivers
-
-- File Descriptors
-
-- User Extensions
-
-- POSIX Queued Signals
-
-Due to the memory requirements of unlimited objects it is strongly recommended
-to use them only in combination with the unified work areas. See `Separate or Unified Work Areas`_ for more information
-on unified work areas.
-
-The following example demonstrates how the two simple configuration defines for
-unlimited objects and unified works areas can replace many seperate
-configuration defines for supported object classes:
-.. code:: c
-
- #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
- #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
- #define CONFIGURE_UNIFIED_WORK_AREAS
- #define CONFIGURE_UNLIMITED_OBJECTS
- #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
- #define CONFIGURE_INIT
- #include <rtems/confdefs.h>
-
-Users are cautioned that using unlimited objects is not recommended for
-production software unless the dynamic growth is absolutely required. It
-is generally considered a safer embedded systems programming practice to
-know the system limits rather than experience an out of memory error
-at an arbitrary and largely unpredictable time in the field.
-
-.. COMMENT: === Per Object Class Unlimited Object Instances ===
-
-Per Object Class Unlimited Object Instances
--------------------------------------------
-.. index:: rtems_resource_unlimited
-
-When the number of objects is not known ahead of time, RTEMS provides an
-auto-extending mode that can be enabled individually for each object
-type by using the macro ``rtems_resource_unlimited``. This takes a value
-as a parameter, and is used to set the object maximum number field in
-an API Configuration table. The value is an allocation unit size. When
-RTEMS is required to grow the object table it is grown by this
-size. The kernel will return the object memory back to the RTEMS Workspace
-when an object is destroyed. The kernel will only return an allocated
-block of objects to the RTEMS Workspace if at least half the allocation
-size of free objects remain allocated. RTEMS always keeps one
-allocation block of objects allocated. Here is an example of using``rtems_resource_unlimited``:
-.. code:: c
-
- #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
-
-.. index:: rtems_resource_is_unlimited
-.. index:: rtems_resource_maximum_per_allocation
-
-Object maximum specifications can be evaluated with the``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` macros.
-
-.. COMMENT: === Unlimited Object Instances ===
-
-Unlimited Object Instances
---------------------------
-
-To ease the burden of developers who are porting new software RTEMS
-also provides the capability to make all object classes listed above
-operate in unlimited mode in a simple manner. The application developer
-is only responsible for enabling unlimited objects and specifying the
-allocation size.
-
-.. COMMENT: === CONFIGURE_UNLIMITED_OBJECTS ===
-
-Enable Unlimited Object Instances
----------------------------------
-.. index:: CONFIGURE_UNLIMITED_OBJECTS
-
-*CONSTANT:*
- ``CONFIGURE_UNLIMITED_OBJECTS``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited``
-mode for Classic API and POSIX API objects that do not already have a
-specific maximum limit defined.
-
-**NOTES:**
-
-When using unlimited objects, it is common practice to also specify``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single
-pool of memory for both RTEMS and application memory allocations.
-
-.. COMMENT: === CONFIGURE_UNLIMITED_ALLOCATION_SIZE ===
-
-Specify Unlimited Objects Allocation Size
------------------------------------------
-
-*CONSTANT:*
- ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, the
- default value is eight (8).
-
-**DESCRIPTION:**
-
-``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an
-allocation size to use for ``rtems_resource_unlimited`` when using``CONFIGURE_UNLIMITED_OBJECTS``.
-
-**NOTES:**
-
-By allowing users to declare all resources as being unlimited
-the user can avoid identifying and limiting the resources used.``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the allocation
-sizes for different objects; users who want that much control can define
-the ``rtems_resource_unlimited`` macros themselves.
-.. code:: c
-
- #define CONFIGURE_UNLIMITED_OBJECTS
- #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
-
-.. COMMENT: === Classic API Configuration ===
-
-Classic API Configuration
-=========================
-
-This section defines the Classic API related system configuration
-parameters supported by ``<rtems/confdefs.h>``.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_TASKS ===
-
-Specify Maximum Classic API Tasks
----------------------------------
-.. index:: CONFIGURE_MAXIMUM_TASKS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_TASKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API
-Tasks that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-The calculations for the required memory in the RTEMS Workspace
-for tasks assume that each task has a minimum stack size and
-has floating point support enabled. The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack
-requirements *ABOVE* the minimum size required. See `Reserve Task/Thread Stack Memory Above Minimum`_
-for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
-
-The maximum number of POSIX threads is specified by``CONFIGURE_MAXIMUM_POSIX_THREADS``.
-
-.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS.
-
-A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate
-the assumption that all tasks have floating point enabled. This would
-require the addition of a new configuration parameter to specify the
-number of tasks which enable floating point support.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_TIMERS ===
-
-Specify Maximum Classic API Timers
-----------------------------------
-.. index:: CONFIGURE_MAXIMUM_TIMERS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_TIMERS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API
-Timers that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_SEMAPHORES ===
-
-Specify Maximum Classic API Semaphores
---------------------------------------
-.. index:: CONFIGURE_MAXIMUM_SEMAPHORES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_SEMAPHORES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic
-API Semaphores that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES ===
-
-Specify Maximum Classic API Semaphores usable with MrsP
--------------------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the
-maximum number of Classic API Semaphores using the Multiprocessor Resource
-Sharing Protocol (MrsP) that can be concurrently active.
-
-**NOTES:**
-
-This configuration option is only used on SMP configurations. On uni-processor
-configurations the Priority Ceiling Protocol is used for MrsP semaphores and
-thus no extra memory is necessary.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_MESSAGE_QUEUES ===
-
-Specify Maximum Classic API Message Queues
-------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic
-API Message Queues that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_BARRIERS ===
-
-Specify Maximum Classic API Barriers
-------------------------------------
-.. index:: CONFIGURE_MAXIMUM_BARRIERS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_BARRIERS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic
-API Barriers that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_PERIODS ===
-
-Specify Maximum Classic API Periods
------------------------------------
-.. index:: CONFIGURE_MAXIMUM_PERIODS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_PERIODS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic
-API Periods that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_PARTITIONS ===
-
-Specify Maximum Classic API Partitions
---------------------------------------
-.. index:: CONFIGURE_MAXIMUM_PARTITIONS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_PARTITIONS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic
-API Partitions that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_REGIONS ===
-
-Specify Maximum Classic API Regions
------------------------------------
-.. index:: CONFIGURE_MAXIMUM_REGIONS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_REGIONS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic
-API Regions that can be concurrently active.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_PORTS ===
-
-Specify Maximum Classic API Ports
----------------------------------
-.. index:: CONFIGURE_MAXIMUM_PORTS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_PORTS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic
-API Ports that can be concurrently active.
-
-**NOTES:**