summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-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:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_USER_EXTENSIONS ===
-
-Specify Maximum Classic API User Extensions
--------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_USER_EXTENSIONS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic
-API User Extensions that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === Classic API Initialization Task Configuration ===
-
-Classic API Initialization Tasks Table Configuration
-====================================================
-
-The ``<rtems/confdefs.h>`` configuration system can automatically
-generate an Initialization Tasks Table named``Initialization_tasks`` with a single entry. The following
-parameters control the generation of that table.
-
-.. COMMENT: === CONFIGURE_RTEMS_INIT_TASKS_TABLE ===
-
-Instantiate Classic API Initialization Task Table
--------------------------------------------------
-.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes
-to use a Classic RTEMS API Initialization Task Table. The table built by``<rtems/confdefs.h>`` specifies the parameters for a single task. This
-is sufficient for applications which initialization the system from a
-single task.
-
-By default, this field is not defined as the user MUST select their own
-API for initialization tasks.
-
-**NOTES:**
-
-The application may choose to use the initialization tasks or threads
-table from another API.
-
-A compile time error will be generated if the user does not configure
-any initialization tasks or threads.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_ENTRY_POINT ===
-
-Specifying Classic API Initialization Task Entry Point
-------------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_ENTRY_POINT``
-
-*DATA TYPE:*
- Task entry function pointer (``rtems_task_entry``).
-
-*RANGE:*
- Valid task entry function pointer.
-
-*DEFAULT VALUE:*
- The default value is ``Init``.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function
-name) of the single initialization task defined by the Classic API
-Initialization Tasks Table.
-
-**NOTES:**
-
-The user must implement the function ``Init`` or the function name provided
-in this configuration parameter.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_NAME ===
-
-Specifying Classic API Initialization Task Name
------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_NAME
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_NAME``
-
-*DATA TYPE:*
- RTEMS Name (``rtems_name``).
-
-*RANGE:*
- Any value.
-
-*DEFAULT VALUE:*
- The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization
-task defined by the Classic API Initialization Tasks Table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_STACK_SIZE ===
-
-Specifying Classic API Initialization Task Stack Size
------------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_STACK_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is RTEMS_MINIMUM_STACK_SIZE.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single
-initialization task defined by the Classic API Initialization Tasks Table.
-
-**NOTES:**
-
-If the stack size specified is greater than the configured minimum,
-it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
-See `Reserve Task/Thread Stack Memory Above Minimum`_
-for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_PRIORITY ===
-
-Specifying Classic API Initialization Task Priority
----------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_PRIORITY
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_PRIORITY``
-
-*DATA TYPE:*
- RTEMS Task Priority (``rtems_task_priority``).
-
-*RANGE:*
- One (1) to CONFIGURE_MAXIMUM_PRIORITY.
-
-*DEFAULT VALUE:*
- The default value is 1, which is the highest priority in the
- Classic API.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single
-initialization task defined by the Classic API Initialization Tasks Table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_ATTRIBUTES ===
-
-Specifying Classic API Initialization Task Attributes
------------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_ATTRIBUTES``
-
-*DATA TYPE:*
- RTEMS Attributes (``rtems_attribute``).
-
-*RANGE:*
- Valid task attribute sets.
-
-*DEFAULT VALUE:*
- The default value is ``RTEMS_DEFAULT_ATTRIBUTES``.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single
-initialization task defined by the Classic API Initialization Tasks Table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_INITIAL_MODES ===
-
-Specifying Classic API Initialization Task Modes
-------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_INITIAL_MODES``
-
-*DATA TYPE:*
- RTEMS Mode (``rtems_mode``).
-
-*RANGE:*
- Valid task mode sets.
-
-*DEFAULT VALUE:*
- The default value is ``RTEMS_NO_PREEMPT``.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of
-the single initialization task defined by the Classic API Initialization
-Tasks Table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_INIT_TASK_ARGUMENTS ===
-
-Specifying Classic API Initialization Task Arguments
-----------------------------------------------------
-.. index:: CONFIGURE_INIT_TASK_ARGUMENTS
-
-*CONSTANT:*
- ``CONFIGURE_INIT_TASK_ARGUMENTS``
-
-*DATA TYPE:*
- RTEMS Task Argument (``rtems_task_argument``).
-
-*RANGE:*
- Complete range of the type.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single
-initialization task defined by the Classic API Initialization Tasks Table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_HAS_OWN_INIT_TASK_TABLE ===
-
-Not Using Generated Initialization Tasks Table
-----------------------------------------------
-.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes
-to define their own Classic API Initialization Tasks Table. This table
-should be named ``Initialization_tasks``.
-
-**NOTES:**
-
-This is a seldom used configuration parameter. The most likely use case
-is when an application desires to have more than one initialization task.
-
-.. COMMENT: === POSIX API Configuration ===
-
-POSIX API Configuration
-=======================
-
-The parameters in this section are used to configure resources
-for the RTEMS POSIX API. They are only relevant if the POSIX API
-is enabled at configure time using the ``--enable-posix`` option.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_THREADS ===
-
-Specify Maximum POSIX API Threads
----------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_THREADS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API
-Threads that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-This calculations for the required memory in the RTEMS Workspace
-for threads assume that each thread has a minimum stack size and
-has floating point support enabled. The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread 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 Classic API Tasks is specified by``CONFIGURE_MAXIMUM_TASKS``.
-
-All POSIX threads have floating point enabled.
-
-.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_TASKS.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MUTEXES ===
-
-Specify Maximum POSIX API Mutexes
----------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_MUTEXES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` is the maximum number of POSIX
-API Mutexes that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES ===
-
-Specify Maximum POSIX API Condition Variables
----------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` is the maximum number
-of POSIX API Condition Variables that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_KEYS ===
-
-Specify Maximum POSIX API Keys
-------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_KEYS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX
-API Keys that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: XXX - Key pairs
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_TIMERS ===
-
-Specify Maximum POSIX API Timers
---------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_TIMERS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX
-API Timers that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS ===
-
-Specify Maximum POSIX API Queued Signals
-----------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX
-API Queued Signals that can be concurrently active.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES ===
-
-Specify Maximum POSIX API Message Queues
-----------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX
-API Message Queues that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: XXX - memory for buffers note
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS ===
-
-Specify Maximum POSIX API Message Queue Descriptors
----------------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGES_QUEUES``
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` is the maximum
-number of POSIX API Message Queue Descriptors that can be concurrently
-active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` should be
-greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ===
-
-Specify Maximum POSIX API Semaphores
-------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX
-API Semaphores that can be concurrently active.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_BARRIERS ===
-
-Specify Maximum POSIX API Barriers
-----------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_BARRIERS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` is the maximum number of POSIX
-API Barriers that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SPINLOCKS ===
-
-Specify Maximum POSIX API Spinlocks
------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` is the maximum number of POSIX
-API Spinlocks that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_RWLOCKS ===
-
-Specify Maximum POSIX API Read/Write Locks
-------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_POSIX_RWLOCKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` is the maximum number of POSIX
-API Read/Write Locks that can be concurrently active.
-
-**NOTES:**
-
-This object class can be configured in unlimited allocation mode.
-
-.. COMMENT: === POSIX Initialization Threads Table Configuration ===
-
-POSIX Initialization Threads Table Configuration
-================================================
-
-The ``<rtems/confdefs.h>`` configuration system can automatically
-generate a POSIX Initialization Threads Table named``POSIX_Initialization_threads`` with a single entry. The following
-parameters control the generation of that table.
-
-.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_TABLE ===
-
-Instantiate POSIX API Initialization Thread Table
--------------------------------------------------
-.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE
-
-*CONSTANT:*
- .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This field is not defined by default, as the user MUST select their own
- API for initialization tasks.
-
-**DESCRIPTION:**
-
-``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes
-to use a POSIX API Initialization Threads Table. The table built
-by ``<rtems/confdefs.h>`` specifies the parameters for a single
-thread. This is sufficient for applications which initialization the
-system from a
-single task.
-
-By default, this field is not defined as the user MUST select their own
-API for initialization tasks.
-
-**NOTES:**
-
-The application may choose to use the initialization tasks or threads
-table from another API.
-
-A compile time error will be generated if the user does not configure
-any initialization tasks or threads.
-
-.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT ===
-
-Specifying POSIX API Initialization Thread Entry Point
-------------------------------------------------------
-.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
-
-*CONSTANT:*
- ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT``
-
-*DATA TYPE:*
- POSIX thread function pointer (``void \*(*entry_point)(void \*)``).
-
-*RANGE:*
- Undefined or a valid POSIX thread function pointer.
-
-*DEFAULT VALUE:*
- The default value is ``POSIX_Init``.
-
-**DESCRIPTION:**
-
-``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point
-(a.k.a. function name) of the single initialization thread defined by
-the POSIX API Initialization Threads Table.
-
-**NOTES:**
-
-The user must implement the function ``POSIX_Init`` or the function name
-provided in this configuration parameter.
-
-.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE ===
-
-Specifying POSIX API Initialization Thread Stack Size
------------------------------------------------------
-.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 2 * RTEMS_MINIMUM_STACK_SIZE.
-
-**DESCRIPTION:**
-
-``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the
-single initialization thread defined by the POSIX API Initialization
-Threads Table.
-
-**NOTES:**
-
-If the stack size specified is greater than the configured minimum,
-it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
-See `Reserve Task/Thread Stack Memory Above Minimum`_
-for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
-
-.. COMMENT: === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE ===
-
-Not Using Generated POSIX Initialization Threads Table
-------------------------------------------------------
-.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the
-user wishes to define their own POSIX API Initialization Threads Table.
-This table should be named ``POSIX_Initialization_threads``.
-
-**NOTES:**
-
-This is a seldom used configuration parameter. The most likely use case
-is when an application desires to have more than one initialization task.
-
-.. COMMENT: === Basic System Information ===
-
-Basic System Information
-========================
-
-This section defines the general system configuration parameters supported by``<rtems/confdefs.h>``.
-
-.. COMMENT: === CONFIGURE_UNIFIED_WORK_AREAS ===
-
-
-Separate or Unified Work Areas
-------------------------------
-.. index:: CONFIGURE_UNIFIED_WORK_AREAS
-.. index:: unified work areas
-.. index:: separate work areas
-.. index:: RTEMS Workspace
-.. index:: C Program Heap
-
-*CONSTANT:*
- ``CONFIGURE_UNIFIED_WORK_AREAS``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default, which specifies that the C Program Heap
- and the RTEMS Workspace will be separate.
-
-**DESCRIPTION:**
-
-When defined, the C Program Heap and the RTEMS Workspace will be one pool
-of memory.
-
-When not defined, there will be separate memory pools for the RTEMS
-Workspace and C Program Heap.
-
-**NOTES:**
-
-Having separate pools does have some advantages in the event a task blows
-a stack or writes outside its memory area. However, in low memory systems
-the overhead of the two pools plus the potential for unused memory in
-either pool is very undesirable.
-
-In high memory environments, this is desirable when you want to use the
-RTEMS "unlimited" objects option. You will be able to create objects
-until you run out of all available memory rather then just until you
-run out of RTEMS Workspace.
-
-.. COMMENT: === CONFIGURE_MICROSECONDS_PER_TICK ===
-
-Length of Each Clock Tick
--------------------------
-.. index:: CONFIGURE_MICROSECONDS_PER_TICK
-.. index:: tick quantum
-
-*CONSTANT:*
- ``CONFIGURE_MICROSECONDS_PER_TICK``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- This is not defined by default. When not defined,
- the clock tick quantum is configured to be 10,000
- microseconds which is ten (10) milliseconds.
-
-**DESCRIPTION:**
-
-This constant is used to specify the length of time between clock ticks.
-
-When the clock tick quantum value is too low, the system will spend so
-much time processing clock ticks that it does not have processing time
-available to perform application work. In this case, the system will
-become unresponsive.
-
-The lowest practical time quantum varies widely based upon the speed
-of the target hardware and the architectural overhead associated with
-interrupts. In general terms, you do not want to configure it lower than
-is needed for the application.
-
-The clock tick quantum should be selected such that it all blocking and
-delay times in the application are evenly divisible by it. Otherwise,
-rounding errors will be introduced which may negatively impact the
-application.
-
-**NOTES:**
-
-This configuration parameter has no impact if the Clock Tick Device
-driver is not configured.
-
-There may be BSP specific limits on the resolution or maximum value of
-a clock tick quantum.
-
-.. COMMENT: === CONFIGURE_TICKS_PER_TIMESLICE ===
-
-Specifying Timeslicing Quantum
-------------------------------
-.. index:: CONFIGURE_TICKS_PER_TIMESLICE
-.. index:: ticks per timeslice
-
-*CONSTANT:*
- ``CONFIGURE_TICKS_PER_TIMESLICE``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 50.
-
-**DESCRIPTION:**
-
-This configuration parameter specifies the length of the timeslice
-quantum in ticks for each task.
-
-**NOTES:**
-
-This configuration parameter has no impact if the Clock Tick Device
-driver is not configured.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_PRIORITY ===
-
-Specifying the Number of Thread Priority Levels
------------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_PRIORITY
-.. index:: maximum priority
-.. index:: number of priority levels
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_PRIORITY``
-
-*DATA TYPE:*
- Unsigned integer (``uint8_t``).
-
-*RANGE:*
- Valid values for this configuration parameter must be one (1) less than
- than a power of two (2) between 4 and 256 inclusively. In other words,
- valid values are 3, 7, 31, 63, 127, and 255.
-
-*DEFAULT VALUE:*
- The default value is 255, because RTEMS must support 256 priority levels to be
- compliant with various standards. These priorities range from zero (0) to 255.
-
-**DESCRIPTION:**
-
-This configuration parameter specified the maximum numeric priority
-of any task in the system and one less that the number of priority levels
-in the system.
-
-Reducing the number of priorities in the system reduces the amount of
-memory allocated from the RTEMS Workspace.
-
-**NOTES:**
-
-The numerically greatest priority is the logically lowest priority in
-the system and will thus be used by the IDLE task.
-
-Priority zero (0) is reserved for internal use by RTEMS and is not
-available to applications.
-
-With some schedulers, reducing the number of priorities can reduce the
-amount of memory used by the scheduler. For example, the Deterministic
-Priority Scheduler (DPS) used by default uses three pointers of storage
-per priority level. Reducing the number of priorities from 256 levels
-to sixteen (16) can reduce memory usage by about three (3) kilobytes.
-
-.. COMMENT: === CONFIGURE_MINIMUM_TASK_STACK_SIZE ===
-
-Specifying the Minimum Task Size
---------------------------------
-.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE
-.. index:: minimum task stack size
-
-*CONSTANT:*
- ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- This is not defined by default, which sets the executive to the recommended
- minimum stack size for this processor.
-
-**DESCRIPTION:**
-
-The configuration parameter is set to the number of bytes the application
-wants the minimum stack size to be for every task or thread in the system.
-
-Adjusting this parameter should be done with caution. Examining the actual
-usage using the Stack Checker Usage Reporting facility is recommended.
-
-**NOTES:**
-
-This parameter can be used to lower the minimum from that
-recommended. This can be used in low memory systems to reduce memory
-consumption for stacks. However, this must be done with caution as it
-could increase the possibility of a blown task stack.
-
-This parameter can be used to increase the minimum from that
-recommended. This can be used in higher memory systems to reduce the
-risk of stack overflow without performing analysis on actual consumption.
-
-.. COMMENT: === CONFIGURE_INTERRUPT_STACK_SIZE ===
-
-Configuring the Size of the Interrupt Stack
--------------------------------------------
-.. index:: CONFIGURE_INTERRUPT_STACK_SIZE
-.. index:: interrupt stack size
-
-*CONSTANT:*
- ``CONFIGURE_INTERRUPT_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is CONFIGURE_MINIMUM_TASK_STACK_SIZE, which is the minimum
- interrupt stack size.
-
-**DESCRIPTION:**
-
-``CONFIGURE_INTERRUPT_STACK_SIZE`` is set to the size of the
-interrupt stack. The interrupt stack size is often set by the BSP but
-since this memory may be allocated from the RTEMS Workspace, it must be
-accounted for.
-
-**NOTES:**
-
-In some BSPs, changing this constant does NOT change the
-size of the interrupt stack, only the amount of memory
-reserved for it.
-
-Patches which result in this constant only being used in memory
-calculations when the interrupt stack is intended to be allocated
-from the RTEMS Workspace would be welcomed by the RTEMS Project.
-
-.. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS ===
-
-
-Reserve Task/Thread Stack Memory Above Minimum
-----------------------------------------------
-.. index:: CONFIGURE_EXTRA_TASK_STACKS
-.. index:: memory for task tasks
-
-*CONSTANT:*
- ``CONFIGURE_EXTRA_TASK_STACKS``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-This configuration parameter is set to the number of bytes the
-applications wishes to add to the task stack requirements calculated
-by ``<rtems/confdefs.h>``.
-
-**NOTES:**
-
-This parameter is very important. If the application creates tasks with
-stacks larger then the minimum, then that memory is NOT accounted for
-by ``<rtems/confdefs.h>``.
-
-.. COMMENT: === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY ===
-
-Automatically Zeroing the RTEMS Workspace and C Program Heap
-------------------------------------------------------------
-.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
-.. index:: clear C Program Heap
-.. index:: clear RTEMS Workspace
-.. index:: zero C Program Heap
-.. index:: zero RTEMS Workspace
-
-*CONSTANT:*
- ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default, unless overridden by the BSP.
- The default is *NOT* to zero out the RTEMS Workspace or C Program Heap.
-
-**DESCRIPTION:**
-
-This macro indicates whether RTEMS should zero the RTEMS Workspace and
-C Program Heap as part of its initialization. If defined, the memory
-regions are zeroed. Otherwise, they are not.
-
-**NOTES:**
-
-Zeroing memory can add significantly to system boot time. It is not
-necessary for RTEMS but is often assumed by support libraries.
-
-.. COMMENT: === CONFIGURE_STACK_CHECKER_ENABLED ===
-
-Enable The Task Stack Usage Checker
------------------------------------
-.. index:: CONFIGURE_STACK_CHECKER_ENABLED
-
-*CONSTANT:*
- ``CONFIGURE_STACK_CHECKER_ENABLED``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default, and thus stack checking is disabled.
-
-**DESCRIPTION:**
-
-This configuration parameter is defined when the application wishes to
-enable run-time stack bounds checking.
-
-**NOTES:**
-
-In 4.9 and older, this configuration parameter was named``STACK_CHECKER_ON``.
-
-This increases the time required to create tasks as well as adding
-overhead to each context switch.
-
-.. COMMENT: === CONFIGURE_INITIAL_EXTENSIONS ===
-
-Specify Application Specific User Extensions
---------------------------------------------
-.. index:: CONFIGURE_INITIAL_EXTENSIONS
-
-*CONSTANT:*
- ``CONFIGURE_INITIAL_EXTENSIONS``
-
-*DATA TYPE:*
- List of user extension initializers (``rtems_extensions_table``).
-
-*RANGE:*
- Undefined or a list of one or more user extensions.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application,
-then this application specific set of initial extensions will be placed
-in the initial extension table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === Custom Stack Allocator ===
-
-Configuring Custom Task Stack Allocation
-========================================
-
-RTEMS allows the application or BSP to define its own allocation and
-deallocation methods for task stacks. This can be used to place task
-stacks in special areas of memory or to utilize a Memory Management Unit
-so that stack overflows are detected in hardware.
-
-.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR_INIT ===
-
-Custom Task Stack Allocator Initialization
-------------------------------------------
-.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT
-
-*CONSTANT:*
- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
-
-*DATA TYPE:*
- Function pointer.
-
-*RANGE:*
- Undefined, NULL or valid function pointer.
-
-*DEFAULT VALUE:*
- The default value is NULL, which indicates that
- task stacks will be allocated from the RTEMS Workspace.
-
-**DESCRIPTION:**
-
-``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization
-method for an application or BSP specific task stack allocation
-implementation.
-
-**NOTES:**
-
-A correctly configured system must configure the following to be consistent:
-
-- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
-
-- ``CONFIGURE_TASK_STACK_ALLOCATOR``
-
-- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-
-.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR ===
-
-Custom Task Stack Allocator
----------------------------
-.. index:: CONFIGURE_TASK_STACK_ALLOCATOR
-
-.. index:: task stack allocator
-
-*CONSTANT:*
- ``CONFIGURE_TASK_STACK_ALLOCATOR``
-
-*DATA TYPE:*
- Function pointer.
-
-*RANGE:*
- Undefined or valid function pointer.
-
-*DEFAULT VALUE:*
- The default value is ``_Workspace_Allocate``, which indicates
- that task stacks will be allocated from the RTEMS Workspace.
-
-**DESCRIPTION:**
-
-``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided
-routine to allocate task stacks.
-
-**NOTES:**
-
-A correctly configured system must configure the following to be consistent:
-
-- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
-
-- ``CONFIGURE_TASK_STACK_ALLOCATOR``
-
-- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-
-.. COMMENT: === CONFIGURE_TASK_STACK_DEALLOCATOR ===
-
-Custom Task Stack Deallocator
------------------------------
-.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR
-.. index:: task stack deallocator
-
-*CONSTANT:*
- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-
-*DATA TYPE:*
- Function pointer.
-
-*RANGE:*
- Undefined or valid function pointer.
-
-*DEFAULT VALUE:*
- The default value is ``_Workspace_Free``, which indicates that
- task stacks will be allocated from the RTEMS Workspace.
-
-**DESCRIPTION:**
-
-``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided
-routine to free task stacks.
-
-**NOTES:**
-
-A correctly configured system must configure the following to be consistent:
-
-- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
-
-- ``CONFIGURE_TASK_STACK_ALLOCATOR``
-
-- ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-
-.. COMMENT: === Classic API Message Buffers ===
-
-Configuring Memory for Classic API Message Buffers
-==================================================
-
-This section describes the configuration parameters related to specifying
-the amount of memory reserved for Classic API Message Buffers.
-
-.. COMMENT: === CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE ===
-
-Calculate Memory for a Single Classic Message API Message Queue
----------------------------------------------------------------
-.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE
-.. index:: memory for a single message queue’s buffers
-
-*CONSTANT:*
- ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is None.
-
-**DESCRIPTION:**
-
-This is a helper macro which is used to assist in computing the total
-amount of memory required for message buffers. Each message queue will
-have its own configuration with maximum message size and maximum number
-of pending messages.
-
-The interface for this macro is as follows:
-.. code:: c
-
- CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)
-
-Where ``max_messages`` is the maximum number of pending messages
-and ``size_per`` is the size in bytes of the user message.
-
-**NOTES:**
-
-This macro is only used in support of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``.
-
-.. COMMENT: === CONFIGURE_MESSAGE_BUFFER_MEMORY ===
-
-Reserve Memory for All Classic Message API Message Queues
----------------------------------------------------------
-.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY
-.. index:: configure message queue buffer memory
-
-*CONSTANT:*
- ``CONFIGURE_MESSAGE_BUFFER_MEMORY``
-
-*DATA TYPE:*
- integer summation macro
-
-*RANGE:*
- undefined (zero) or calculation resulting in a positive integer
-
-*DEFAULT VALUE:*
- This is not defined by default, and zero (0) memory is reserved.
-
-**DESCRIPTION:**
-
-This macro is set to the number of bytes the application requires to be
-reserved for pending Classic API Message Queue buffers.
-
-**NOTES:**
-
-The following illustrates how the help macro``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE`` can be used to assist in
-calculating the message buffer memory required. In this example, there
-are two message queues used in this application. The first message
-queue has maximum of 24 pending messages with the message structure
-defined by the type ``one_message_type``. The other message queue
-has maximum of 500 pending messages with the message structure defined
-by the type ``other_message_type``.
-.. code:: c
-
- #define CONFIGURE_MESSAGE_BUFFER_MEMORY \\
- (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \\
- 24, sizeof(one_message_type) + \\
- CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \\
- 500, sizeof(other_message_type) \\
- )
-
-.. COMMENT: === Seldom Used Configuration Parameters ===
-
-Seldom Used Configuration Parameters
-====================================
-
-This section describes configuration parameters supported by``<rtems/confdefs.h>`` which are seldom used by applications. These
-parameters tend to be oriented to debugging system configurations
-and providing work-arounds when the memory estimated by``<rtems/confdefs.h>`` is incorrect.
-
-.. COMMENT: === CONFIGURE_MEMORY_OVERHEAD ===
-
-
-Specify Memory Overhead
------------------------
-.. index:: CONFIGURE_MEMORY_OVERHEAD
-
-*CONSTANT:*
- ``CONFIGURE_MEMORY_OVERHEAD``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-Thie parameter is set to the number of kilobytes the application wishes
-to add to the requirements calculated by ``<rtems/confdefs.h>``.
-
-**NOTES:**
-
-This configuration parameter should only be used when it is suspected that
-a bug in ``<rtems/confdefs.h>`` has resulted in an underestimation.
-Typically the memory allocation will be too low when an application does
-not account for all message queue buffers or task stacks.
-
-.. COMMENT: === CONFIGURE_HAS_OWN_CONFIGURATION_TABLE ===
-
-Do Not Generate Configuration Information
------------------------------------------
-.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_HAS_OWN_CONFIGURATION_TABLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-This configuration parameter should only be defined if the application
-is providing their own complete set of configuration tables.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === C Library Support Configuration ===
-
-C Library Support Configuration
-===============================
-
-This section defines the file system and IO library
-related configuration parameters supported by``<rtems/confdefs.h>``.
-
-.. COMMENT: === CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS ===
-
-Specify Maximum Number of File Descriptors
-------------------------------------------
-.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS
-.. index:: maximum file descriptors
-
-*CONSTANT:*
- ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- If ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined, then the
- default value is 3, otherwise the default value is 0.
- Three file descriptors allows RTEMS to support standard input, output, and
- error I/O streams on ``/dev/console``.
-
-**DESCRIPTION:**
-
-This configuration parameter is set to the maximum number of file like objects
-that can be concurrently open.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_TERMIOS_DISABLED ===
-
-Disable POSIX Termios Support
------------------------------
-.. index:: CONFIGURE_TERMIOS_DISABLED
-
-*CONSTANT:*
- ``CONFIGURE_TERMIOS_DISABLED``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default, and resources are reserved for the
- termios functionality.
-
-**DESCRIPTION:**
-
-This configuration parameter is defined if the software implementing
-POSIX termios functionality is not going to be used by this application.
-
-**NOTES:**
-
-The termios support library should not be included in an application
-executable unless it is directly referenced by the application or a
-device driver.
-
-.. COMMENT: === CONFIGURE_NUMBER_OF_TERMIOS_PORTS ===
-
-Specify Maximum Termios Ports
------------------------------
-.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS
-
-*CONSTANT:*
- ``CONFIGURE_NUMBER_OF_TERMIOS_PORTS``
-
-*DATA TYPE:*
- Unsigned integer.
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 1, so a console port can be used.
-
-**DESCRIPTION:**
-
-This configuration parameter is set to the number of ports using the
-termios functionality. Each concurrently active termios port requires
-resources.
-
-**NOTES:**
-
-If the application will be using serial ports
-including, but not limited to, the Console Device
-(e.g. ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``), then it is
-highly likely that this configuration parameter should NOT be is defined.
-
-.. COMMENT: === File System Configuration Parameters ===
-
-File System Configuration Parameters
-====================================
-
-This section defines File System related configuration parameters.
-
-.. COMMENT: === CONFIGURE_HAS_OWN_MOUNT_TABLE ===
-
-Providing Application Specific Mount Table
-------------------------------------------
-.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_HAS_OWN_MOUNT_TABLE``
-
-*DATA TYPE:*
- Undefined or an array of type ``rtems_filesystem_mount_table_t``.
-
-*RANGE:*
- Undefined or an array of type ``rtems_filesystem_mount_table_t``.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-This configuration parameter is defined when the application
-provides their own filesystem mount table. The mount table is an
-array of ``rtems_filesystem_mount_table_t`` entries pointed
-to by the global variable ``rtems_filesystem_mount_table``.
-The number of entries in this table is in an integer variable named``rtems_filesystem_mount_table_t``.
-
-.. COMMENT: XXX - is the variable name for the count right?
-
-**NOTES:**
-
-None.
-
-.. COMMENT: XXX - Please provide an example
-
-.. COMMENT: === CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM ===
-
-Configure devFS as Root File System
------------------------------------
-.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
-
-*CONSTANT:*
- ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default. If no other root file system
- configuration parameters are specified, the IMFS will be used as the
- root file system.
-
-**DESCRIPTION:**
-
-This configuration parameter is defined if the application wishes to
-use the device-only filesytem as the root file system.
-
-**NOTES:**
-
-The device-only filesystem supports only device nodes and is smaller in
-executable code size than the full IMFS and miniIMFS.
-
-The devFS is comparable in functionality to the pseudo-filesystem name
-space provided before RTEMS release 4.5.0.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_DEVICES ===
-
-Specifying Maximum Devices for devFS
-------------------------------------
-.. index:: CONFIGURE_MAXIMUM_DEVICES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_DEVICES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- If ``BSP_MAXIMUM_DEVICES`` is defined, then the
- default value is ``BSP_MAXIMUM_DEVICES``, otherwise the default value is 4.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_DEVICES`` is defined to the number of
-individual devices that may be registered in the device file system (devFS).
-
-**NOTES:**
-
-This option is specific to the device file system (devFS) and should not be
-confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only
-impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified.
-
-.. COMMENT: === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM ===
-
-Disable File System Support
----------------------------
-.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default. If no other root file system
- configuration parameters are specified, the IMFS will be used as the
- root file system.
-
-**DESCRIPTION:**
-
-This configuration parameter is defined if the application dose not
-intend to use any kind of filesystem support. This include the device
-infrastructure necessary to support ``printf()``.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM ===
-
-Use a Root IMFS with a Minimalistic Feature Set
------------------------------------------------
-.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM
-
-*CONSTANT:*
- ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the following configuration
-options will be defined as well
-
-- ``CONFIGURE_IMFS_DISABLE_CHMOD``,
-
-- ``CONFIGURE_IMFS_DISABLE_CHOWN``,
-
-- ``CONFIGURE_IMFS_DISABLE_UTIME``,
-
-- ``CONFIGURE_IMFS_DISABLE_LINK``,
-
-- ``CONFIGURE_IMFS_DISABLE_SYMLINK``,
-
-- ``CONFIGURE_IMFS_DISABLE_READLINK``,
-
-- ``CONFIGURE_IMFS_DISABLE_RENAME``, and
-
-- ``CONFIGURE_IMFS_DISABLE_UNMOUNT``.
-
-.. COMMENT: === CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK ===
-
-Specify Block Size for IMFS
----------------------------
-.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Valid values for this configuration parameter are a power of two (2)
- between 16 and 512 inclusive. In other words, valid values are 16,
- 32, 64, 128, 256,and 512.
-
-*DEFAULT VALUE:*
- The default IMFS block size is 128 bytes.
-
-**DESCRIPTION:**
-
-This configuration parameter specifies the block size for in-memory files
-managed by the IMFS. The configured block size has two impacts. The first
-is the average amount of unused memory in the last block of each file. For
-example, when the block size is 512, on average one-half of the last block
-of each file will remain unused and the memory is wasted. In contrast,
-when the block size is 16, the average unused memory per file is only
-8 bytes. However, it requires more allocations for the same size file
-and thus more overhead per block for the dynamic memory management.
-
-Second, the block size has an impact on the maximum size file that can
-be stored in the IMFS. With smaller block size, the maximum file size
-is correspondingly smaller. The following shows the maximum file size
-possible based on the configured block size:
-
-- when the block size is 16 bytes, the maximum file size is 1,328
- bytes.
-
-- when the block size is 32 bytes, the maximum file size is 18,656
- bytes.
-
-- when the block size is 64 bytes, the maximum file size is 279,488
- bytes.
-
-- when the block size is 128 bytes, the maximum file size is
- 4,329,344 bytes.
-
-- when the block size is 256 bytes, the maximum file size is
- 68,173,568 bytes.
-
-- when the block size is 512 bytes, the maximum file size is
- 1,082,195,456 bytes.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHOWN ===
-
-Disable Change Owner Support of Root IMFS
------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_CHOWN
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_CHOWN``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to change the
-owner is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHMOD ===
-
-Disable Change Mode Support of Root IMFS
-----------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_CHMOD
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_CHMOD``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to change the
-mode is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_UTIME ===
-
-Disable Change Times Support of Root IMFS
------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_UTIME
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_UTIME``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to change times
-is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_LINK ===
-
-Disable Create Hard Link Support of Root IMFS
----------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_LINK
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_LINK``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to create hard
-links is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_SYMLINK ===
-
-Disable Create Symbolic Link Support of Root IMFS
--------------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_SYMLINK``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to create
-symbolic links is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_READLINK ===
-
-Disable Read Symbolic Link Support of Root IMFS
------------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_READLINK
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_READLINK``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to read symbolic
-links is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_RENAME ===
-
-Disable Rename Support of Root IMFS
------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_RENAME
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_RENAME``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to rename nodes
-is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_READDIR ===
-
-Disable Directory Read Support of Root IMFS
--------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_READDIR
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_READDIR``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to read a
-directory is disabled in the root IMFS. It is still possible to open nodes in
-a directory.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_MOUNT ===
-
-Disable Mount Support of Root IMFS
-----------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_MOUNT
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_MOUNT``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to mount other
-file systems is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_UNMOUNT ===
-
-Disable Unmount Support of Root IMFS
-------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_UNMOUNT``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to unmount file
-systems is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD ===
-
-Disable Make Nodes Support of Root IMFS
----------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_MKNOD
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_MKNOD``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to make
-directories, devices, regular files and FIFOs is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD_FILE ===
-
-Disable Make Files Support of Root IMFS
----------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to make regular
-files is disabled in the root IMFS.
-
-.. COMMENT: === CONFIGURE_IMFS_DISABLE_RMNOD ===
-
-Disable Remove Nodes Support of Root IMFS
------------------------------------------
-.. index:: CONFIGURE_IMFS_DISABLE_RMNOD
-
-*CONSTANT:*
- ``CONFIGURE_IMFS_DISABLE_RMNOD``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-In case this configuration option is defined, then the support to remove nodes
-is disabled in the root IMFS.
-
-.. COMMENT: === Block Device Cache Configuration ===
-
-Block Device Cache Configuration
-================================
-
-This section defines Block Device Cache (bdbuf) related configuration
-parameters.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ===
-
-Enable Block Device Cache
--------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-Provides a Block Device Cache configuration.
-
-**NOTES:**
-
-Each option of the Block Device Cache configuration can be explicitly set by
-the user with the configuration options below. The Block Device Cache is used
-for example by the RFS and DOSFS file systems.
-
-.. COMMENT: === CONFIGURE_BDBUF_CACHE_MEMORY_SIZE ===
-
-Size of the Cache Memory
-------------------------
-.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 32768 bytes.
-
-**DESCRIPTION:**
-
-Size of the cache memory in bytes.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MIN_SIZE ===
-
-Minimum Size of a Buffer
-------------------------
-.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 512 bytes.
-
-**DESCRIPTION:**
-
-Defines the minimum size of a buffer in bytes.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MAX_SIZE ===
-
-Maximum Size of a Buffer
-------------------------
-.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- It must be positive and an integral multiple of the buffer minimum size.
-
-*DEFAULT VALUE:*
- The default value is 4096 bytes.
-
-**DESCRIPTION:**
-
-Defines the maximum size of a buffer in bytes.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SWAPOUT_SWAP_PERIOD ===
-
-Swapout Task Swap Period
-------------------------
-.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD
-
-*CONSTANT:*
- ``CONFIGURE_SWAPOUT_SWAP_PERIOD``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 250 milliseconds.
-
-**DESCRIPTION:**
-
-Defines the swapout task swap period in milliseconds.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SWAPOUT_BLOCK_HOLD ===
-
-Swapout Task Maximum Block Hold Time
-------------------------------------
-.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD
-
-*CONSTANT:*
- ``CONFIGURE_SWAPOUT_BLOCK_HOLD``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 1000 milliseconds.
-
-**DESCRIPTION:**
-
-Defines the swapout task maximum block hold time in milliseconds.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SWAPOUT_TASK_PRIORITY ===
-
-Swapout Task Priority
----------------------
-.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY
-
-*CONSTANT:*
- ``CONFIGURE_SWAPOUT_TASK_PRIORITY``
-
-*DATA TYPE:*
- Task priority (``rtems_task_priority``).
-
-*RANGE:*
- Valid task priority.
-
-*DEFAULT VALUE:*
- The default value is 15.
-
-**DESCRIPTION:**
-
-Defines the swapout task priority.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS ===
-
-Maximum Blocks per Read-Ahead Request
--------------------------------------
-.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-Defines the maximum blocks per read-ahead request.
-
-**NOTES:**
-
-A value of 0 disables the read-ahead task (default). The read-ahead task will
-issue speculative read transfers if a sequential access pattern is detected.
-This can improve the performance on some systems.
-
-.. COMMENT: === CONFIGURE_BDBUF_MAX_WRITE_BLOCKS ===
-
-Maximum Blocks per Write Request
---------------------------------
-.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 16.
-
-**DESCRIPTION:**
-
-Defines the maximum blocks per write request.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_BDBUF_TASK_STACK_SIZE ===
-
-Task Stack Size of the Block Device Cache Tasks
------------------------------------------------
-.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_TASK_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is RTEMS_MINIMUM_STACK_SIZE.
-
-**DESCRIPTION:**
-
-Defines the task stack size of the Block Device Cache tasks in bytes.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ===
-
-Read-Ahead Task Priority
-------------------------
-.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY
-
-*CONSTANT:*
- ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY``
-
-*DATA TYPE:*
- Task priority (``rtems_task_priority``).
-
-*RANGE:*
- Valid task priority.
-
-*DEFAULT VALUE:*
- The default value is 15.
-
-**DESCRIPTION:**
-
-Defines the read-ahead task priority.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASKS ===
-
-Swapout Worker Task Count
--------------------------
-.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS
-
-*CONSTANT:*
- ``CONFIGURE_SWAPOUT_WORKER_TASKS``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-Defines the swapout worker task count.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY ===
-
-Swapout Worker Task Priority
-----------------------------
-.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY
-
-*CONSTANT:*
- ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY``
-
-*DATA TYPE:*
- Task priority (``rtems_task_priority``).
-
-*RANGE:*
- Valid task priority.
-
-*DEFAULT VALUE:*
- The default value is 15.
-
-**DESCRIPTION:**
-
-Defines the swapout worker task priority.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === BSP Specific Settings ===
-
-BSP Specific Settings
-=====================
-
-This section describes BSP specific configuration settings used by``<rtems/confdefs.h>``. The BSP specific configuration settings are
-defined in ``<bsp.h>``.
-
-.. COMMENT: === Disable BSP Settings ===
-
-Disable BSP Configuration Settings
-----------------------------------
-.. index:: CONFIGURE_DISABLE_BSP_SETTINGS
-
-*CONSTANT:*
- ``CONFIGURE_DISABLE_BSP_SETTINGS``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-All BSP specific configuration settings can be disabled by the application
-with the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK ===
-
-Specify BSP Supports sbrk()
----------------------------
-.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
-
-*CONSTANT:*
- ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-This configuration parameter is defined by a BSP to indicate that it
-does not allocate all available memory to the C Program Heap used by
-the Malloc Family of routines.
-
-If defined, when ``malloc()`` is unable to allocate memory, it will
-call the BSP supplied ``sbrk()`` to obtain more memory.
-
-**NOTES:**
-
-This parameter should not be defined by the application. Only the BSP
-knows how it allocates memory to the C Program Heap.
-
-.. COMMENT: === BSP_IDLE_TASK_BODY ===
-
-Specify BSP Specific Idle Task
-------------------------------
-.. index:: BSP_IDLE_TASK_BODY
-
-*CONSTANT:*
- ``BSP_IDLE_TASK_BODY``
-
-*DATA TYPE:*
- Function pointer.
-
-*RANGE:*
- Undefined or valid function pointer.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application,
-then this BSP specific idle task body will be used.
-
-**NOTES:**
-
-As it has knowledge of the specific CPU model, system controller logic,
-and peripheral buses, a BSP specific IDLE task may be capable of turning
-components off to save power during extended periods of no task activity
-
-.. COMMENT: === BSP_IDLE_TASK_STACK_SIZE ===
-
-Specify BSP Suggested Value for IDLE Task Stack Size
-----------------------------------------------------
-.. index:: BSP_IDLE_TASK_STACK_SIZE
-
-*CONSTANT:*
- ``BSP_IDLE_TASK_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application,
-then this BSP suggested idle task stack size will be used.
-
-**NOTES:**
-
-The order of precedence for configuring the IDLE task stack size is:
-
-- RTEMS default minimum stack size.
-
-- If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``.
-
-- If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``.
-
-- If defined, then the application specified``CONFIGURE_IDLE_TASK_SIZE``.
-
-.. COMMENT: XXX - add cross references to other related values.
-
-.. COMMENT: === BSP_INITIAL_EXTENSION ===
-
-Specify BSP Specific User Extensions
-------------------------------------
-.. index:: BSP_INITIAL_EXTENSION
-
-*CONSTANT:*
- ``BSP_INITIAL_EXTENSION``
-
-*DATA TYPE:*
- List of user extension initializers (``rtems_extensions_table``).
-
-*RANGE:*
- Undefined or a list of user extension initializers.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP
-specific initial extension will be placed as the last entry in the initial
-extension table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === BSP_INTERRUPT_STACK_SIZE ===
-
-Specifying BSP Specific Interrupt Stack Size
---------------------------------------------
-.. index:: BSP_INTERRUPT_STACK_SIZE
-
-*CONSTANT:*
- ``BSP_INTERRUPT_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application,
-then this BSP specific interrupt stack size will be used.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === BSP_MAXIMUM_DEVICES ===
-
-Specifying BSP Specific Maximum Devices
----------------------------------------
-.. index:: BSP_MAXIMUM_DEVICES
-
-*CONSTANT:*
- ``BSP_MAXIMUM_DEVICES``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application,
-then this BSP specific maximum device count will be used.
-
-**NOTES:**
-
-This option is specific to the device file system (devFS) and should not be
-confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only
-impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified.
-
-.. COMMENT: === BSP_ZERO_WORKSPACE_AUTOMATICALLY ===
-
-BSP Recommends RTEMS Workspace be Cleared
------------------------------------------
-.. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY
-
-*CONSTANT:*
- ``BSP_ZERO_WORKSPACE_AUTOMATICALLY``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-If ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined by the BSP and``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` is not defined by the
-application, then the workspace will be zeroed automatically.
-
-**NOTES:**
-
-Zeroing memory can add significantly to system boot time. It is not
-necessary for RTEMS but is often assumed by support libraries.
-
-.. COMMENT: === CONFIGURE_BSP_PREREQUISITE_DRIVERS ===
-
-Specify BSP Prerequisite Drivers
---------------------------------
-.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS
-
-*CONSTANT:*
- ``CONFIGURE_BSP_PREREQUISITE_DRIVERS``
-
-*DATA TYPE:*
- List of device driver initializers (``rtems_driver_address_table``).
-
-*RANGE:*
- Undefined or array of device drivers.
-
-*DEFAULT VALUE:*
- This option is BSP specific.
-
-**DESCRIPTION:**
-
-``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device
-drivers it needs to include in the Device Driver Table. This should be
-defined to the set of device driver entries that will be placed in the
-table at the *FRONT* of the Device Driver Table and initialized before
-any other drivers *INCLUDING* any application prerequisite drivers.
-
-**NOTES:**
-
-``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs
-to configure common infrastructure such as bus controllers or probe
-for devices.
-
-.. COMMENT: === Idle Task Configuration ===
-
-Idle Task Configuration
-=======================
-
-This section defines the IDLE task related configuration parameters
-supported by ``<rtems/confdefs.h>``.
-
-.. COMMENT: === CONFIGURE_IDLE_TASK_BODY ===
-
-Specify Application Specific Idle Task Body
--------------------------------------------
-.. index:: CONFIGURE_IDLE_TASK_BODY
-
-*CONSTANT:*
- ``CONFIGURE_IDLE_TASK_BODY``
-
-*DATA TYPE:*
- Function pointer.
-
-*RANGE:*
- Undefined or valid function pointer.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding
-to the application specific IDLE thread body. If not specified, the
-BSP or RTEMS default IDLE thread body will be used.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_IDLE_TASK_STACK_SIZE ===
-
-Specify Idle Task Stack Size
-----------------------------
-.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE
-
-*CONSTANT:*
- ``CONFIGURE_IDLE_TASK_STACK_SIZE``
-
-*DATA TYPE:*
- Unsigned integer (``size_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- The default value is RTEMS_MINIMUM_STACK_SIZE.
-
-**DESCRIPTION:**
-
-``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the
-desired stack size for the IDLE task.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION ===
-
-Specify Idle Task Performs Application Initialization
------------------------------------------------------
-.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
-
-*CONSTANT:*
- ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default, the user is assumed
- to provide one or more initialization tasks.
-
-**DESCRIPTION:**
-
-``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set to
-indicate that the user has configured *NO* user initialization tasks
-or threads and that the user provided IDLE task will perform application
-initialization and then transform itself into an IDLE task.
-
-**NOTES:**
-
-If you use this option be careful, the user IDLE task *CANNOT* block
-at all during the initialization sequence. Further, once application
-initialization is complete, it must make itself preemptible and enter
-an IDLE body loop.
-
-The IDLE task must run at the lowest priority of all tasks in the system.
-
-.. COMMENT: === Scheduler Algorithm Configuration ===
-
-Scheduler Algorithm Configuration
-=================================
-
-This section defines the configuration parameters related to selecting a
-scheduling algorithm for an application. For the schedulers built into
-RTEMS, the configuration is straightforward. All that is required is
-to define the configuration macro which specifies which scheduler you
-want for in your application. The currently available schedulers are:
-
-The pluggable scheduler interface also enables the user to provide their
-own scheduling algorithm. If you choose to do this, you must define
-multiple configuration macros.
-
-.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY ===
-
-Use Deterministic Priority Scheduler
-------------------------------------
-.. index:: CONFIGURE_SCHEDULER_PRIORITY
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_PRIORITY``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is defined by default.
- This is the default scheduler and specifying this
- configuration parameter is redundant.
-
-**DESCRIPTION:**
-
-The Deterministic Priority Scheduler is the default scheduler in RTEMS
-for uni-processor applications and is designed for predictable performance
-under the highest loads. It can block or unblock a thread in a constant
-amount of time. This scheduler requires a variable amount of memory
-based upon the number of priorities configured in the system.
-
-**NOTES:**
-
-This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_PRIORITY`` although this is equivalent to the
-default behavior.
-
-.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE ===
-
-Use Simple Priority Scheduler
------------------------------
-.. index:: CONFIGURE_SCHEDULER_SIMPLE
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_SIMPLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-When defined, the Simple Priority Scheduler is used at the thread
-scheduling algorithm. This is an alternative scheduler in RTEMS.
-It is designed to provide the same task scheduling behaviour as the
-Deterministic Priority Scheduler while being simpler in implementation
-and uses less memory for data management. It maintains a single sorted
-list of all ready threads. Thus blocking or unblocking a thread is not
-a constant time operation with this scheduler.
-
-This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_SIMPLE``.
-
-**NOTES:**
-
-This scheduler is appropriate for use in small systems where RAM is limited.
-
-.. COMMENT: === CONFIGURE_SCHEDULER_EDF ===
-
-Use Earliest Deadline First Scheduler
--------------------------------------
-.. index:: CONFIGURE_SCHEDULER_EDF
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_EDF``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in
-RTEMS for uni-processor applications. The EDF schedules tasks with dynamic
-priorities equal to deadlines. The deadlines are declared using only
-Rate Monotonic manager which handles periodic behavior. Period is always
-equal to deadline. If a task does not have any deadline declared or the
-deadline is cancelled, the task is considered a background task which is
-scheduled in case no deadline-driven tasks are ready to run. Moreover,
-multiple background tasks are scheduled according their priority assigned
-upon initialization. All ready tasks reside in a single ready queue.
-
-This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_EDF``.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SCHEDULER_CBS ===
-
-Use Constant Bandwidth Server Scheduler
----------------------------------------
-.. index:: CONFIGURE_SCHEDULER_CBS
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_CBS``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler
-in RTEMS for uni-processor applications. The CBS is a budget aware extension
-of EDF scheduler. The goal of this scheduler is to ensure temporal
-isolation of tasks. The CBS is equipped with a set of additional rules
-and provides with an extensive API.
-
-This scheduler may be explicitly selected by defining``CONFIGURE_SCHEDULER_CBS``.
-
-.. COMMENT: XXX - add cross reference to API chapter
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY_SMP ===
-
-Use Deterministic Priority SMP Scheduler
-----------------------------------------
-.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-The Deterministic Priority SMP Scheduler is derived from the Deterministic
-Priority Scheduler but is capable of scheduling threads across multiple
-processors.
-
-In a configuration with SMP enabled at configure time, it may be
-explicitly selected by defining ``CONFIGURE_SCHEDULER_PRIORITY_SMP``.
-
-**NOTES:**
-
-This scheduler is only available when RTEMS is configured with SMP
-support enabled.
-
-This scheduler is currently the default in SMP configurations and is
-only selected when ``CONFIGURE_SMP_APPLICATION`` is defined.
-
-.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE_SMP ===
-
-Use Simple SMP Priority Scheduler
----------------------------------
-.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-The Simple SMP Priority Scheduler is derived from the Simple Priority
-Scheduler but is capable of scheduling threads across multiple processors.
-It is designed to provide the same task scheduling behaviour as the
-Deterministic Priority Scheduler while distributing threads across
-multiple processors. Being based upon the Simple Priority Scheduler, it also
-maintains a single sorted list of all ready threads. Thus blocking or
-unblocking a thread is not a constant time operation with this scheduler.
-
-In addition, when allocating threads to processors, the algorithm is not
-constant time. This algorithm was not designed with efficiency as a
-primary design goal. Its primary design goal was to provide an SMP-aware
-scheduling algorithm that is simple to understand.
-
-In a configuration with SMP enabled at configure time, it may be
-explicitly selected by defining ``CONFIGURE_SCHEDULER_SIMPLE_SMP``.
-
-**NOTES:**
-
-This scheduler is only available when RTEMS is configured with SMP
-support enabled.
-
-.. COMMENT: === Configuring a Scheduler Name ===
-
-Configuring a Scheduler Name
-----------------------------
-.. index:: CONFIGURE_SCHEDULER_NAME
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_NAME``
-
-*DATA TYPE:*
- RTEMS Name (``rtems_name``).
-
-*RANGE:*
- Any value.
-
-*DEFAULT VALUE:*
- The default name is
- - ``"UCBS"`` for the Uni-Processor CBS scheduler,
- - ``"UEDF"`` for the Uni-Processor EDF scheduler,
- - ``"UPD "`` for the Uni-Processor Deterministic Priority scheduler,
- - ``"UPS "`` for the Uni-Processor Simple Priority scheduler,
- - ``"MPA "`` for the Multi-Processor Priority Affinity scheduler, and
- - ``"MPD "`` for the Multi-Processor Deterministic Priority scheduler, and
- - ``"MPS "`` for the Multi-Processor Simple Priority scheduler.
-
-**DESCRIPTION:**
-
-Schedulers can be identified via ``rtems_scheduler_ident``. The name of the scheduler is determined by the configuration.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === Configuring a User Scheduler ===
-
-Configuring a User Provided Scheduler
--------------------------------------
-.. index:: CONFIGURE_SCHEDULER_USER
-
-*CONSTANT:*
- ``CONFIGURE_SCHEDULER_USER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-RTEMS allows the application to provide its own task/thread
-scheduling algorithm. In order to do this, one must define``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its
-own scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined
-then the following additional macros must be defined:
-
-- ``CONFIGURE_SCHEDULER_CONTEXT`` must be defined to a static definition
- of the scheduler context of the user scheduler.
-
-- ``CONFIGURE_SCHEDULER_CONTROLS`` must be defined to a scheduler
- control initializer for the user scheduler.
-
-- ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of
- the per-thread information of the user scheduler.
-
-**NOTES:**
-
-At this time, the mechanics and requirements for writing a
-new scheduler are evolving and not fully documented. It is
-recommended that you look at the existing Deterministic Priority
-Scheduler in ``cpukit/score/src/schedulerpriority*.c`` for
-guidance. For guidance on the configuration macros, please examine``cpukit/sapi/include/confdefs.h`` for how these are defined for the
-Deterministic Priority Scheduler.
-
-.. COMMENT: === Configuring Clustered Schedulers ===
-
-
-Configuring Clustered Schedulers
---------------------------------
-
-Clustered scheduling helps to control the worst-case latencies in a
-multi-processor system. The goal is to reduce the amount of shared state in
-the system and thus prevention of lock contention. Modern multi-processor
-systems tend to have several layers of data and instruction caches. With
-clustered scheduling it is possible to honour the cache topology of a system
-and thus avoid expensive cache synchronization traffic.
-
-We have clustered scheduling in case the set of processors of a system is
-partitioned into non-empty pairwise-disjoint subsets. These subsets are called
-clusters. Clusters with a cardinality of one are partitions. Each cluster is
-owned by exactly one scheduler instance. In order to use clustered
-scheduling the application designer has to answer two questions.
-
-# How is the set of processors partitioned into clusters?
-
-# Which scheduler is used for which cluster?
-
-**CONFIGURATION:**
-
-The schedulers in an SMP system are statically configured on RTEMS. Firstly
-the application must select which scheduling algorithms are available with the
-following defines
-
-- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``,
-
-- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and
-
-- ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``.
-
-This is necessary to calculate the per-thread overhead introduced by the
-schedulers. After these definitions the configuration file must ``#include
-<rtems/scheduler.h>`` to have access to scheduler specific configuration macros.
-Each scheduler needs a context to store state information at run-time. To
-provide a context for each scheduler is the next step. Use the following
-macros to create scheduler contexts
-
-- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``,
-
-- ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and
-
-- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``.
-
-The ``name`` parameter is used as part of a designator for a global
-variable, so the usual C/C++ designator rules apply. Additional parameters are
-scheduler specific. The schedulers are registered in the system via the
-scheduler table. To create the scheduler table define``CONFIGURE_SCHEDULER_CONTROLS`` to a list of the following scheduler
-control initializers
-
-- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``,
-
-- ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and
-
-- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``.
-
-The ``name`` parameter must correspond to the parameter defining the
-scheduler context. The ``obj_name`` determines the scheduler object name
-and can be used in ``rtems_scheduler_ident()`` to get the scheduler object
-identifier.
-
-The last step is to define which processor uses which scheduler.
-For this purpose a scheduler assignment table must be defined. The entry count
-of this table must be equal to the configured maximum processors
-(``CONFIGURE_SMP_MAXIMUM_PROCESSORS``). A processor assignment to a
-scheduler can be optional or mandatory. The boot processor must have a
-scheduler assigned. In case the system needs more mandatory processors than
-available then a fatal run-time error will occur. To specify the scheduler
-assignments define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a list of``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros. The ``index`` parameter
-must be a valid index into the scheduler table. The ``attr`` parameter
-defines the scheduler assignment attributes. By default a scheduler assignment
-to a processor is optional. For the scheduler assignment attribute use one of
-the mutually exclusive variants
-
-- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
-
-- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
-
-- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
-
-**ERRORS:**
-
-In case one of the scheduler indices in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` is invalid a link-time error will
-occur with an undefined reference to ``RTEMS_SCHEDULER_INVALID_INDEX``.
-
-Some fatal errors may occur in case of scheduler configuration inconsistencies or a lack
-of processors on the system. The fatal source is``RTEMS_FATAL_SOURCE_SMP``. None of the errors is internal.
-
-- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot
- processor must have a scheduler assigned.
-
-- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a
- mandatory processor beyond the range of physically or virtually available
- processors. The processor demand must be reduced for this system.
-
-- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a
- mandatory processor failed during system initialization. The system may not
- have this processor at all or it could be a problem with a boot loader for
- example. Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` definition.
-
-- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not
- allowed to start multitasking on a processor with no scheduler assigned.
-
-**EXAMPLE:**
-
-The following example shows a scheduler configuration for a hypothetical
-product using two chip variants. One variant has four processors which is used
-for the normal product line and another provides eight processors for the
-high-performance product line. The first processor performs hard-real time
-control of actuators and sensors. The second processor is not used by RTEMS at
-all and runs a Linux instance to provide a graphical user interface. The
-additional processors are used for a worker thread pool to perform data
-processing operations.
-
-The processors managed by RTEMS use two Deterministic Priority scheduler
-instances capable of dealing with 256 priority levels. The scheduler with
-index zero has the name ``"IO "``. The scheduler with index one has the
-name ``"WORK"``. The scheduler assignments of the first, third and fourth
-processor are mandatory, so the system must have at least four processors,
-otherwise a fatal run-time error will occur during system startup. The
-processor assignments for the fifth up to the eighth processor are optional so
-that the same application can be used for the normal and high-performance
-product lines. The second processor has no scheduler assigned and runs Linux.
-A hypervisor will ensure that the two systems cannot interfere in an
-undesirable way.
-.. code:: c
-
- #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8
- #define CONFIGURE_MAXIMUM_PRIORITY 255
- /* Make the scheduler algorithm available \*/
- #define CONFIGURE_SCHEDULER_PRIORITY_SMP
- #include <rtems/scheduler.h>
- /* Create contexts for the two scheduler instances \*/
- RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
- RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
- /* Define the scheduler table \*/
- #define CONFIGURE_SCHEDULER_CONTROLS \\
- RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \\
- io, \\
- rtems_build_name('I', 'O', ' ', ' ') \\
- ), \\
- RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \\
- work, \\
- rtems_build_name('W', 'O', 'R', 'K') \\
- )
- /* Define the processor to scheduler assignments \*/
- #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \\
- RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
- RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \\
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
-
-.. COMMENT: === SMP Specific Configuration Parameters ===
-
-SMP Specific Configuration Parameters
-=====================================
-
-When RTEMS is configured to support SMP target systems, there are other
-configuration parameters which apply.
-
-.. COMMENT: XXX - add -enable-smp
-
-.. COMMENT: === CONFIGURE_SMP_APPLICATION ===
-
-
-Enable SMP Support for Applications
------------------------------------
-.. index:: CONFIGURE_SMP_APPLICATION
-
-*CONSTANT:*
- ``CONFIGURE_SMP_APPLICATION``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the
-application.
-
-**NOTES:**
-
-This define may go away in the future in case all RTEMS components are SMP
-ready. This configuration define is ignored on uni-processor configurations.
-
-.. COMMENT: === CONFIGURE_SMP_MAXIMUM_PROCESSORS ===
-
-Specify Maximum Processors in SMP System
-----------------------------------------
-.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS
-
-*CONSTANT:*
- ``CONFIGURE_SMP_MAXIMUM_PROCESSORS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined).
-
-**DESCRIPTION:**
-
-``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` must be set to the number of
-processors in the SMP configuration.
-
-**NOTES:**
-
-If there are more processors available than configured, the rest will be
-ignored. This configuration define is ignored on uni-processor configurations.
-
-.. COMMENT: === Device Driver Table ===
-
-Device Driver Table
-===================
-
-This section defines the configuration parameters related
-to the automatic generation of a Device Driver Table. As``<rtems/confdefs.h>`` only is aware of a small set of
-standard device drivers, the generated Device Driver
-Table is suitable for simple applications with no
-custom device drivers.
-
-Note that network device drivers are not configured in the Device Driver Table.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_DRIVERS ===
-
-Specifying the Maximum Number of Device Drivers
------------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_DRIVERS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_DRIVERS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- This is computed by default, and is set to the number of device drivers
- configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER``
- configuration parameters.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device
-drivers per node.
-
-**NOTES:**
-
-If the application will dynamically install device drivers, then this
-configuration parameter must be larger than the number of statically
-configured device drivers. Drivers configured using the``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters
-are statically installed.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ===
-
-Enable Console Device Driver
-----------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the
-application wishes to include the Console Device Driver.
-
-**NOTES:**
-
-This device driver is responsible for providing standard input and output
-using */dev/console*.
-
-BSPs should be constructed in a manner that allows ``printk()``
-to work properly without the need for the console driver to be configured.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ===
-
-Enable Clock Driver
--------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the
-application wishes to include the Clock Device Driver.
-
-**NOTES:**
-
-This device driver is responsible for providing a regular
-interrupt which invokes the ``rtems_clock_tick`` directive.
-
-If neither the Clock Driver not Benchmark Timer is enabled and
-the configuration parameter``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined,
-then a compile time error will occur.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ===
-
-Enable the Benchmark Timer Driver
----------------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the
-application wishes to include the Timer Driver. This device driver is
-used to benchmark execution times by the RTEMS Timing Test Suites.
-
-**NOTES:**
-
-If neither the Clock Driver not Benchmark Timer is enabled and
-the configuration parameter``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined,
-then a compile time error will occur.
-
-.. COMMENT: === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ===
-
-Specify Clock and Benchmark Timer Drivers Are Not Needed
---------------------------------------------------------
-.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when
-the application does *NOT* want the Clock Device Driver and is *NOT*
-using the Timer Driver. The inclusion or exclusion of the Clock Driver
-must be explicit in user applications.
-
-**NOTES:**
-
-This configuration parameter is intended to prevent the common user error
-of using the Hello World example as the baseline for an application and
-leaving out a clock tick source.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER ===
-
-Enable Real-Time Clock Driver
------------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the
-application wishes to include the Real-Time Clock Driver.
-
-**NOTES:**
-
-Most BSPs do not include support for a real-time clock. This is because
-many boards do not include the required hardware.
-
-If this is defined and the BSP does not have this device driver, then
-the user will get a link time error for an undefined symbol.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ===
-
-Enable the Watchdog Device Driver
----------------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
-is defined if the application wishes to include the Watchdog Driver.
-
-**NOTES:**
-
-Most BSPs do not include support for a watchdog device driver. This is
-because many boards do not include the required hardware.
-
-If this is defined and the BSP does not have this device driver, then
-the user will get a link time error for an undefined symbol.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ===
-
-Enable the Graphics Frame Buffer Device Driver
-----------------------------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined
-if the application wishes to include the BSP’s Frame Buffer Device Driver.
-
-**NOTES:**
-
-Most BSPs do not include support for a Frame Buffer Device Driver. This is
-because many boards do not include the required hardware.
-
-If this is defined and the BSP does not have this device driver, then
-the user will get a link time error for an undefined symbol.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER ===
-
-Enable Stub Device Driver
--------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the
-application wishes to include the Stub Device Driver.
-
-**NOTES:**
-
-This device driver simply provides entry points that return successful
-and is primarily a test fixture. It is supported by all BSPs.
-
-.. COMMENT: === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ===
-
-Specify Application Prerequisite Device Drivers
------------------------------------------------
-.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS``
-
-*DATA TYPE:*
- device driver entry structures
-
-*RANGE:*
- Undefined or set of device driver entry structures
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the
-application has device drivers it needs to include in the Device Driver
-Table. This should be defined to the set of device driver entries that
-will be placed in the table at the *FRONT* of the Device Driver Table
-and initialized before any other drivers *EXCEPT* any BSP prerequisite
-drivers.
-
-**NOTES:**
-
-In some cases, it is used by System On Chip BSPs to support peripheral
-buses beyond those normally found on the System On Chip. For example,
-this is used by one RTEMS system which has implemented a SPARC/ERC32
-based board with VMEBus. The VMEBus Controller initialization is performed
-by a device driver configured via this configuration parameter.
-
-.. COMMENT: XXX Add example
-
-.. COMMENT: === CONFIGURE_APPLICATION_EXTRA_DRIVERS ===
-
-Specify Extra Application Device Drivers
-----------------------------------------
-.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_EXTRA_DRIVERS``
-
-*DATA TYPE:*
- device driver entry structures
-
-*RANGE:*
- Undefined or set of device driver entry structures
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the
-application has device drivers it needs to include in the Device Driver
-Table. This should be defined to the set of device driver entries that
-will be placed in the table at the *END* of the Device Driver Table.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER ===
-
-Enable /dev/null Device Driver
-------------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
-.. index:: /dev/null
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-This configuration variable is specified to enable */dev/null*
-device driver.
-
-**NOTES:**
-
-This device driver is supported by all BSPs.
-
-.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER ===
-
-Enable /dev/zero Device Driver
-------------------------------
-.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
-.. index:: /dev/zero
-
-*CONSTANT:*
- ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-This configuration variable is specified to enable */dev/zero*
-device driver.
-
-**NOTES:**
-
-This device driver is supported by all BSPs.
-
-.. COMMENT: === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE ===
-
-Specifying Application Defined Device Driver Table
---------------------------------------------------
-.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default, indicating the ``<rtems/confdefs.h>``
- is providing the device driver table.
-
-**DESCRIPTION:**
-
-``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` is defined if the application
-wishes to provide their own Device Driver Table.
-
-The table must be an array of ``rtems_driver_address_table`` entries named``_IO_Driver_address_table``. The application must also provide a const
-variable ``_IO_Number_of_drivers`` of type ``size_t`` indicating the
-number of entries in the ``_IO_Driver_address_table``.
-
-**NOTES:**
-
-It is expected that there the application would only rarely need to do this.
-
-.. COMMENT: === Multiprocessing Configuration ===
-
-Multiprocessing Configuration
-=============================
-
-This section defines the multiprocessing related system configuration
-parameters supported by ``<rtems/confdefs.h>``. They are only used
-if the Multiprocessing Support (distinct from the SMP support) is enabled
-at configure time using the ``--enable-multiprocessing`` option.
-
-Additionally, this class of Configuration Constants are only applicable if``CONFIGURE_MP_APPLICATION`` is defined.
-
-.. COMMENT: === CONFIGURE_MP_APPLICATION ===
-
-Specify Application Will Use Multiprocessing
---------------------------------------------
-.. index:: CONFIGURE_MP_APPLICATION
-
-*CONSTANT:*
- ``CONFIGURE_MP_APPLICATION``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-This configuration parameter must be defined to indicate
-that the application intends to be part of a multiprocessing
-configuration. Additional configuration parameters are assumed to be
-provided.
-
-**NOTES:**
-
-This has no impact unless RTEMS was configured and built using the``--enable-multiprocessing`` option.
-
-.. COMMENT: === CONFIGURE_MP_NODE_NUMBER ===
-
-Configure Node Number in Multiprocessor Configuration
------------------------------------------------------
-.. index:: CONFIGURE_MP_NODE_NUMBER
-
-*CONSTANT:*
- ``CONFIGURE_MP_NODE_NUMBER``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is ``NODE_NUMBER``, which is assumed to be
- set by the compilation environment.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MP_NODE_NUMBER`` is the node number of
-this node in a multiprocessor system.
-
-**NOTES:**
-
-In the RTEMS Multiprocessing Test Suite, the node number is derived from
-the Makefile variable ``NODE_NUMBER``. The same code is compiled with
-the ``NODE_NUMBER`` set to different values. The test programs behave
-differently based upon their node number.
-
-.. COMMENT: === CONFIGURE_MP_MAXIMUM_NODES ===
-
-Configure Maximum Node in Multiprocessor Configuration
-------------------------------------------------------
-.. index:: CONFIGURE_MP_MAXIMUM_NODES
-
-*CONSTANT:*
- ``CONFIGURE_MP_MAXIMUM_NODES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 2.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a
-multiprocessor system.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ===
-
-Configure Maximum Global Objects in Multiprocessor Configuration
-----------------------------------------------------------------
-.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS
-
-*CONSTANT:*
- ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Positive.
-
-*DEFAULT VALUE:*
- The default value is 32.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of
-concurrently active global objects in a multiprocessor system.
-
-**NOTES:**
-
-This value corresponds to the total number of objects which can be
-created with the ``RTEMS_GLOBAL`` attribute.
-
-.. COMMENT: === CONFIGURE_MP_MAXIMUM_PROXIES ===
-
-Configure Maximum Proxies in Multiprocessor Configuration
----------------------------------------------------------
-.. index:: CONFIGURE_MP_MAXIMUM_PROXIES
-
-*CONSTANT:*
- ``CONFIGURE_MP_MAXIMUM_PROXIES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- The default value is 32.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently
-active thread/task proxies on this node in a multiprocessor system.
-
-**NOTES:**
-
-Since a proxy is used to represent a remote task/thread which is blocking on
-this node. This configuration parameter reflects the maximum number of
-remote tasks/threads which can be blocked on objects on this node.
-
-.. COMMENT: XXX - add xref to proxy discussion in MP chapter
-
-.. COMMENT: === CONFIGURE_MP_MPCI_TABLE_POINTER ===
-
-Configure MPCI in Multiprocessor Configuration
-----------------------------------------------
-.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER
-
-*CONSTANT:*
- ``CONFIGURE_MP_MPCI_TABLE_POINTER``
-
-*DATA TYPE:*
- pointer to ``rtems_mpci_table``
-
-*RANGE:*
- undefined or valid pointer
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the
-MPCI Configuration Table. The default value of this field is``&MPCI_table``.
-
-**NOTES:**
-
-RTEMS provides a Shared Memory MPCI Device Driver which can be used on
-any Multiprocessor System assuming the BSP provides the proper set of
-supporting methods.
-
-.. COMMENT: === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE ===
-
-Do Not Generate Multiprocessor Configuration Table
---------------------------------------------------
-.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE
-
-*CONSTANT:*
- ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` is defined if the
-application wishes to provide their own Multiprocessing Configuration
-Table. The generated table is named ``Multiprocessing_configuration``.
-
-**NOTES:**
-
-This is a configuration parameter which is very unlikely to be used by
-an application. If you find yourself wanting to use it in an application,
-please reconsider and discuss this on the RTEMS Users mailing list.
-
-.. COMMENT: === Ada Tasks ===
-
-Ada Tasks
-=========
-
-This section defines the system configuration parameters supported
-by ``<rtems/confdefs.h>`` related to configuring RTEMS to support
-a task using Ada tasking with GNAT/RTEMS.
-
-These configuration parameters are only available when RTEMS is built with
-the ``--enable-ada`` configure option and the application specifies``CONFIGURE_GNAT_RTEMS``.
-
-Additionally RTEMS includes an Ada language binding to the Classic
-API which has a test suite. This test suite is enabled only when``--enable-tests`` and ``--enable-expada`` are specified on the
-configure command.
-
-.. COMMENT: === CONFIGURE_GNAT_RTEMS ===
-
-Specify Application Includes Ada Code
--------------------------------------
-.. index:: CONFIGURE_GNAT_RTEMS
-
-*CONSTANT:*
- ``CONFIGURE_GNAT_RTEMS``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_GNAT_RTEMS`` is defined to inform RTEMS that the GNAT
-Ada run-time is to be used by the application.
-
-**NOTES:**
-
-This configuration parameter is critical as it makes``<rtems/confdefs.h>`` configure the resources (POSIX API Threads,
-Mutexes, Condition Variables, and Keys) used implicitly by the GNAT
-run-time.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_ADA_TASKS ===
-
-Specify the Maximum Number of Ada Tasks.
-----------------------------------------
-.. index:: CONFIGURE_MAXIMUM_ADA_TASKS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_ADA_TASKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Undefined or positive.
-
-*DEFAULT VALUE:*
- If ``CONFIGURE_GNAT_RTEMS`` is defined, then the
- default value is 20, otherwise the default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_ADA_TASKS`` is the number of Ada tasks that can
-be concurrently active in the system.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS ===
-
-Specify the Maximum Fake Ada Tasks
-----------------------------------
-.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
-
-*CONSTANT:*
- .. index:: ``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 0.
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` is the number of *fake* Ada tasks
-that can be concurrently active in the system. A *fake* Ada task is
-a non-Ada task that makes calls back into Ada code and thus implicitly
-uses the Ada run-time.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: === PCI Library ===
-
-PCI Library
-===========
-
-This section defines the system configuration parameters supported
-by ``rtems/confdefs.h`` related to configuring the PCI Library
-for RTEMS.
-
-The PCI Library startup behaviour can be configured in four different
-ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
-
-- .. index:: PCI_LIB_AUTO
-
- ``PCI_LIB_AUTO`` is used to enable the PCI auto configuration
- software. PCI will be automatically probed, PCI buses enumerated, all
- devices and bridges will be initialized using Plug & Play software
- routines. The PCI device tree will be populated based on the PCI devices
- found in the system, PCI devices will be configured by allocating address
- region resources automatically in PCI space according to the BSP or host
- bridge driver set up.
-
-- .. index:: PCI_LIB_READ
-
- ``PCI_LIB_READ`` is used to enable the PCI read configuration
- software. The current PCI configuration is read to create the RAM
- representation (the PCI device tree) of the PCI devices present. PCI devices
- are assumed to already have been initialized and PCI buses enumerated, it is
- therefore required that a BIOS or a boot loader has set up configuration space
- prior to booting into RTEMS.
-
-- .. index:: PCI_LIB_STATIC
-
- ``PCI_LIB_STATIC`` is used to enable the PCI static configuration
- software. The user provides a PCI tree with information how all PCI devices
- are to be configured at compile time by linking in a custom``struct pci_bus pci_hb`` tree. The static PCI library will not probe PCI
- for devices, instead it will assume that all devices defined by the user are
- present, it will enumerate the PCI buses and configure all PCI devices in
- static configuration accordingly. Since probe and allocation software is not
- needed the startup is faster, has smaller footprint and does not require
- dynamic memory allocation.
-
-- .. index:: PCI_LIB_PERIPHERAL
-
- ``PCI_LIB_PERIPHERAL`` is used to enable the PCI peripheral
- configuration. It is similar to ``PCI_LIB_STATIC``, but it will never write
- the configuration to the PCI devices since PCI peripherals are not allowed to
- access PCI configuration space.
-
-Note that selecting PCI_LIB_STATIC or PCI_LIB_PERIPHERAL but not defining``pci_hb`` will reuslt in link errors. Note also that in these modes
-Plug & Play is not performed.
-
-.. COMMENT: === Go Tasks ===
-
-Go Tasks
-========
-
-.. COMMENT: === CONFIGURE_ENABLE_GO ===
-
-Specify Application Includes Go Code
-------------------------------------
-.. index:: CONFIGURE_ENABLE_GO
-
-*CONSTANT:*
- ``CONFIGURE_ENABLE_GO``
-
-*DATA TYPE:*
- Boolean feature macro.
-
-*RANGE:*
- Defined or undefined.
-
-*DEFAULT VALUE:*
- This is not defined by default.
-
-**DESCRIPTION:**
-
-``CONFIGURE_ENABLE_GO`` is defined to inform RTEMS that the Go
-run-time is to be used by the application.
-
-**NOTES:**
-
-The Go language support is experimental
-
-.. COMMENT: === CONFIGURE_MAXIMUM_GOROUTINES ===
-
-Specify the maximum number of Go routines
------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_GOROUTINES
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_GOROUTINES``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 400
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_GOROUTINES`` is defined to specify the maximum number of
-Go routines.
-
-**NOTES:**
-
-The Go language support is experimental
-
-.. COMMENT: === CONFIGURE_MAXIMUM_GO_CHANNELS ===
-
-Specify the maximum number of Go Channels
------------------------------------------
-.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS
-
-*CONSTANT:*
- ``CONFIGURE_MAXIMUM_GO_CHANNELS``
-
-*DATA TYPE:*
- Unsigned integer (``uint32_t``).
-
-*RANGE:*
- Zero or positive.
-
-*DEFAULT VALUE:*
- The default value is 500
-
-**DESCRIPTION:**
-
-``CONFIGURE_MAXIMUM_GO_CHANNELS`` is defined to specify the maximum number
-of Go channels.
-
-**NOTES:**
-
-The Go language support is experimental
-
-.. COMMENT: === Configuration Data Structures ===
-
-Configuration Data Structures
-=============================
-
-It is recommended that applications be configured using``<rtems/confdefs.h>`` as it is simpler and insulates applications
-from changes in the underlying data structures. However, it is sometimes
-important to understand the data structures that are automatically filled
-in by the configuration parameters. This section describes the primary
-configuration data structures.
-
-If the user wishes to see the details of a particular data structure,
-they are are advised to look at the source code. After all, that is one
-of the advantages of RTEMS.
-
-.. COMMENT: COPYRIGHT (c) 1988-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Multiprocessing Manager
-#######################
-
-.. index:: multiprocessing
-
-Introduction
-============
-
-In multiprocessor real-time systems, new
-requirements, such as sharing data and global resources between
-processors, are introduced. This requires an efficient and
-reliable communications vehicle which allows all processors to
-communicate with each other as necessary. In addition, the
-ramifications of multiple processors affect each and every
-characteristic of a real-time system, almost always making them
-more complicated.
-
-RTEMS addresses these issues by providing simple and
-flexible real-time multiprocessing capabilities. The executive
-easily lends itself to both tightly-coupled and loosely-coupled
-configurations of the target system hardware. In addition,
-RTEMS supports systems composed of both homogeneous and
-heterogeneous mixtures of processors and target boards.
-
-A major design goal of the RTEMS executive was to
-transcend the physical boundaries of the target hardware
-configuration. This goal is achieved by presenting the
-application software with a logical view of the target system
-where the boundaries between processor nodes are transparent.
-As a result, the application developer may designate objects
-such as tasks, queues, events, signals, semaphores, and memory
-blocks as global objects. These global objects may then be
-accessed by any task regardless of the physical location of the
-object and the accessing task. RTEMS automatically determines
-that the object being accessed resides on another processor and
-performs the actions required to access the desired object.
-Simply stated, RTEMS allows the entire system, both hardware and
-software, to be viewed logically as a single system.
-
-Background
-==========
-
-.. index:: multiprocessing topologies
-
-RTEMS makes no assumptions regarding the connection
-media or topology of a multiprocessor system. The tasks which
-compose a particular application can be spread among as many
-processors as needed to satisfy the application’s timing
-requirements. The application tasks can interact using a subset
-of the RTEMS directives as if they were on the same processor.
-These directives allow application tasks to exchange data,
-communicate, and synchronize regardless of which processor they
-reside upon.
-
-The RTEMS multiprocessor execution model is multiple
-instruction streams with multiple data streams (MIMD). This
-execution model has each of the processors executing code
-independent of the other processors. Because of this
-parallelism, the application designer can more easily guarantee
-deterministic behavior.
-
-By supporting heterogeneous environments, RTEMS
-allows the systems designer to select the most efficient
-processor for each subsystem of the application. Configuring
-RTEMS for a heterogeneous environment is no more difficult than
-for a homogeneous one. In keeping with RTEMS philosophy of
-providing transparent physical node boundaries, the minimal
-heterogeneous processing required is isolated in the MPCI layer.
-
-Nodes
------
-.. index:: nodes, definition
-
-A processor in a RTEMS system is referred to as a
-node. Each node is assigned a unique non-zero node number by
-the application designer. RTEMS assumes that node numbers are
-assigned consecutively from one to the ``maximum_nodes``
-configuration parameter. The node
-number, node, and the maximum number of nodes, maximum_nodes, in
-a system are found in the Multiprocessor Configuration Table.
-The maximum_nodes field and the number of global objects,
-maximum_global_objects, is required to be the same on all nodes
-in a system.
-
-The node number is used by RTEMS to identify each
-node when performing remote operations. Thus, the
-Multiprocessor Communications Interface Layer (MPCI) must be
-able to route messages based on the node number.
-
-Global Objects
---------------
-.. index:: global objects, definition
-
-All RTEMS objects which are created with the GLOBAL
-attribute will be known on all other nodes. Global objects can
-be referenced from any node in the system, although certain
-directive specific restrictions (e.g. one cannot delete a remote
-object) may apply. A task does not have to be global to perform
-operations involving remote objects. The maximum number of
-global objects is the system is user configurable and can be
-found in the maximum_global_objects field in the Multiprocessor
-Configuration Table. The distribution of tasks to processors is
-performed during the application design phase. Dynamic task
-relocation is not supported by RTEMS.
-
-Global Object Table
--------------------
-.. index:: global objects table
-
-RTEMS maintains two tables containing object
-information on every node in a multiprocessor system: a local
-object table and a global object table. The local object table
-on each node is unique and contains information for all objects
-created on this node whether those objects are local or global.
-The global object table contains information regarding all
-global objects in the system and, consequently, is the same on
-every node.
-
-Since each node must maintain an identical copy of
-the global object table, the maximum number of entries in each
-copy of the table must be the same. The maximum number of
-entries in each copy is determined by the
-maximum_global_objects parameter in the Multiprocessor
-Configuration Table. This parameter, as well as the
-maximum_nodes parameter, is required to be the same on all
-nodes. To maintain consistency among the table copies, every
-node in the system must be informed of the creation or deletion
-of a global object.
-
-Remote Operations
------------------
-.. index:: MPCI and remote operations
-
-When an application performs an operation on a remote
-global object, RTEMS must generate a Remote Request (RQ) message
-and send it to the appropriate node. After completing the
-requested operation, the remote node will build a Remote
-Response (RR) message and send it to the originating node.
-Messages generated as a side-effect of a directive (such as
-deleting a global task) are known as Remote Processes (RP) and
-do not require the receiving node to respond.
-
-Other than taking slightly longer to execute
-directives on remote objects, the application is unaware of the
-location of the objects it acts upon. The exact amount of
-overhead required for a remote operation is dependent on the
-media connecting the nodes and, to a lesser degree, on the
-efficiency of the user-provided MPCI routines.
-
-The following shows the typical transaction sequence
-during a remote application:
-
-# The application issues a directive accessing a
- remote global object.
-
-# RTEMS determines the node on which the object
- resides.
-
-# RTEMS calls the user-provided MPCI routine
- GET_PACKET to obtain a packet in which to build a RQ message.
-
-# After building a message packet, RTEMS calls the
- user-provided MPCI routine SEND_PACKET to transmit the packet to
- the node on which the object resides (referred to as the
- destination node).
-
-# The calling task is blocked until the RR message
- arrives, and control of the processor is transferred to another
- task.
-
-# The MPCI layer on the destination node senses the
- arrival of a packet (commonly in an ISR), and calls the``rtems_multiprocessing_announce``
- directive. This directive readies the Multiprocessing Server.
-
-# The Multiprocessing Server calls the user-provided
- MPCI routine RECEIVE_PACKET, performs the requested operation,
- builds an RR message, and returns it to the originating node.
-
-# The MPCI layer on the originating node senses the
- arrival of a packet (typically via an interrupt), and calls the RTEMS``rtems_multiprocessing_announce`` directive. This directive
- readies the Multiprocessing Server.
-
-# The Multiprocessing Server calls the user-provided
- MPCI routine RECEIVE_PACKET, readies the original requesting
- task, and blocks until another packet arrives. Control is
- transferred to the original task which then completes processing
- of the directive.
-
-If an uncorrectable error occurs in the user-provided
-MPCI layer, the fatal error handler should be invoked. RTEMS
-assumes the reliable transmission and reception of messages by
-the MPCI and makes no attempt to detect or correct errors.
-
-Proxies
--------
-.. index:: proxy, definition
-
-A proxy is an RTEMS data structure which resides on a
-remote node and is used to represent a task which must block as
-part of a remote operation. This action can occur as part of the``rtems_semaphore_obtain`` and``rtems_message_queue_receive`` directives. If the
-object were local, the task’s control block would be available
-for modification to indicate it was blocking on a message queue
-or semaphore. However, the task’s control block resides only on
-the same node as the task. As a result, the remote node must
-allocate a proxy to represent the task until it can be readied.
-
-The maximum number of proxies is defined in the
-Multiprocessor Configuration Table. Each node in a
-multiprocessor system may require a different number of proxies
-to be configured. The distribution of proxy control blocks is
-application dependent and is different from the distribution of
-tasks.
-
-Multiprocessor Configuration Table
-----------------------------------
-
-The Multiprocessor Configuration Table contains
-information needed by RTEMS when used in a multiprocessor
-system. This table is discussed in detail in the section
-Multiprocessor Configuration Table of the Configuring a System
-chapter.
-
-Multiprocessor Communications Interface Layer
-=============================================
-
-The Multiprocessor Communications Interface Layer
-(MPCI) is a set of user-provided procedures which enable the
-nodes in a multiprocessor system to communicate with one
-another. These routines are invoked by RTEMS at various times
-in the preparation and processing of remote requests.
-Interrupts are enabled when an MPCI procedure is invoked. It is
-assumed that if the execution mode and/or interrupt level are
-altered by the MPCI layer, that they will be restored prior to
-returning to RTEMS... index:: MPCI, definition
-
-The MPCI layer is responsible for managing a pool of
-buffers called packets and for sending these packets between
-system nodes. Packet buffers contain the messages sent between
-the nodes. Typically, the MPCI layer will encapsulate the
-packet within an envelope which contains the information needed
-by the MPCI layer. The number of packets available is dependent
-on the MPCI layer implementation... index:: MPCI entry points
-
-The entry points to the routines in the user’s MPCI
-layer should be placed in the Multiprocessor Communications
-Interface Table. The user must provide entry points for each of
-the following table entries in a multiprocessor system:
-
-- initialization initialize the MPCI
-
-- get_packet obtain a packet buffer
-
-- return_packet return a packet buffer
-
-- send_packet send a packet to another node
-
-- receive_packet called to get an arrived packet
-
-A packet is sent by RTEMS in each of the following situations:
-
-- an RQ is generated on an originating node;
-
-- an RR is generated on a destination node;
-
-- a global object is created;
-
-- a global object is deleted;
-
-- a local task blocked on a remote object is deleted;
-
-- during system initialization to check for system consistency.
-
-If the target hardware supports it, the arrival of a
-packet at a node may generate an interrupt. Otherwise, the
-real-time clock ISR can check for the arrival of a packet. In
-any case, the``rtems_multiprocessing_announce`` directive must be called
-to announce the arrival of a packet. After exiting the ISR,
-control will be passed to the Multiprocessing Server to process
-the packet. The Multiprocessing Server will call the get_packet
-entry to obtain a packet buffer and the receive_entry entry to
-copy the message into the buffer obtained.
-
-INITIALIZATION
---------------
-
-The INITIALIZATION component of the user-provided
-MPCI layer is called as part of the ``rtems_initialize_executive``
-directive to initialize the MPCI layer and associated hardware.
-It is invoked immediately after all of the device drivers have
-been initialized. This component should be adhere to the
-following prototype:.. index:: rtems_mpci_entry
-
-.. code:: c
-
- rtems_mpci_entry user_mpci_initialization(
- rtems_configuration_table \*configuration
- );
-
-where configuration is the address of the user’s
-Configuration Table. Operations on global objects cannot be
-performed until this component is invoked. The INITIALIZATION
-component is invoked only once in the life of any system. If
-the MPCI layer cannot be successfully initialized, the fatal
-error manager should be invoked by this routine.
-
-One of the primary functions of the MPCI layer is to
-provide the executive with packet buffers. The INITIALIZATION
-routine must create and initialize a pool of packet buffers.
-There must be enough packet buffers so RTEMS can obtain one
-whenever needed.
-
-GET_PACKET
-----------
-
-The GET_PACKET component of the user-provided MPCI
-layer is called when RTEMS must obtain a packet buffer to send
-or broadcast a message. This component should be adhere to the
-following prototype:
-.. code:: c
-
- rtems_mpci_entry user_mpci_get_packet(
- rtems_packet_prefix \**packet
- );
-
-where packet is the address of a pointer to a packet.
-This routine always succeeds and, upon return, packet will
-contain the address of a packet. If for any reason, a packet
-cannot be successfully obtained, then the fatal error manager
-should be invoked.
-
-RTEMS has been optimized to avoid the need for
-obtaining a packet each time a message is sent or broadcast.
-For example, RTEMS sends response messages (RR) back to the
-originator in the same packet in which the request message (RQ)
-arrived.
-
-RETURN_PACKET
--------------
-
-The RETURN_PACKET component of the user-provided MPCI
-layer is called when RTEMS needs to release a packet to the free
-packet buffer pool. This component should be adhere to the
-following prototype:
-.. code:: c
-
- rtems_mpci_entry user_mpci_return_packet(
- rtems_packet_prefix \*packet
- );
-
-where packet is the address of a packet. If the
-packet cannot be successfully returned, the fatal error manager
-should be invoked.
-
-RECEIVE_PACKET
---------------
-
-The RECEIVE_PACKET component of the user-provided
-MPCI layer is called when RTEMS needs to obtain a packet which
-has previously arrived. This component should be adhere to the
-following prototype:
-.. code:: c
-
- rtems_mpci_entry user_mpci_receive_packet(
- rtems_packet_prefix \**packet
- );
-
-where packet is a pointer to the address of a packet
-to place the message from another node. If a message is
-available, then packet will contain the address of the message
-from another node. If no messages are available, this entry
-packet should contain NULL.
-
-SEND_PACKET
------------
-
-The SEND_PACKET component of the user-provided MPCI
-layer is called when RTEMS needs to send a packet containing a
-message to another node. This component should be adhere to the
-following prototype:
-.. code:: c
-
- rtems_mpci_entry user_mpci_send_packet(
- uint32_t node,
- rtems_packet_prefix \**packet
- );
-
-where node is the node number of the destination and packet is the
-address of a packet which containing a message. If the packet cannot
-be successfully sent, the fatal error manager should be invoked.
-
-If node is set to zero, the packet is to be
-broadcasted to all other nodes in the system. Although some
-MPCI layers will be built upon hardware which support a
-broadcast mechanism, others may be required to generate a copy
-of the packet for each node in the system.
-
-.. COMMENT: XXX packet_prefix structure needs to be defined in this document
-
-Many MPCI layers use the ``packet_length`` field of the``rtems_packet_prefix`` portion
-of the packet to avoid sending unnecessary data. This is especially
-useful if the media connecting the nodes is relatively slow.
-
-The ``to_convert`` field of the ``rtems_packet_prefix`` portion of the
-packet indicates how much of the packet in 32-bit units may require conversion
-in a heterogeneous system.
-
-Supporting Heterogeneous Environments
--------------------------------------
-.. index:: heterogeneous multiprocessing
-
-Developing an MPCI layer for a heterogeneous system
-requires a thorough understanding of the differences between the
-processors which comprise the system. One difficult problem is
-the varying data representation schemes used by different
-processor types. The most pervasive data representation problem
-is the order of the bytes which compose a data entity.
-Processors which place the least significant byte at the
-smallest address are classified as little endian processors.
-Little endian byte-ordering is shown below:
-
-.. code:: c
-
- +---------------+----------------+---------------+----------------+
- | | | | |
- | Byte 3 | Byte 2 | Byte 1 | Byte 0 |
- | | | | |
- +---------------+----------------+---------------+----------------+
-
-Conversely, processors which place the most
-significant byte at the smallest address are classified as big
-endian processors. Big endian byte-ordering is shown below:
-.. code:: c
-
- +---------------+----------------+---------------+----------------+
- | | | | |
- | Byte 0 | Byte 1 | Byte 2 | Byte 3 |
- | | | | |
- +---------------+----------------+---------------+----------------+
-
-Unfortunately, sharing a data structure between big
-endian and little endian processors requires translation into a
-common endian format. An application designer typically chooses
-the common endian format to minimize conversion overhead.
-
-Another issue in the design of shared data structures
-is the alignment of data structure elements. Alignment is both
-processor and compiler implementation dependent. For example,
-some processors allow data elements to begin on any address
-boundary, while others impose restrictions. Common restrictions
-are that data elements must begin on either an even address or
-on a long word boundary. Violation of these restrictions may
-cause an exception or impose a performance penalty.
-
-Other issues which commonly impact the design of
-shared data structures include the representation of floating
-point numbers, bit fields, decimal data, and character strings.
-In addition, the representation method for negative integers
-could be one’s or two’s complement. These factors combine to
-increase the complexity of designing and manipulating data
-structures shared between processors.
-
-RTEMS addressed these issues in the design of the
-packets used to communicate between nodes. The RTEMS packet
-format is designed to allow the MPCI layer to perform all
-necessary conversion without burdening the developer with the
-details of the RTEMS packet format. As a result, the MPCI layer
-must be aware of the following:
-
-- All packets must begin on a four byte boundary.
-
-- Packets are composed of both RTEMS and application data. All RTEMS data
- is treated as 32-bit unsigned quantities and is in the first ``to_convert``
- 32-bit quantities of the packet. The ``to_convert`` field is part of the``rtems_packet_prefix`` portion of the packet.
-
-- The RTEMS data component of the packet must be in native
- endian format. Endian conversion may be performed by either the
- sending or receiving MPCI layer.
-
-- RTEMS makes no assumptions regarding the application
- data component of the packet.
-
-Operations
-==========
-
-Announcing a Packet
--------------------
-
-The ``rtems_multiprocessing_announce`` directive is called by
-the MPCI layer to inform RTEMS that a packet has arrived from
-another node. This directive can be called from an interrupt
-service routine or from within a polling routine.
-
-Directives
-==========
-
-This section details the additional directives
-required to support RTEMS in a multiprocessor configuration. A
-subsection is dedicated to each of this manager’s directives and
-describes the calling sequence, related constants, usage, and
-status codes.
-
-MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
------------------------------------------------------------
-.. index:: announce arrival of package
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_multiprocessing_announce
-
-.. code:: c
-
- void rtems_multiprocessing_announce( void );
-
-**DIRECTIVE STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive informs RTEMS that a multiprocessing
-communications packet has arrived from another node. This
-directive is called by the user-provided MPCI, and is only used
-in multiprocessor configurations.
-
-**NOTES:**
-
-This directive is typically called from an ISR.
-
-This directive will almost certainly cause the
-calling task to be preempted.
-
-This directive does not generate activity on remote nodes.
-
-.. COMMENT: COPYRIGHT (c) 2014.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Symmetric Multiprocessing Services
-##################################
-
-Introduction
-============
-
-The Symmetric Multiprocessing (SMP) support of the RTEMS 4.10.99.0 is
-available on
-
-- ARM,
-
-- PowerPC, and
-
-- SPARC.
-
-It must be explicitly enabled via the ``--enable-smp`` configure command
-line option. To enable SMP in the application configuration see `Enable SMP Support for Applications`_. The default
-scheduler for SMP applications supports up to 32 processors and is a global
-fixed priority scheduler, see also `Configuring Clustered Schedulers`_. For example applications see:file:`testsuites/smptests`.
-
-*WARNING: The SMP support in RTEMS is work in progress. Before you
-start using this RTEMS version for SMP ask on the RTEMS mailing list.*
-
-This chapter describes the services related to Symmetric Multiprocessing
-provided by RTEMS.
-
-The application level services currently provided are:
-
-- ``rtems_get_processor_count`` - Get processor count
-
-- ``rtems_get_current_processor`` - Get current processor index
-
-- ``rtems_scheduler_ident`` - Get ID of a scheduler
-
-- ``rtems_scheduler_get_processor_set`` - Get processor set of a scheduler
-
-- ``rtems_task_get_scheduler`` - Get scheduler of a task
-
-- ``rtems_task_set_scheduler`` - Set scheduler of a task
-
-- ``rtems_task_get_affinity`` - Get task processor affinity
-
-- ``rtems_task_set_affinity`` - Set task processor affinity
-
-Background
-==========
-
-Uniprocessor versus SMP Parallelism
------------------------------------
-
-Uniprocessor systems have long been used in embedded systems. In this hardware
-model, there are some system execution characteristics which have long been
-taken for granted:
-
-- one task executes at a time
-
-- hardware events result in interrupts
-
-There is no true parallelism. Even when interrupts appear to occur
-at the same time, they are processed in largely a serial fashion.
-This is true even when the interupt service routines are allowed to
-nest. From a tasking viewpoint, it is the responsibility of the real-time
-operatimg system to simulate parallelism by switching between tasks.
-These task switches occur in response to hardware interrupt events and explicit
-application events such as blocking for a resource or delaying.
-
-With symmetric multiprocessing, the presence of multiple processors
-allows for true concurrency and provides for cost-effective performance
-improvements. Uniprocessors tend to increase performance by increasing
-clock speed and complexity. This tends to lead to hot, power hungry
-microprocessors which are poorly suited for many embedded applications.
-
-The true concurrency is in sharp contrast to the single task and
-interrupt model of uniprocessor systems. This results in a fundamental
-change to uniprocessor system characteristics listed above. Developers
-are faced with a different set of characteristics which, in turn, break
-some existing assumptions and result in new challenges. In an SMP system
-with N processors, these are the new execution characteristics.
-
-- N tasks execute in parallel
-
-- hardware events result in interrupts
-
-There is true parallelism with a task executing on each processor and
-the possibility of interrupts occurring on each processor. Thus in contrast
-to their being one task and one interrupt to consider on a uniprocessor,
-there are N tasks and potentially N simultaneous interrupts to consider
-on an SMP system.
-
-This increase in hardware complexity and presence of true parallelism
-results in the application developer needing to be even more cautious
-about mutual exclusion and shared data access than in a uniprocessor
-embedded system. Race conditions that never or rarely happened when an
-application executed on a uniprocessor system, become much more likely
-due to multiple threads executing in parallel. On a uniprocessor system,
-these race conditions would only happen when a task switch occurred at
-just the wrong moment. Now there are N-1 tasks executing in parallel
-all the time and this results in many more opportunities for small
-windows in critical sections to be hit.
-
-Task Affinity
--------------
-.. index:: task affinity
-.. index:: thread affinity
-
-RTEMS provides services to manipulate the affinity of a task. Affinity
-is used to specify the subset of processors in an SMP system on which
-a particular task can execute.
-
-By default, tasks have an affinity which allows them to execute on any
-available processor.
-
-Task affinity is a possible feature to be supported by SMP-aware
-schedulers. However, only a subset of the available schedulers support
-affinity. Although the behavior is scheduler specific, if the scheduler
-does not support affinity, it is likely to ignore all attempts to set
-affinity.
-
-The scheduler with support for arbitary processor affinities uses a proof of
-concept implementation. See https://devel.rtems.org/ticket/2510.
-
-Task Migration
---------------
-.. index:: task migration
-.. index:: thread migration
-
-With more than one processor in the system tasks can migrate from one processor
-to another. There are three reasons why tasks migrate in RTEMS.
-
-- The scheduler changes explicitly via ``rtems_task_set_scheduler()`` or
- similar directives.
-
-- The task resumes execution after a blocking operation. On a priority
- based scheduler it will evict the lowest priority task currently assigned to a
- processor in the processor set managed by the scheduler instance.
-
-- The task moves temporarily to another scheduler instance due to locking
- protocols like *Migratory Priority Inheritance* or the*Multiprocessor Resource Sharing Protocol*.
-
-Task migration should be avoided so that the working set of a task can stay on
-the most local cache level.
-
-The current implementation of task migration in RTEMS has some implications
-with respect to the interrupt latency. It is crucial to preserve the system
-invariant that a task can execute on at most one processor in the system at a
-time. This is accomplished with a boolean indicator in the task context. The
-processor architecture specific low-level task context switch code will mark
-that a task context is no longer executing and waits that the heir context
-stopped execution before it restores the heir context and resumes execution of
-the heir task. So there is one point in time in which a processor is without a
-task. This is essential to avoid cyclic dependencies in case multiple tasks
-migrate at once. Otherwise some supervising entity is necessary to prevent
-life-locks. Such a global supervisor would lead to scalability problems so
-this approach is not used. Currently the thread dispatch is performed with
-interrupts disabled. So in case the heir task is currently executing on
-another processor then this prolongs the time of disabled interrupts since one
-processor has to wait for another processor to make progress.
-
-It is difficult to avoid this issue with the interrupt latency since interrupts
-normally store the context of the interrupted task on its stack. In case a
-task is marked as not executing we must not use its task stack to store such an
-interrupt context. We cannot use the heir stack before it stopped execution on
-another processor. So if we enable interrupts during this transition we have
-to provide an alternative task independent stack for this time frame. This
-issue needs further investigation.
-
-Clustered Scheduling
---------------------
-
-We have clustered scheduling in case the set of processors of a system is
-partitioned into non-empty pairwise-disjoint subsets. These subsets are called
-clusters. Clusters with a cardinality of one are partitions. Each cluster is
-owned by exactly one scheduler instance.
-
-Clustered scheduling helps to control the worst-case latencies in
-multi-processor systems, see *Brandenburg, Björn B.: Scheduling and
-Locking in Multiprocessor Real-Time Operating Systems. PhD thesis, 2011.http://www.cs.unc.edu/~bbb/diss/brandenburg-diss.pdf*. The goal is to
-reduce the amount of shared state in the system and thus prevention of lock
-contention. Modern multi-processor systems tend to have several layers of data
-and instruction caches. With clustered scheduling it is possible to honour the
-cache topology of a system and thus avoid expensive cache synchronization
-traffic. It is easy to implement. The problem is to provide synchronization
-primitives for inter-cluster synchronization (more than one cluster is involved
-in the synchronization process). In RTEMS there are currently four means
-available
-
-- events,
-
-- message queues,
-
-- semaphores using the `Priority Inheritance`_
- protocol (priority boosting), and
-
-- semaphores using the `Multiprocessor Resource Sharing Protocol`_ (MrsP).
-
-The clustered scheduling approach enables separation of functions with
-real-time requirements and functions that profit from fairness and high
-throughput provided the scheduler instances are fully decoupled and adequate
-inter-cluster synchronization primitives are used. This is work in progress.
-
-For the configuration of clustered schedulers see `Configuring Clustered Schedulers`_.
-
-To set the scheduler of a task see `SCHEDULER_IDENT - Get ID of a scheduler`_
-and `TASK_SET_SCHEDULER - Set scheduler of a task`_.
-
-Task Priority Queues
---------------------
-
-Due to the support for clustered scheduling the task priority queues need
-special attention. It makes no sense to compare the priority values of two
-different scheduler instances. Thus, it is not possible to simply use one
-plain priority queue for tasks of different scheduler instances.
-
-One solution to this problem is to use two levels of queues. The top level
-queue provides FIFO ordering and contains priority queues. Each priority queue
-is associated with a scheduler instance and contains only tasks of this
-scheduler instance. Tasks are enqueued in the priority queue corresponding to
-their scheduler instance. In case this priority queue was empty, then it is
-appended to the FIFO. To dequeue a task the highest priority task of the first
-priority queue in the FIFO is selected. Then the first priority queue is
-removed from the FIFO. In case the previously first priority queue is not
-empty, then it is appended to the FIFO. So there is FIFO fairness with respect
-to the highest priority task of each scheduler instances. See also *Brandenburg, Björn B.: A fully preemptive multiprocessor semaphore protocol for
-latency-sensitive real-time applications. In Proceedings of the 25th Euromicro
-Conference on Real-Time Systems (ECRTS 2013), pages 292–302, 2013.http://www.mpi-sws.org/~bbb/papers/pdf/ecrts13b.pdf*.
-
-Such a two level queue may need a considerable amount of memory if fast enqueue
-and dequeue operations are desired (depends on the scheduler instance count).
-To mitigate this problem an approch of the FreeBSD kernel was implemented in
-RTEMS. We have the invariant that a task can be enqueued on at most one task
-queue. Thus, we need only as many queues as we have tasks. Each task is
-equipped with spare task queue which it can give to an object on demand. The
-task queue uses a dedicated memory space independent of the other memory used
-for the task itself. In case a task needs to block, then there are two options
-
-- the object already has task queue, then the task enqueues itself to this
- already present queue and the spare task queue of the task is added to a list
- of free queues for this object, or
-
-- otherwise, then the queue of the task is given to the object and the task
- enqueues itself to this queue.
-
-In case the task is dequeued, then there are two options
-
-- the task is the last task on the queue, then it removes this queue from
- the object and reclaims it for its own purpose, or
-
-- otherwise, then the task removes one queue from the free list of the
- object and reclaims it for its own purpose.
-
-Since there are usually more objects than tasks, this actually reduces the
-memory demands. In addition the objects contain only a pointer to the task
-queue structure. This helps to hide implementation details and makes it
-possible to use self-contained synchronization objects in Newlib and GCC (C++
-and OpenMP run-time support).
-
-Scheduler Helping Protocol
---------------------------
-
-The scheduler provides a helping protocol to support locking protocols like*Migratory Priority Inheritance* or the *Multiprocessor Resource
-Sharing Protocol*. Each ready task can use at least one scheduler node at a
-time to gain access to a processor. Each scheduler node has an owner, a user
-and an optional idle task. The owner of a scheduler node is determined a task
-creation and never changes during the life time of a scheduler node. The user
-of a scheduler node may change due to the scheduler helping protocol. A
-scheduler node is in one of the four scheduler help states:
-
-:dfn:`help yourself`
- This scheduler node is solely used by the owner task. This task owns no
- resources using a helping protocol and thus does not take part in the scheduler
- helping protocol. No help will be provided for other tasks.
-
-:dfn:`help active owner`
- This scheduler node is owned by a task actively owning a resource and can be
- used to help out tasks.
- In case this scheduler node changes its state from ready to scheduled and the
- task executes using another node, then an idle task will be provided as a user
- of this node to temporarily execute on behalf of the owner task. Thus lower
- priority tasks are denied access to the processors of this scheduler instance.
- In case a task actively owning a resource performs a blocking operation, then
- an idle task will be used also in case this node is in the scheduled state.
-
-:dfn:`help active rival`
- This scheduler node is owned by a task actively obtaining a resource currently
- owned by another task and can be used to help out tasks.
- The task owning this node is ready and will give away its processor in case the
- task owning the resource asks for help.
-
-:dfn:`help passive`
- This scheduler node is owned by a task obtaining a resource currently owned by
- another task and can be used to help out tasks.
- The task owning this node is blocked.
-
-The following scheduler operations return a task in need for help
-
-- unblock,
-
-- change priority,
-
-- yield, and
-
-- ask for help.
-
-A task in need for help is a task that encounters a scheduler state change from
-scheduled to ready (this is a pre-emption by a higher priority task) or a task
-that cannot be scheduled in an unblock operation. Such a task can ask tasks
-which depend on resources owned by this task for help.
-
-In case it is not possible to schedule a task in need for help, then the
-scheduler nodes available for the task will be placed into the set of ready
-scheduler nodes of the corresponding scheduler instances. Once a state change
-from ready to scheduled happens for one of scheduler nodes it will be used to
-schedule the task in need for help.
-
-The ask for help scheduler operation is used to help tasks in need for help
-returned by the operations mentioned above. This operation is also used in
-case the root of a resource sub-tree owned by a task changes.
-
-The run-time of the ask for help procedures depend on the size of the resource
-tree of the task needing help and other resource trees in case tasks in need
-for help are produced during this operation. Thus the worst-case latency in
-the system depends on the maximum resource tree size of the application.
-
-Critical Section Techniques and SMP
------------------------------------
-
-As discussed earlier, SMP systems have opportunities for true parallelism
-which was not possible on uniprocessor systems. Consequently, multiple
-techniques that provided adequate critical sections on uniprocessor
-systems are unsafe on SMP systems. In this section, some of these
-unsafe techniques will be discussed.
-
-In general, applications must use proper operating system provided mutual
-exclusion mechanisms to ensure correct behavior. This primarily means
-the use of binary semaphores or mutexes to implement critical sections.
-
-Disable Interrupts and Interrupt Locks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A low overhead means to ensure mutual exclusion in uni-processor configurations
-is to disable interrupts around a critical section. This is commonly used in
-device driver code and throughout the operating system core. On SMP
-configurations, however, disabling the interrupts on one processor has no
-effect on other processors. So, this is insufficient to ensure system wide
-mutual exclusion. The macros
-
-- ``rtems_interrupt_disable()``,
-
-- ``rtems_interrupt_enable()``, and
-
-- ``rtems_interrupt_flush()``
-
-are disabled on SMP configurations and its use will lead to compiler warnings
-and linker errors. In the unlikely case that interrupts must be disabled on
-the current processor, then the
-
-- ``rtems_interrupt_local_disable()``, and
-
-- ``rtems_interrupt_local_enable()``
-
-macros are now available in all configurations.
-
-Since disabling of interrupts is not enough to ensure system wide mutual
-exclusion on SMP, a new low-level synchronization primitive was added - the
-interrupt locks. They are a simple API layer on top of the SMP locks used for
-low-level synchronization in the operating system core. Currently they are
-implemented as a ticket lock. On uni-processor configurations they degenerate
-to simple interrupt disable/enable sequences. It is disallowed to acquire a
-single interrupt lock in a nested way. This will result in an infinite loop
-with interrupts disabled. While converting legacy code to interrupt locks care
-must be taken to avoid this situation.
-.. code:: c
-
- void legacy_code_with_interrupt_disable_enable( void )
- {
- rtems_interrupt_level level;
- rtems_interrupt_disable( level );
- /* Some critical stuff \*/
- rtems_interrupt_enable( level );
- }
- RTEMS_INTERRUPT_LOCK_DEFINE( static, lock, "Name" )
- void smp_ready_code_with_interrupt_lock( void )
- {
- rtems_interrupt_lock_context lock_context;
- rtems_interrupt_lock_acquire( &lock, &lock_context );
- /* Some critical stuff \*/
- rtems_interrupt_lock_release( &lock, &lock_context );
- }
-
-The ``rtems_interrupt_lock`` structure is empty on uni-processor
-configurations. Empty structures have a different size in C
-(implementation-defined, zero in case of GCC) and C++ (implementation-defined
-non-zero value, one in case of GCC). Thus the``RTEMS_INTERRUPT_LOCK_DECLARE()``, ``RTEMS_INTERRUPT_LOCK_DEFINE()``,``RTEMS_INTERRUPT_LOCK_MEMBER()``, and``RTEMS_INTERRUPT_LOCK_REFERENCE()`` macros are provided to ensure ABI
-compatibility.
-
-Highest Priority Task Assumption
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On a uniprocessor system, it is safe to assume that when the highest
-priority task in an application executes, it will execute without being
-preempted until it voluntarily blocks. Interrupts may occur while it is
-executing, but there will be no context switch to another task unless
-the highest priority task voluntarily initiates it.
-
-Given the assumption that no other tasks will have their execution
-interleaved with the highest priority task, it is possible for this
-task to be constructed such that it does not need to acquire a binary
-semaphore or mutex for protected access to shared data.
-
-In an SMP system, it cannot be assumed there will never be a single task
-executing. It should be assumed that every processor is executing another
-application task. Further, those tasks will be ones which would not have
-been executed in a uniprocessor configuration and should be assumed to
-have data synchronization conflicts with what was formerly the highest
-priority task which executed without conflict.
-
-Disable Preemption
-~~~~~~~~~~~~~~~~~~
-
-On a uniprocessor system, disabling preemption in a task is very similar
-to making the highest priority task assumption. While preemption is
-disabled, no task context switches will occur unless the task initiates
-them voluntarily. And, just as with the highest priority task assumption,
-there are N-1 processors also running tasks. Thus the assumption that no
-other tasks will run while the task has preemption disabled is violated.
-
-Task Unique Data and SMP
-------------------------
-
-Per task variables are a service commonly provided by real-time operating
-systems for application use. They work by allowing the application
-to specify a location in memory (typically a ``void *``) which is
-logically added to the context of a task. On each task switch, the
-location in memory is stored and each task can have a unique value in
-the same memory location. This memory location is directly accessed as a
-variable in a program.
-
-This works well in a uniprocessor environment because there is one task
-executing and one memory location containing a task-specific value. But
-it is fundamentally broken on an SMP system because there are always N
-tasks executing. With only one location in memory, N-1 tasks will not
-have the correct value.
-
-This paradigm for providing task unique data values is fundamentally
-broken on SMP systems.
-
-Classic API Per Task Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Classic API provides three directives to support per task variables. These are:
-
-- ``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
-
-As task variables are unsafe for use on SMP systems, the use of these services
-must be eliminated in all software that is to be used in an SMP environment.
-The task variables API is disabled on SMP. Its use will lead to compile-time
-and link-time errors. It is recommended that the application developer consider
-the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys are available
-in all RTEMS configurations. For the availablity of TLS on a particular
-architecture please consult the *RTEMS CPU Architecture Supplement*.
-
-The only remaining user of task variables in the RTEMS code base is the Ada
-support. So basically Ada is not available on RTEMS SMP.
-
-OpenMP
-------
-
-OpenMP support for RTEMS is available via the GCC provided libgomp. There is
-libgomp support for RTEMS in the POSIX configuration of libgomp since GCC 4.9
-(requires a Newlib snapshot after 2015-03-12). In GCC 6.1 or later (requires a
-Newlib snapshot after 2015-07-30 for <sys/lock.h> provided self-contained
-synchronization objects) there is a specialized libgomp configuration for RTEMS
-which offers a significantly better performance compared to the POSIX
-configuration of libgomp. In addition application configurable thread pools
-for each scheduler instance are available in GCC 6.1 or later.
-
-The run-time configuration of libgomp is done via environment variables
-documented in the `libgomp
-manual <https://gcc.gnu.org/onlinedocs/libgomp/>`_. The environment variables are evaluated in a constructor function
-which executes in the context of the first initialization task before the
-actual initialization task function is called (just like a global C++
-constructor). To set application specific values, a higher priority
-constructor function must be used to set up the environment variables.
-.. code:: c
-
- #include <stdlib.h>
- void __attribute__((constructor(1000))) config_libgomp( void )
- {
- setenv( "OMP_DISPLAY_ENV", "VERBOSE", 1 );
- setenv( "GOMP_SPINCOUNT", "30000", 1 );
- setenv( "GOMP_RTEMS_THREAD_POOLS", "1$2@SCHD", 1 );
- }
-
-The environment variable ``GOMP_RTEMS_THREAD_POOLS`` is RTEMS-specific. It
-determines the thread pools for each scheduler instance. The format for``GOMP_RTEMS_THREAD_POOLS`` is a list of optional``<thread-pool-count>[$<priority>]@<scheduler-name>`` configurations
-separated by ``:`` where:
-
-- ``<thread-pool-count>`` is the thread pool count for this scheduler
- instance.
-
-- ``$<priority>`` is an optional priority for the worker threads of a
- thread pool according to ``pthread_setschedparam``. In case a priority
- value is omitted, then a worker thread will inherit the priority of the OpenMP
- master thread that created it. The priority of the worker thread is not
- changed by libgomp after creation, even if a new OpenMP master thread using the
- worker has a different priority.
-
-- ``@<scheduler-name>`` is the scheduler instance name according to the
- RTEMS application configuration.
-
-In case no thread pool configuration is specified for a scheduler instance,
-then each OpenMP master thread of this scheduler instance will use its own
-dynamically allocated thread pool. To limit the worker thread count of the
-thread pools, each OpenMP master thread must call ``omp_set_num_threads``.
-
-Lets suppose we have three scheduler instances ``IO``, ``WRK0``, and``WRK1`` with ``GOMP_RTEMS_THREAD_POOLS`` set to``"1@WRK0:3$4@WRK1"``. Then there are no thread pool restrictions for
-scheduler instance ``IO``. In the scheduler instance ``WRK0`` there is
-one thread pool available. Since no priority is specified for this scheduler
-instance, the worker thread inherits the priority of the OpenMP master thread
-that created it. In the scheduler instance ``WRK1`` there are three thread
-pools available and their worker threads run at priority four.
-
-Thread Dispatch Details
------------------------
-
-This section gives background information to developers interested in the
-interrupt latencies introduced by thread dispatching. A thread dispatch
-consists of all work which must be done to stop the currently executing thread
-on a processor and hand over this processor to an heir thread.
-
-On SMP systems, scheduling decisions on one processor must be propagated to
-other processors through inter-processor interrupts. So, a thread dispatch
-which must be carried out on another processor happens not instantaneous. Thus
-several thread dispatch requests might be in the air and it is possible that
-some of them may be out of date before the corresponding processor has time to
-deal with them. The thread dispatch mechanism uses three per-processor
-variables,
-
-- the executing thread,
-
-- the heir thread, and
-
-- an boolean flag indicating if a thread dispatch is necessary or not.
-
-Updates of the heir thread and the thread dispatch necessary indicator are
-synchronized via explicit memory barriers without the use of locks. A thread
-can be an heir thread on at most one processor in the system. The thread context
-is protected by a TTAS lock embedded in the context to ensure that it is used
-on at most one processor at a time. The thread post-switch actions use a
-per-processor lock. This implementation turned out to be quite efficient and
-no lock contention was observed in the test suite.
-
-The current implementation of thread dispatching has some implications with
-respect to the interrupt latency. It is crucial to preserve the system
-invariant that a thread can execute on at most one processor in the system at a
-time. This is accomplished with a boolean indicator in the thread context.
-The processor architecture specific context switch code will mark that a thread
-context is no longer executing and waits that the heir context stopped
-execution before it restores the heir context and resumes execution of the heir
-thread (the boolean indicator is basically a TTAS lock). So, there is one
-point in time in which a processor is without a thread. This is essential to
-avoid cyclic dependencies in case multiple threads migrate at once. Otherwise
-some supervising entity is necessary to prevent deadlocks. Such a global
-supervisor would lead to scalability problems so this approach is not used.
-Currently the context switch is performed with interrupts disabled. Thus in
-case the heir thread is currently executing on another processor, the time of
-disabled interrupts is prolonged since one processor has to wait for another
-processor to make progress.
-
-It is difficult to avoid this issue with the interrupt latency since interrupts
-normally store the context of the interrupted thread on its stack. In case a
-thread is marked as not executing, we must not use its thread stack to store
-such an interrupt context. We cannot use the heir stack before it stopped
-execution on another processor. If we enable interrupts during this
-transition, then we have to provide an alternative thread independent stack for
-interrupts in this time frame. This issue needs further investigation.
-
-The problematic situation occurs in case we have a thread which executes with
-thread dispatching disabled and should execute on another processor (e.g. it is
-an heir thread on another processor). In this case the interrupts on this
-other processor are disabled until the thread enables thread dispatching and
-starts the thread dispatch sequence. The scheduler (an exception is the
-scheduler with thread processor affinity support) tries to avoid such a
-situation and checks if a new scheduled thread already executes on a processor.
-In case the assigned processor differs from the processor on which the thread
-already executes and this processor is a member of the processor set managed by
-this scheduler instance, it will reassign the processors to keep the already
-executing thread in place. Therefore normal scheduler requests will not lead
-to such a situation. Explicit thread migration requests, however, can lead to
-this situation. Explicit thread migrations may occur due to the scheduler
-helping protocol or explicit scheduler instance changes. The situation can
-also be provoked by interrupts which suspend and resume threads multiple times
-and produce stale asynchronous thread dispatch requests in the system.
-
-Operations
-==========
-
-Setting Affinity to a Single Processor
---------------------------------------
-
-On some embedded applications targeting SMP systems, it may be beneficial to
-lock individual tasks to specific processors. In this way, one can designate a
-processor for I/O tasks, another for computation, etc.. The following
-illustrates the code sequence necessary to assign a task an affinity for
-processor with index ``processor_index``.
-.. code:: c
-
- #include <rtems.h>
- #include <assert.h>
- void pin_to_processor(rtems_id task_id, int processor_index)
- {
- rtems_status_code sc;
- cpu_set_t cpuset;
- CPU_ZERO(&cpuset);
- CPU_SET(processor_index, &cpuset);
- sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset);
- assert(sc == RTEMS_SUCCESSFUL);
- }
-
-It is important to note that the ``cpuset`` is not validated until the``rtems_task_set_affinity`` call is made. At that point,
-it is validated against the current system configuration.
-
-Directives
-==========
-
-This section details the symmetric multiprocessing services. A subsection
-is dedicated to each of these services and describes the calling sequence,
-related constants, usage, and status codes.
-
-.. COMMENT: rtems_get_processor_count
-
-GET_PROCESSOR_COUNT - Get processor count
------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- uint32_t rtems_get_processor_count(void);
-
-**DIRECTIVE STATUS CODES:**
-
-The count of processors in the system.
-
-**DESCRIPTION:**
-
-On uni-processor configurations a value of one will be returned.
-
-On SMP configurations this returns the value of a global variable set during
-system initialization to indicate the count of utilized processors. The
-processor count depends on the physically or virtually available processors and
-application configuration. The value will always be less than or equal to the
-maximum count of application configured processors.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: rtems_get_current_processor
-
-GET_CURRENT_PROCESSOR - Get current processor index
----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- uint32_t rtems_get_current_processor(void);
-
-**DIRECTIVE STATUS CODES:**
-
-The index of the current processor.
-
-**DESCRIPTION:**
-
-On uni-processor configurations a value of zero will be returned.
-
-On SMP configurations an architecture specific method is used to obtain the
-index of the current processor in the system. The set of processor indices is
-the range of integers starting with zero up to the processor count minus one.
-
-Outside of sections with disabled thread dispatching the current processor
-index may change after every instruction since the thread may migrate from one
-processor to another. Sections with disabled interrupts are sections with
-thread dispatching disabled.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: rtems_scheduler_ident
-
-
-SCHEDULER_IDENT - Get ID of a scheduler
----------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_scheduler_ident(
- rtems_name name,
- rtems_id \*id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
-``RTEMS_INVALID_NAME`` - invalid scheduler name
-``RTEMS_UNSATISFIED`` - - a scheduler with this name exists, but
-the processor set of this scheduler is empty
-
-**DESCRIPTION:**
-
-Identifies a scheduler by its name. The scheduler name is determined by the
-scheduler configuration. See `Configuring a System`_.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: rtems_scheduler_get_processor_set
-
-SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
---------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_scheduler_get_processor_set(
- rtems_id scheduler_id,
- size_t cpusetsize,
- cpu_set_t \*cpuset
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ADDRESS`` - ``cpuset`` is NULL
-``RTEMS_INVALID_ID`` - invalid scheduler id
-``RTEMS_INVALID_NUMBER`` - the affinity set buffer is too small for
-set of processors owned by the scheduler
-
-**DESCRIPTION:**
-
-Returns the processor set owned by the scheduler in ``cpuset``. A set bit
-in the processor set means that this processor is owned by the scheduler and a
-cleared bit means the opposite.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: rtems_task_get_scheduler
-
-TASK_GET_SCHEDULER - Get scheduler of a task
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_task_get_scheduler(
- rtems_id task_id,
- rtems_id \*scheduler_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ADDRESS`` - ``scheduler_id`` is NULL
-``RTEMS_INVALID_ID`` - invalid task id
-
-**DESCRIPTION:**
-
-Returns the scheduler identifier of a task identified by ``task_id`` in``scheduler_id``.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: rtems_task_set_scheduler
-
-
-TASK_SET_SCHEDULER - Set scheduler of a task
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_task_set_scheduler(
- rtems_id task_id,
- rtems_id scheduler_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ID`` - invalid task or scheduler id
-``RTEMS_INCORRECT_STATE`` - the task is in the wrong state to
-perform a scheduler change
-
-**DESCRIPTION:**
-
-Sets the scheduler of a task identified by ``task_id`` to the scheduler
-identified by ``scheduler_id``. The scheduler of a task is initialized to
-the scheduler of the task that created it.
-
-**NOTES:**
-
-None.
-
-**EXAMPLE:**
-
-.. code:: c
-
- #include <rtems.h>
- #include <assert.h>
- void task(rtems_task_argument arg);
- void example(void)
- {
- rtems_status_code sc;
- rtems_id task_id;
- rtems_id scheduler_id;
- rtems_name scheduler_name;
- scheduler_name = rtems_build_name('W', 'O', 'R', 'K');
- sc = rtems_scheduler_ident(scheduler_name, &scheduler_id);
- assert(sc == RTEMS_SUCCESSFUL);
- sc = rtems_task_create(
- rtems_build_name('T', 'A', 'S', 'K'),
- 1,
- RTEMS_MINIMUM_STACK_SIZE,
- RTEMS_DEFAULT_MODES,
- RTEMS_DEFAULT_ATTRIBUTES,
- &task_id
- );
- assert(sc == RTEMS_SUCCESSFUL);
- sc = rtems_task_set_scheduler(task_id, scheduler_id);
- assert(sc == RTEMS_SUCCESSFUL);
- sc = rtems_task_start(task_id, task, 0);
- assert(sc == RTEMS_SUCCESSFUL);
- }
-
-.. COMMENT: rtems_task_get_affinity
-
-TASK_GET_AFFINITY - Get task processor affinity
------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_task_get_affinity(
- rtems_id id,
- size_t cpusetsize,
- cpu_set_t \*cpuset
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ADDRESS`` - ``cpuset`` is NULL
-``RTEMS_INVALID_ID`` - invalid task id
-``RTEMS_INVALID_NUMBER`` - the affinity set buffer is too small for
-the current processor affinity set of the task
-
-**DESCRIPTION:**
-
-Returns the current processor affinity set of the task in ``cpuset``. A set
-bit in the affinity set means that the task can execute on this processor and a
-cleared bit means the opposite.
-
-**NOTES:**
-
-None.
-
-.. COMMENT: rtems_task_set_affinity
-
-TASK_SET_AFFINITY - Set task processor affinity
------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- rtems_status_code rtems_task_set_affinity(
- rtems_id id,
- size_t cpusetsize,
- const cpu_set_t \*cpuset
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - successful operation
-``RTEMS_INVALID_ADDRESS`` - ``cpuset`` is NULL
-``RTEMS_INVALID_ID`` - invalid task id
-``RTEMS_INVALID_NUMBER`` - invalid processor affinity set
-
-**DESCRIPTION:**
-
-Sets the processor affinity set for the task specified by ``cpuset``. A set
-bit in the affinity set means that the task can execute on this processor and a
-cleared bit means the opposite.
-
-**NOTES:**
-
-This function will not change the scheduler of the task. The intersection of
-the processor affinity set and the set of processors owned by the scheduler of
-the task must be non-empty. It is not an error if the processor affinity set
-contains processors that are not part of the set of processors owned by the
-scheduler instance of the task. A task will simply not run under normal
-circumstances on these processors since the scheduler ignores them. Some
-locking protocols may temporarily use processors that are not included in the
-processor affinity set of the task. It is also not an error if the processor
-affinity set contains processors that are not part of the system.
-
-.. COMMENT: COPYRIGHT (c) 2011,2015
-
-.. COMMENT: Aeroflex Gaisler AB
-
-.. COMMENT: All rights reserved.
-
-PCI Library
-###########
-
-.. index:: libpci
-
-Introduction
-============
-
-The Peripheral Component Interconnect (PCI) bus is a very common computer
-bus architecture that is found in almost every PC today. The PCI bus is
-normally located at the motherboard where some PCI devices are soldered
-directly onto the PCB and expansion slots allows the user to add custom
-devices easily. There is a wide range of PCI hardware available implementing
-all sorts of interfaces and functions.
-
-This section describes the PCI Library available in RTEMS used to access the
-PCI bus in a portable way across computer architectures supported by RTEMS.
-
-The PCI Library aims to be compatible with PCI 2.3 with a couple of
-limitations, for example there is no support for hot-plugging, 64-bit
-memory space and cardbus bridges.
-
-In order to support different architectures and with small foot-print embedded
-systems in mind the PCI Library offers four different configuration options
-listed below. It is selected during compile time by defining the appropriate
-macros in confdefs.h. It is also possible to enable PCI_LIB_NONE (No
-Configuration) which can be used for debuging PCI access functions.
-
-- Auto Configuration (do Plug & Play)
-
-- Read Configuration (read BIOS or boot loader configuration)
-
-- Static Configuration (write user defined configuration)
-
-- Peripheral Configuration (no access to cfg-space)
-
-Background
-==========
-
-The PCI bus is constructed in a way where on-board devices and devices
-in expansion slots can be automatically found (probed) and configured
-using Plug & Play completely implemented in software. The bus is set up once
-during boot up. The Plug & Play information can be read and written from
-PCI configuration space. A PCI device is identified in configuration space by
-a unique bus, slot and function number. Each PCI slot can have up to 8
-functions and interface to another PCI sub-bus by implementing a PCI-to-PCI
-bridge according to the PCI Bridge Architecture specification.
-
-Using the unique \[bus:slot:func] any device can be configured regardless of how
-PCI is currently set up as long as all PCI buses are enumerated correctly. The
-enumeration is done during probing, all bridges are given a bus number in
-order for the bridges to respond to accesses from both directions. The PCI
-library can assign address ranges to which a PCI device should respond using
-Plug & Play technique or a static user defined configuration. After the
-configuration has been performed the PCI device drivers can find devices by
-the read-only PCI Class type, Vendor ID and Device ID information found in
-configuration space for each device.
-
-In some systems there is a boot loader or BIOS which have already configured
-all PCI devices, but on embedded targets it is quite common that there is no
-BIOS or boot loader, thus RTEMS must configure the PCI bus. Only the PCI host
-may do configuration space access, the host driver or BSP is responsible to
-translate the \[bus:slot:func] into a valid PCI configuration space access.
-
-If the target is not a host, but a peripheral, configuration space can not be
-accessed, the peripheral is set up by the host during start up. In complex
-embedded PCI systems the peripheral may need to access other PCI boards than
-the host. In such systems a custom (static) configuration of both the host
-and peripheral may be a convenient solution.
-
-The PCI bus defines four interrupt signals INTA#..INTD#. The interrupt signals
-must be mapped into a system interrupt/vector, it is up to the BSP or host
-driver to know the mapping, however the BIOS or boot loader may use the
-8-bit read/write "Interrupt Line" register to pass the knowledge along to the
-OS.
-
-The PCI standard defines and recommends that the backplane route the interupt
-lines in a systematic way, however in standard there is no such requirement.
-The PCI Auto Configuration Library implements the recommended way of routing
-which is very common but it is also supported to some extent to override the
-interrupt routing from the BSP or Host Bridge driver using the configuration
-structure.
-
-Software Components
--------------------
-
-The PCI library is located in cpukit/libpci, it consists of different parts:
-
-- PCI Host bridge driver interface
-
-- Configuration routines
-
-- Access (Configuration, I/O and Memory space) routines
-
-- Interrupt routines (implemented by BSP)
-
-- Print routines
-
-- Static/peripheral configuration creation
-
-- PCI shell command
-
-PCI Configuration
------------------
-
-During start up the PCI bus must be configured in order for host and
-peripherals to access one another using Memory or I/O accesses and that
-interrupts are properly handled. Three different spaces are defined and
-mapped separately:
-
-# I/O space (IO)
-
-# non-prefetchable Memory space (MEMIO)
-
-# prefetchable Memory space (MEM)
-
-Regions of the same type (I/O or Memory) may not overlap which is guaranteed
-by the software. MEM regions may be mapped into MEMIO regions, but MEMIO
-regions can not be mapped into MEM, for that could lead to prefetching of
-registers. The interrupt pin which a board is driving can be read out from
-PCI configuration space, however it is up to software to know how interrupt
-signals are routed between PCI-to-PCI bridges and how PCI INT[A..D]# pins are
-mapped to system IRQ. In systems where previous software (boot loader or BIOS)
-has already set up this the configuration is overwritten or simply read out.
-
-In order to support different configuration methods the following configuration
-libraries are selectable by the user:
-
-- Auto Configuration (run Plug & Play software)
-
-- Read Configuration (relies on a boot loader or BIOS)
-
-- Static Configuration (write user defined setup, no Plug & Play)
-
-- Peripheral Configuration (user defined setup, no access to
- configuration space)
-
-A host driver can be made to support all three configuration methods, or any
-combination. It may be defined by the BSP which approach is used.
-
-The configuration software is called from the PCI driver (pci_config_init()).
-
-Regardless of configuration method a PCI device tree is created in RAM during
-initialization, the tree can be accessed to find devices and resources without
-accessing configuration space later on. The user is responsible to create the
-device tree at compile time when using the static/peripheral method.
-
-RTEMS Configuration selection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The active configuration method can be selected at compile time in the same
-way as other project parameters by including rtems/confdefs.h and setting
-
-- CONFIGURE_INIT
-
-- RTEMS_PCI_CONFIG_LIB
-
-- CONFIGURE_PCI_LIB = PCI_LIB_(AUTO,STATIC,READ,PERIPHERAL)
-
-See the RTEMS configuration section how to setup the PCI library.
-
-Auto Configuration
-~~~~~~~~~~~~~~~~~~
-
-The auto configuration software enumerates PCI buses and initializes all PCI
-devices found using Plug & Play. The auto configuration software requires
-that a configuration setup has been registered by the driver or BSP in order
-to setup the I/O and Memory regions at the correct address ranges. PCI
-interrupt pins can optionally be routed over PCI-to-PCI bridges and mapped
-to a system interrupt number. BAR resources are sorted by size and required
-alignment, unused "dead" space may be created when PCI bridges are present
-due to the PCI bridge window size does not equal the alignment. To cope with
-that resources are reordered to fit smaller BARs into the dead space to minimize
-the PCI space required. If a BAR or ROM register can not be allocated a PCI
-address region (due to too few resources available) the register will be given
-the value of pci_invalid_address which defaults to 0.
-
-The auto configuration routines support:
-
-- PCI 2.3
-
-- Little and big endian PCI bus
-
-- one I/O 16 or 32-bit range (IO)
-
-- memory space (MEMIO)
-
-- prefetchable memory space (MEM), if not present MEM will be mapped into
- MEMIO
-
-- multiple PCI buses - PCI-to-PCI bridges
-
-- standard BARs, PCI-to-PCI bridge BARs, ROM BARs
-
-- Interrupt routing over bridges
-
-- Interrupt pin to system interrupt mapping
-
-Not supported:
-
-- hot-pluggable devices
-
-- Cardbus bridges
-
-- 64-bit memory space
-
-- 16-bit and 32-bit I/O address ranges at the same time
-
-In PCI 2.3 there may exist I/O BARs that must be located at the low 64kBytes
-address range, in order to support this the host driver or BSP must make sure
-that I/O addresses region is within this region.
-
-Read Configuration
-~~~~~~~~~~~~~~~~~~
-
-When a BIOS or boot loader already has setup the PCI bus the configuration can
-be read directly from the PCI resource registers and buses are already
-enumerated, this is a much simpler approach than configuring PCI ourselves. The
-PCI device tree is automatically created based on the current configuration and
-devices present. After initialization is done there is no difference between
-the auto or read configuration approaches.
-
-Static Configuration
-~~~~~~~~~~~~~~~~~~~~
-
-To support custom configurations and small-footprint PCI systems, the user may
-provide the PCI device tree which contains the current configuration. The
-PCI buses are enumerated and all resources are written to PCI devices during
-initialization. When this approach is selected PCI boards must be located at
-the same slots every time and devices can not be removed or added, Plug & Play
-is not performed. Boards of the same type may of course be exchanged.
-
-The user can create a configuration by calling pci_cfg_print() on a running
-system that has had PCI setup by the auto or read configuration routines, it
-can be called from the PCI shell command. The user must provide the PCI device
-tree named pci_hb.
-
-Peripheral Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-On systems where a peripheral PCI device needs to access other PCI devices than
-the host the peripheral configuration approach may be handy. Most PCI devices
-answers on the PCI host’s requests and start DMA accesses into the Hosts memory,
-however in some complex systems PCI devices may want to access other devices
-on the same bus or at another PCI bus.
-
-A PCI peripheral is not allowed to do PCI configuration cycles, which
-means that it must either rely on the host to give it the addresses it
-needs, or that the addresses are predefined.
-
-This configuration approach is very similar to the static option, however the
-configuration is never written to PCI bus, instead it is only used for drivers
-to find PCI devices and resources using the same PCI API as for the host
-
-PCI Access
-----------
-
-The PCI access routines are low-level routines provided for drivers,
-configuration software, etc. in order to access different regions in a way
-not dependent upon the host driver, BSP or platform.
-
-- PCI configuration space
-
-- PCI I/O space
-
-- Registers over PCI memory space
-
-- Translate PCI address into CPU accessible address and vice versa
-
-By using the access routines drivers can be made portable over different
-architectures. The access routines take the architecture endianness into
-consideration and let the host driver or BSP implement I/O space and
-configuration space access.
-
-Some non-standard hardware may also define the PCI bus big-endian, for example
-the LEON2 AT697 PCI host bridge and some LEON3 systems may be configured that
-way. It is up to the BSP to set the appropriate PCI endianness on compile time
-(BSP_PCI_BIG_ENDIAN) in order for inline macros to be correctly defined.
-Another possibility is to use the function pointers defined by the access
-layer to implement drivers that support "run-time endianness detection".
-
-Configuration space
-~~~~~~~~~~~~~~~~~~~
-
-Configuration space is accessed using the routines listed below. The
-pci_dev_t type is used to specify a specific PCI bus, device and function. It
-is up to the host driver or BSP to create a valid access to the requested
-PCI slot. Requests made to slots that are not supported by hardware should
-result in PCISTS_MSTABRT and/or data must be ignored (writes) or 0xffffffff
-is always returned (reads).
-.. code:: c
-
- /* Configuration Space Access Read Routines \*/
- extern int pci_cfg_r8(pci_dev_t dev, int ofs, uint8_t \*data);
- extern int pci_cfg_r16(pci_dev_t dev, int ofs, uint16_t \*data);
- extern int pci_cfg_r32(pci_dev_t dev, int ofs, uint32_t \*data);
- /* Configuration Space Access Write Routines \*/
- extern int pci_cfg_w8(pci_dev_t dev, int ofs, uint8_t data);
- extern int pci_cfg_w16(pci_dev_t dev, int ofs, uint16_t data);
- extern int pci_cfg_w32(pci_dev_t dev, int ofs, uint32_t data);
-
-I/O space
-~~~~~~~~~
-
-The BSP or driver provide special routines in order to access I/O space. Some
-architectures have a special instruction accessing I/O space, others have it
-mapped into a "PCI I/O window" in the standard address space accessed by the
-CPU. The window size may vary and must be taken into consideration by the
-host driver. The below routines must be used to access I/O space. The address
-given to the functions is not the PCI I/O addresses, the caller must have
-translated PCI I/O addresses (available in the PCI BARs) into a BSP or host
-driver custom address, see `Access functions`_ for how
-addresses are translated.
-
-.. code:: c
-
- /* Read a register over PCI I/O Space \*/
- extern uint8_t pci_io_r8(uint32_t adr);
- extern uint16_t pci_io_r16(uint32_t adr);
- extern uint32_t pci_io_r32(uint32_t adr);
- /* Write a register over PCI I/O Space \*/
- extern void pci_io_w8(uint32_t adr, uint8_t data);
- extern void pci_io_w16(uint32_t adr, uint16_t data);
- extern void pci_io_w32(uint32_t adr, uint32_t data);
-
-Registers over Memory space
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-PCI host bridge hardware normally swap data accesses into the endianness of the
-host architecture in order to lower the load of the CPU, peripherals can do DMA
-without swapping. However, the host controller can not separate a standard
-memory access from a memory access to a register, registers may be mapped into
-memory space. This leads to register content being swapped, which must be
-swapped back. The below routines makes it possible to access registers over PCI
-memory space in a portable way on different architectures, the BSP or
-architecture must provide necessary functions in order to implement this.
-.. code:: c
-
- static inline uint16_t pci_ld_le16(volatile uint16_t \*addr);
- static inline void pci_st_le16(volatile uint16_t \*addr, uint16_t val);
- static inline uint32_t pci_ld_le32(volatile uint32_t \*addr);
- static inline void pci_st_le32(volatile uint32_t \*addr, uint32_t val);
- static inline uint16_t pci_ld_be16(volatile uint16_t \*addr);
- static inline void pci_st_be16(volatile uint16_t \*addr, uint16_t val);
- static inline uint32_t pci_ld_be32(volatile uint32_t \*addr);
- static inline void pci_st_be32(volatile uint32_t \*addr, uint32_t val);
-
-In order to support non-standard big-endian PCI bus the above pci_* functions
-is required, pci_ld_le16 != ld_le16 on big endian PCI buses.
-
-Access functions
-~~~~~~~~~~~~~~~~
-
-The PCI Access Library can provide device drivers with function pointers
-executing the above Configuration, I/O and Memory space accesses. The
-functions have the same arguments and return values as the above
-functions.
-
-The pci_access_func() function defined below can be used to get a function
-pointer of a specific access type.
-.. code:: c
-
- /* Get Read/Write function for accessing a register over PCI Memory Space
- * (non-inline functions).
- *
- * Arguments
- * wr 0(Read), 1(Write)
- * size 1(Byte), 2(Word), 4(Double Word)
- * func Where function pointer will be stored
- * endian PCI_LITTLE_ENDIAN or PCI_BIG_ENDIAN
- * type 1(I/O), 3(REG over MEM), 4(CFG)
- *
- * Return
- * 0 Found function
- * others No such function defined by host driver or BSP
- \*/
- int pci_access_func(int wr, int size, void \**func, int endian, int type);
-
-PCI device drivers may be written to support run-time detection of endianess,
-this is mosly for debugging or for development systems. When the product is
-finally deployed macros switch to using the inline functions instead which
-have been configured for the correct endianness.
-
-PCI address translation
-~~~~~~~~~~~~~~~~~~~~~~~
-
-When PCI addresses, both I/O and memory space, is not mapped 1:1 address
-translation before access is needed. If drivers read the PCI resources directly
-using configuration space routines or in the device tree, the addresses given
-are PCI addresses. The below functions can be used to translate PCI addresses
-into CPU accessible addresses or vice versa, translation may be different for
-different PCI spaces/regions.
-.. code:: c
-
- /* Translate PCI address into CPU accessible address \*/
- static inline int pci_pci2cpu(uint32_t \*address, int type);
- /* Translate CPU accessible address into PCI address (for DMA) \*/
- static inline int pci_cpu2pci(uint32_t \*address, int type);
-
-PCI Interrupt
--------------
-
-The PCI specification defines four different interrupt lines INTA#..INTD#,
-the interrupts are low level sensitive which make it possible to support
-multiple interrupt sources on the same interrupt line. Since the lines are
-level sensitive the interrupt sources must be acknowledged before clearing the
-interrupt contoller, or the interrupt controller must be masked. The BSP must
-provide a routine for clearing/acknowledging the interrupt controller, it is
-up to the interrupt service routine to acknowledge the interrupt source.
-
-The PCI Library relies on the BSP for implementing shared interrupt handling
-through the BSP_PCI_shared_interrupt_* functions/macros, they must be defined
-when including bsp.h.
-
-PCI device drivers may use the pci_interrupt_* routines in order to call the
-BSP specific functions in a platform independent way. The PCI interrupt
-interface has been made similar to the RTEMS IRQ extension so that a BSP can
-use the standard RTEMS interrupt functions directly.
-
-PCI Shell command
------------------
-
-The RTEMS shell has a PCI command ’pci’ which makes it possible to read/write
-configuration space, print the current PCI configuration and print out a
-configuration C-file for the static or peripheral library.
-
-.. COMMENT: COPYRIGHT (c) 1988-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Stack Bounds Checker
-####################
-
-Introduction
-============
-
-The stack bounds checker is an RTEMS support component that determines
-if a task has overrun its run-time stack. The routines provided
-by the stack bounds checker manager are:
-
-- ``rtems_stack_checker_is_blown`` - Has the Current Task Blown its Stack
-
-- ``rtems_stack_checker_report_usage`` - Report Task Stack Usage
-
-Background
-==========
-
-Task Stack
-----------
-
-Each task in a system has a fixed size stack associated with it. This
-stack is allocated when the task is created. As the task executes, the
-stack is used to contain parameters, return addresses, saved registers,
-and local variables. The amount of stack space required by a task
-is dependent on the exact set of routines used. The peak stack usage
-reflects the worst case of subroutine pushing information on the stack.
-For example, if a subroutine allocates a local buffer of 1024 bytes, then
-this data must be accounted for in the stack of every task that invokes that
-routine.
-
-Recursive routines make calculating peak stack usage difficult, if not
-impossible. Each call to the recursive routine consumes *n* bytes
-of stack space. If the routine recursives 1000 times, then ``1000 * *n*`` bytes of stack space are required.
-
-Execution
----------
-
-The stack bounds checker operates as a set of task extensions. At
-task creation time, the task’s stack is filled with a pattern to
-indicate the stack is unused. As the task executes, it will overwrite
-this pattern in memory. At each task switch, the stack bounds checker’s
-task switch extension is executed. This extension checks that:
-
-- the last ``n`` bytes of the task’s stack have
- not been overwritten. If this pattern has been damaged, it
- indicates that at some point since this task was context
- switch to the CPU, it has used too much stack space.
-
-- the current stack pointer of the task is not within
- the address range allocated for use as the task’s stack.
-
-If either of these conditions is detected, then a blown stack
-error is reported using the ``printk`` routine.
-
-The number of bytes checked for an overwrite is processor family dependent.
-The minimum stack frame per subroutine call varies widely between processor
-families. On CISC families like the Motorola MC68xxx and Intel ix86, all
-that is needed is a return address. On more complex RISC processors,
-the minimum stack frame per subroutine call may include space to save
-a significant number of registers.
-
-Another processor dependent feature that must be taken into account by
-the stack bounds checker is the direction that the stack grows. On some
-processor families, the stack grows up or to higher addresses as the
-task executes. On other families, it grows down to lower addresses. The
-stack bounds checker implementation uses the stack description definitions
-provided by every RTEMS port to get for this information.
-
-Operations
-==========
-
-Initializing the Stack Bounds Checker
--------------------------------------
-
-The stack checker is initialized automatically when its task
-create extension runs for the first time.
-
-The application must include the stack bounds checker extension set
-in its set of Initial Extensions. This set of extensions is
-defined as ``STACK_CHECKER_EXTENSION``. If using ``<rtems/confdefs.h>``
-for Configuration Table generation, then all that is necessary is
-to define the macro ``CONFIGURE_STACK_CHECKER_ENABLED`` before including``<rtems/confdefs.h>`` as shown below:
-.. code:: c
-
- #define CONFIGURE_STACK_CHECKER_ENABLED
- ...
- #include <rtems/confdefs.h>
-
-Checking for Blown Task Stack
------------------------------
-
-The application may check whether the stack pointer of currently
-executing task is within proper bounds at any time by calling
-the ``rtems_stack_checker_is_blown`` method. This
-method return ``FALSE`` if the task is operating within its
-stack bounds and has not damaged its pattern area.
-
-Reporting Task Stack Usage
---------------------------
-
-The application may dynamically report the stack usage for every task
-in the system by calling the``rtems_stack_checker_report_usage`` routine.
-This routine prints a table with the peak usage and stack size of
-every task in the system. The following is an example of the
-report generated:
-.. code:: c
-
- ID NAME LOW HIGH AVAILABLE USED
- 0x04010001 IDLE 0x003e8a60 0x003e9667 2952 200
- 0x08010002 TA1 0x003e5750 0x003e7b57 9096 1168
- 0x08010003 TA2 0x003e31c8 0x003e55cf 9096 1168
- 0x08010004 TA3 0x003e0c40 0x003e3047 9096 1104
- 0xffffffff INTR 0x003ecfc0 0x003effbf 12160 128
-
-Notice the last time. The task id is 0xffffffff and its name is "INTR".
-This is not actually a task, it is the interrupt stack.
-
-When a Task Overflows the Stack
--------------------------------
-
-When the stack bounds checker determines that a stack overflow has occurred,
-it will attempt to print a message using ``printk`` identifying the
-task and then shut the system down. If the stack overflow has caused
-corruption, then it is possible that the message cannot be printed.
-
-The following is an example of the output generated:
-.. code:: c
-
- BLOWN STACK!!! Offending task(0x3eb360): id=0x08010002; name=0x54413120
- stack covers range 0x003e5750 - 0x003e7b57 (9224 bytes)
- Damaged pattern begins at 0x003e5758 and is 128 bytes long
-
-The above includes the task id and a pointer to the task control block as
-well as enough information so one can look at the task’s stack and
-see what was happening.
-
-Routines
-========
-
-This section details the stack bounds checker’s routines.
-A subsection is dedicated to each of routines
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-.. COMMENT: rtems_stack_checker_is_blown
-
-STACK_CHECKER_IS_BLOWN - Has Current Task Blown Its Stack
----------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- bool rtems_stack_checker_is_blown( void );
-
-**STATUS CODES:**
-
-``TRUE`` - Stack is operating within its stack limits
-``FALSE`` - Current stack pointer is outside allocated area
-
-**DESCRIPTION:**
-
-This method is used to determine if the current stack pointer
-of the currently executing task is within bounds.
-
-**NOTES:**
-
-This method checks the current stack pointer against
-the high and low addresses of the stack memory allocated when
-the task was created and it looks for damage to the high water
-mark pattern for the worst case usage of the task being called.
-
-STACK_CHECKER_REPORT_USAGE - Report Task Stack Usage
-----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_stack_checker_report_usage( void );
-
-**STATUS CODES: NONE**
-
-**DESCRIPTION:**
-
-This routine prints a table with the peak stack usage and stack space
-allocation of every task in the system.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-CPU Usage Statistics
-####################
-
-Introduction
-============
-
-The CPU usage statistics manager is an RTEMS support
-component that provides a convenient way to manipulate
-the CPU usage information associated with each task
-The routines provided by the CPU usage statistics manager are:
-
-- ``rtems_cpu_usage_report`` - Report CPU Usage Statistics
-
-- ``rtems_cpu_usage_reset`` - Reset CPU Usage Statistics
-
-Background
-==========
-
-When analyzing and debugging real-time applications, it is important
-to be able to know how much CPU time each task in the system consumes.
-This support component provides a mechanism to easily obtain this
-information with little burden placed on the target.
-
-The raw data is gathered as part of performing a context switch. RTEMS
-keeps track of how many clock ticks have occurred which the task being
-switched out has been executing. If the task has been running less than
-1 clock tick, then for the purposes of the statistics, it is assumed to
-have executed 1 clock tick. This results in some inaccuracy but the
-alternative is for the task to have appeared to execute 0 clock ticks.
-
-RTEMS versions newer than the 4.7 release series, support the ability
-to obtain timestamps with nanosecond granularity if the BSP provides
-support. It is a desirable enhancement to change the way the usage
-data is gathered to take advantage of this recently added capability.
-Please consider sponsoring the core RTEMS development team to add
-this capability.
-
-Operations
-==========
-
-Report CPU Usage Statistics
----------------------------
-
-The application may dynamically report the CPU usage for every
-task in the system by calling the``rtems_cpu_usage_report`` routine.
-This routine prints a table with the following information per task:
-
-- task id
-
-- task name
-
-- number of clock ticks executed
-
-- percentage of time consumed by this task
-
-The following is an example of the report generated:
-
-
-+------------------------------------------------------------------------------+
-|CPU USAGE BY THREAD |
-+-----------+----------------------------------------+-------------------------+
-|ID | NAME | SECONDS | PERCENT |
-+-----------+----------------------------------------+---------------+---------+
-|0x04010001 | IDLE | 0 | 0.000 |
-+-----------+----------------------------------------+---------------+---------+
-|0x08010002 | TA1 | 1203 | 0.748 |
-+-----------+----------------------------------------+---------------+---------+
-|0x08010003 | TA2 | 203 | 0.126 |
-+-----------+----------------------------------------+---------------+---------+
-|0x08010004 | TA3 | 202 | 0.126 |
-+-----------+----------------------------------------+---------------+---------+
-|TICKS SINCE LAST SYSTEM RESET: 1600 |
-|TOTAL UNITS: 1608 |
-+------------------------------------------------------------------------------+
-
-Notice that the "TOTAL UNITS" is greater than the ticks per reset.
-This is an artifact of the way in which RTEMS keeps track of CPU
-usage. When a task is context switched into the CPU, the number
-of clock ticks it has executed is incremented. While the task
-is executing, this number is incremented on each clock tick.
-Otherwise, if a task begins and completes execution between
-successive clock ticks, there would be no way to tell that it
-executed at all.
-
-Another thing to keep in mind when looking at idle time, is that
-many systems – especially during debug – have a task providing
-some type of debug interface. It is usually fine to think of the
-total idle time as being the sum of the IDLE task and a debug
-task that will not be included in a production build of an application.
-
-Reset CPU Usage Statistics
---------------------------
-
-Invoking the ``rtems_cpu_usage_reset`` routine resets
-the CPU usage statistics for all tasks in the system.
-
-Directives
-==========
-
-This section details the CPU usage statistics 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.
-
-cpu_usage_report - Report CPU Usage Statistics
-----------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_cpu_usage_report( void );
-
-**STATUS CODES: NONE**
-
-**DESCRIPTION:**
-
-This routine prints out a table detailing the CPU usage statistics for
-all tasks in the system.
-
-**NOTES:**
-
-The table is printed using the ``printk`` routine.
-
-cpu_usage_reset - Reset CPU Usage Statistics
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_cpu_usage_reset( void );
-
-**STATUS CODES: NONE**
-
-**DESCRIPTION:**
-
-This routine re-initializes the CPU usage statistics for all tasks
-in the system to their initial state. The initial state is that
-a task has not executed and thus has consumed no CPU time.
-default state which is when zero period executions have occurred.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Object Services
-###############
-
-.. index:: object manipulation
-
-Introduction
-============
-
-RTEMS provides a collection of services to assist in the
-management and usage of the objects created and utilized
-via other managers. These services assist in the
-manipulation of RTEMS objects independent of the API used
-to create them. The object related services provided by
-RTEMS are:
-
-- build_id
-
-- ``rtems_build_name`` - build object name from characters
-
-- ``rtems_object_get_classic_name`` - lookup name from Id
-
-- ``rtems_object_get_name`` - obtain object name as string
-
-- ``rtems_object_set_name`` - set object name
-
-- ``rtems_object_id_get_api`` - obtain API from Id
-
-- ``rtems_object_id_get_class`` - obtain class from Id
-
-- ``rtems_object_id_get_node`` - obtain node from Id
-
-- ``rtems_object_id_get_index`` - obtain index from Id
-
-- ``rtems_build_id`` - build object id from components
-
-- ``rtems_object_id_api_minimum`` - obtain minimum API value
-
-- ``rtems_object_id_api_maximum`` - obtain maximum API value
-
-- ``rtems_object_id_api_minimum_class`` - obtain minimum class value
-
-- ``rtems_object_id_api_maximum_class`` - obtain maximum class value
-
-- ``rtems_object_get_api_name`` - obtain API name
-
-- ``rtems_object_get_api_class_name`` - obtain class name
-
-- ``rtems_object_get_class_information`` - obtain class information
-
-Background
-==========
-
-APIs
-----
-
-RTEMS implements multiple APIs including an Internal API,
-the Classic API, and the POSIX API. These
-APIs share the common foundation of SuperCore objects and
-thus share object management code. This includes a common
-scheme for object Ids and for managing object names whether
-those names be in the thirty-two bit form used by the Classic
-API or C strings.
-
-The object Id contains a field indicating the API that
-an object instance is associated with. This field
-holds a numerically small non-zero integer.
-
-Object Classes
---------------
-
-Each API consists of a collection of managers. Each manager
-is responsible for instances of a particular object class.
-Classic API Tasks and POSIX Mutexes example classes.
-
-The object Id contains a field indicating the class that
-an object instance is associated with. This field
-holds a numerically small non-zero integer. In all APIs,
-a class value of one is reserved for tasks or threads.
-
-Object Names
-------------
-
-Every RTEMS object which has an Id may also have a
-name associated with it. Depending on the API, names
-may be either thirty-two bit integers as in the Classic
-API or strings as in the POSIX API.
-
-Some objects have Ids but do not have a defined way to associate
-a name with them. For example, POSIX threads have
-Ids but per POSIX do not have names. In RTEMS, objects
-not defined to have thirty-two bit names may have string
-names assigned to them via the ``rtems_object_set_name``
-service. The original impetus in providing this service
-was so the normally anonymous POSIX threads could have
-a user defined name in CPU Usage Reports.
-
-Operations
-==========
-
-Decomposing and Recomposing an Object Id
-----------------------------------------
-
-Services are provided to decompose an object Id into its
-subordinate components. The following services are used
-to do this:
-
-- ``rtems_object_id_get_api``
-
-- ``rtems_object_id_get_class``
-
-- ``rtems_object_id_get_node``
-
-- ``rtems_object_id_get_index``
-
-The following C language example illustrates the
-decomposition of an Id and printing the values.
-.. code:: c
-
- void printObjectId(rtems_id id)
- {
- printf(
- "API=%d Class=%d Node=%d Index=%d\\n",
- rtems_object_id_get_api(id),
- rtems_object_id_get_class(id),
- rtems_object_id_get_node(id),
- rtems_object_id_get_index(id)
- );
- }
-
-This prints the components of the Ids as integers.
-
-It is also possible to construct an arbitrary Id using
-the ``rtems_build_id`` service. The following
-C language example illustrates how to construct the
-"next Id."
-.. code:: c
-
- rtems_id nextObjectId(rtems_id id)
- {
- return rtems_build_id(
- rtems_object_id_get_api(id),
- rtems_object_id_get_class(id),
- rtems_object_id_get_node(id),
- rtems_object_id_get_index(id) + 1
- );
- }
-
-Note that this Id may not be valid in this
-system or associated with an allocated object.
-
-Printing an Object Id
----------------------
-
-RTEMS also provides services to associate the API and Class
-portions of an Object Id with strings. This allows the
-application developer to provide more information about
-an object in diagnostic messages.
-
-In the following C language example, an Id is decomposed into
-its constituent parts and "pretty-printed."
-.. code:: c
-
- void prettyPrintObjectId(rtems_id id)
- {
- int tmpAPI, tmpClass;
- tmpAPI = rtems_object_id_get_api(id),
- tmpClass = rtems_object_id_get_class(id),
- printf(
- "API=%s Class=%s Node=%d Index=%d\\n",
- rtems_object_get_api_name(tmpAPI),
- rtems_object_get_api_class_name(tmpAPI, tmpClass),
- rtems_object_id_get_node(id),
- rtems_object_id_get_index(id)
- );
- }
-
-Directives
-==========
-
-BUILD_NAME - Build object name from characters
-----------------------------------------------
-.. index:: build object name
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_build_name
-
-.. code:: c
-
- rtems_name rtems_build_name(
- uint8_t c1,
- uint8_t c2,
- uint8_t c3,
- uint8_t c4
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns a name constructed from the four characters.
-
-**DESCRIPTION:**
-
-This service takes the four characters provided as arguments
-and constructs a thirty-two bit object name with ``c1``
-in the most significant byte and ``c4`` in the least
-significant byte.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_GET_CLASSIC_NAME - Lookup name from id
----------------------------------------------
-.. index:: get name from id
-.. index:: obtain name from id
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_build_name
-
-.. code:: c
-
- rtems_status_code rtems_object_get_classic_name(
- rtems_id id,
- rtems_name \*name
- );
-
-**DIRECTIVE STATUS CODES**
-
-``RTEMS_SUCCESSFUL`` - name looked up successfully
-``RTEMS_INVALID_ADDRESS`` - invalid name pointer
-``RTEMS_INVALID_ID`` - invalid object id
-
-**DESCRIPTION:**
-
-This service looks up the name for the object ``id`` specified
-and, if found, places the result in ``*name``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_GET_NAME - Obtain object name as string
-----------------------------------------------
-.. index:: get object name as string
-.. index:: obtain object name as string
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_get_name
-
-.. code:: c
-
- char \*rtems_object_get_name(
- rtems_id id,
- size_t length,
- char \*name
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns a pointer to the name if successful or ``NULL``
-otherwise.
-
-**DESCRIPTION:**
-
-This service looks up the name of the object specified by``id`` and places it in the memory pointed to by ``name``.
-Every attempt is made to return name as a printable string even
-if the object has the Classic API thirty-two bit style name.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_SET_NAME - Set object name
----------------------------------
-.. index:: set object name
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_set_name
-
-.. code:: c
-
- rtems_status_code rtems_object_set_name(
- rtems_id id,
- const char \*name
- );
-
-**DIRECTIVE STATUS CODES**
-
-``RTEMS_SUCCESSFUL`` - name looked up successfully
-``RTEMS_INVALID_ADDRESS`` - invalid name pointer
-``RTEMS_INVALID_ID`` - invalid object id
-
-**DESCRIPTION:**
-
-This service sets the name of ``id`` to that specified
-by the string located at ``name``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-If the object specified by ``id`` is of a class that
-has a string name, this method will free the existing
-name to the RTEMS Workspace and allocate enough memory
-from the RTEMS Workspace to make a copy of the string
-located at ``name``.
-
-If the object specified by ``id`` is of a class that
-has a thirty-two bit integer style name, then the first
-four characters in ``*name`` will be used to construct
-the name.
-name to the RTEMS Workspace and allocate enough memory
-from the RTEMS Workspace to make a copy of the string
-
-OBJECT_ID_GET_API - Obtain API from Id
---------------------------------------
-.. index:: obtain API from id
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_id_get_api
-
-.. code:: c
-
- int rtems_object_id_get_api(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns the API portion of the object Id.
-
-**DESCRIPTION:**
-
-This directive returns the API portion of the provided object ``id``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-This directive does NOT validate the ``id`` provided.
-
-OBJECT_ID_GET_CLASS - Obtain Class from Id
-------------------------------------------
-.. index:: obtain class from object id
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_id_get_class
-
-.. code:: c
-
- int rtems_object_id_get_class(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns the class portion of the object Id.
-
-**DESCRIPTION:**
-
-This directive returns the class portion of the provided object ``id``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-This directive does NOT validate the ``id`` provided.
-
-OBJECT_ID_GET_NODE - Obtain Node from Id
-----------------------------------------
-.. index:: obtain node from object id
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_id_get_node
-
-.. code:: c
-
- int rtems_object_id_get_node(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns the node portion of the object Id.
-
-**DESCRIPTION:**
-
-This directive returns the node portion of the provided object ``id``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-This directive does NOT validate the ``id`` provided.
-
-OBJECT_ID_GET_INDEX - Obtain Index from Id
-------------------------------------------
-.. index:: obtain index from object id
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_id_get_index
-
-.. code:: c
-
- int rtems_object_id_get_index(
- rtems_id id
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns the index portion of the object Id.
-
-**DESCRIPTION:**
-
-This directive returns the index portion of the provided object ``id``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-This directive does NOT validate the ``id`` provided.
-
-BUILD_ID - Build Object Id From Components
-------------------------------------------
-.. index:: build object id from components
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_build_id
-
-.. code:: c
-
- rtems_id rtems_build_id(
- int the_api,
- int the_class,
- int the_node,
- int the_index
- );
-
-**DIRECTIVE STATUS CODES**
-
-Returns an object Id constructed from the provided arguments.
-
-**DESCRIPTION:**
-
-This service constructs an object Id from the provided``the_api``, ``the_class``, ``the_node``, and ``the_index``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-This directive does NOT validate the arguments provided
-or the Object id returned.
-
-OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
-------------------------------------------------
-.. index:: obtain minimum API value
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_id_api_minimum
-
-.. code:: c
-
- int rtems_object_id_api_minimum(void);
-
-**DIRECTIVE STATUS CODES**
-
-Returns the minimum valid for the API portion of an object Id.
-
-**DESCRIPTION:**
-
-This service returns the minimum valid for the API portion of
-an object Id.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
-------------------------------------------------
-.. index:: obtain maximum API value
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_id_api_maximum
-
-.. code:: c
-
- int rtems_object_id_api_maximum(void);
-
-**DIRECTIVE STATUS CODES**
-
-Returns the maximum valid for the API portion of an object Id.
-
-**DESCRIPTION:**
-
-This service returns the maximum valid for the API portion of
-an object Id.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
------------------------------------------------------
-.. index:: obtain minimum class value
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_api_minimum_class
-
-.. code:: c
-
- int rtems_object_api_minimum_class(
- int api
- );
-
-**DIRECTIVE STATUS CODES**
-
-If ``api`` is not valid, -1 is returned.
-
-If successful, this service returns the minimum valid for the class
-portion of an object Id for the specified ``api``.
-
-**DESCRIPTION:**
-
-This service returns the minimum valid for the class portion of
-an object Id for the specified ``api``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
------------------------------------------------------
-.. index:: obtain maximum class value
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_api_maximum_class
-
-.. code:: c
-
- int rtems_object_api_maximum_class(
- int api
- );
-
-**DIRECTIVE STATUS CODES**
-
-If ``api`` is not valid, -1 is returned.
-
-If successful, this service returns the maximum valid for the class
-portion of an object Id for the specified ``api``.
-
-**DESCRIPTION:**
-
-This service returns the maximum valid for the class portion of
-an object Id for the specified ``api``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-OBJECT_GET_API_NAME - Obtain API Name
--------------------------------------
-.. index:: obtain API name
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_get_api_name
-
-.. code:: c
-
- const char \*rtems_object_get_api_name(
- int api
- );
-
-**DIRECTIVE STATUS CODES**
-
-If ``api`` is not valid, the string ``"BAD API"`` is returned.
-
-If successful, this service returns a pointer to a string
-containing the name of the specified ``api``.
-
-**DESCRIPTION:**
-
-This service returns the name of the specified ``api``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-The string returned is from constant space. Do not modify
-or free it.
-
-OBJECT_GET_API_CLASS_NAME - Obtain Class Name
----------------------------------------------
-.. index:: obtain class name
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_get_api_class_name
-
-.. code:: c
-
- const char \*rtems_object_get_api_class_name(
- int the_api,
- int the_class
- );
-
-**DIRECTIVE STATUS CODES**
-
-If ``the_api`` is not valid, the string ``"BAD API"`` is returned.
-
-If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned.
-
-If successful, this service returns a pointer to a string
-containing the name of the specified ``the_api``/``the_class`` pair.
-
-**DESCRIPTION:**
-
-This service returns the name of the object class indicated by the
-specified ``the_api`` and ``the_class``.
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-The string returned is from constant space. Do not modify
-or free it.
-
-OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
--------------------------------------------------------
-.. index:: obtain class information
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_object_get_class_information
-
-.. code:: c
-
- rtems_status_code rtems_object_get_class_information(
- int the_api,
- int the_class,
- rtems_object_api_class_information \*info
- );
-
-**DIRECTIVE STATUS CODES**
-
-``RTEMS_SUCCESSFUL`` - information obtained successfully
-``RTEMS_INVALID_ADDRESS`` - ``info`` is NULL
-``RTEMS_INVALID_NUMBER`` - invalid ``api`` or ``the_class``
-
-If successful, the structure located at ``info`` will be filled
-in with information about the specified ``api``/``the_class`` pairing.
-
-**DESCRIPTION:**
-
-This service returns information about the object class indicated by the
-specified ``api`` and ``the_class``. This structure is defined as
-follows:
-.. code:: c
-
- typedef struct {
- rtems_id minimum_id;
- rtems_id maximum_id;
- int maximum;
- bool auto_extend;
- int unallocated;
- } rtems_object_api_class_information;
-
-**NOTES:**
-
-This directive is strictly local and does not impact task scheduling.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Chains
-######
-
-.. index:: chains
-
-Introduction
-============
-
-The Chains API is an interface to the Super Core (score) chain
-implementation. The Super Core uses chains for all list type
-functions. This includes wait queues and task queues. The Chains API
-provided by RTEMS is:
-
-- build_id
-
-- ``rtems_chain_node`` - Chain node used in user objects
-
-- ``rtems_chain_control`` - Chain control node
-
-- ``rtems_chain_initialize`` - initialize the chain with nodes
-
-- ``rtems_chain_initialize_empty`` - initialize the chain as empty
-
-- ``rtems_chain_is_null_node`` - Is the node NULL ?
-
-- ``rtems_chain_head`` - Return the chain’s head
-
-- ``rtems_chain_tail`` - Return the chain’s tail
-
-- ``rtems_chain_are_nodes_equal`` - Are the node’s equal ?
-
-- ``rtems_chain_is_empty`` - Is the chain empty ?
-
-- ``rtems_chain_is_first`` - Is the Node the first in the chain ?
-
-- ``rtems_chain_is_last`` - Is the Node the last in the chain ?
-
-- ``rtems_chain_has_only_one_node`` - Does the node have one node ?
-
-- ``rtems_chain_node_count_unprotected`` - Returns the node count of the chain (unprotected)
-
-- ``rtems_chain_is_head`` - Is the node the head ?
-
-- ``rtems_chain_is_tail`` - Is the node the tail ?
-
-- ``rtems_chain_extract`` - Extract the node from the chain
-
-- ``rtems_chain_extract_unprotected`` - Extract the node from the chain (unprotected)
-
-- ``rtems_chain_get`` - Return the first node on the chain
-
-- ``rtems_chain_get_unprotected`` - Return the first node on the chain (unprotected)
-
-- ``rtems_chain_get_first_unprotected`` - Get the first node on the chain (unprotected)
-
-- ``rtems_chain_insert`` - Insert the node into the chain
-
-- ``rtems_chain_insert_unprotected`` - Insert the node into the chain (unprotected)
-
-- ``rtems_chain_append`` - Append the node to chain
-
-- ``rtems_chain_append_unprotected`` - Append the node to chain (unprotected)
-
-- ``rtems_chain_prepend`` - Prepend the node to the end of the chain
-
-- ``rtems_chain_prepend_unprotected`` - Prepend the node to chain (unprotected)
-
-Background
-==========
-
-The Chains API maps to the Super Core Chains API. Chains are
-implemented as a double linked list of nodes anchored to a control
-node. The list starts at the control node and is terminated at the
-control node. A node has previous and next pointers. Being a double
-linked list nodes can be inserted and removed without the need to
-travse the chain.
-
-Chains have a small memory footprint and can be used in interrupt
-service routines and are thread safe in a multi-threaded
-environment. The directives list which operations disable interrupts.
-
-Chains are very useful in Board Support packages and applications.
-
-Nodes
------
-
-A chain is made up from nodes that orginate from a chain control
-object. A node is of type ``rtems_chain_node``. The node
-is designed to be part of a user data structure and a cast is used to
-move from the node address to the user data structure address. For
-example:
-.. code:: c
-
- typedef struct foo
- {
- rtems_chain_node node;
- int bar;
- } foo;
-
-creates a type ``foo`` that can be placed on a chain. To get the
-foo structure from the list you perform the following:
-.. code:: c
-
- foo* get_foo(rtems_chain_control* control)
- {
- return (foo*) rtems_chain_get(control);
- }
-
-The node is placed at the start of the user’s structure to allow the
-node address on the chain to be easly cast to the user’s structure
-address.
-
-Controls
---------
-
-A chain is anchored with a control object. Chain control provide the
-user with access to the nodes on the chain. The control is head of the
-node.
-
-.. code:: c
-
- Control
- first ------------------------>
- permanent_null <--------------- NODE
- last ------------------------->
-
-The implementation does not require special checks for manipulating
-the first and last nodes on the chain. To accomplish this the``rtems_chain_control`` structure is treated as two
-overlapping ``rtems_chain_node`` structures. The
-permanent head of the chain overlays a node structure on the first and``permanent_null`` fields. The ``permanent_tail`` of the chain
-overlays a node structure on the ``permanent_null`` and ``last``
-elements of the structure.
-
-Operations
-==========
-
-Multi-threading
----------------
-
-Chains are designed to be used in a multi-threading environment. The
-directives list which operations mask interrupts. Chains supports
-tasks and interrupt service routines appending and extracting nodes
-with out the need for extra locks. Chains how-ever cannot insure the
-integrity of a chain for all operations. This is the responsibility of
-the user. For example an interrupt service routine extracting nodes
-while a task is iterating over the chain can have unpredictable
-results.
-
-Creating a Chain
-----------------
-
-To create a chain you need to declare a chain control then add nodes
-to the control. Consider a user structure and chain control:
-.. code:: c
-
- typedef struct foo
- {
- rtems_chain_node node;
- uint8_t char* data;
- } foo;
- rtems_chain_control chain;
-
-Add nodes with the following code:
-.. code:: c
-
- rtems_chain_initialize_empty (&chain);
- for (i = 0; i < count; i++)
- {
- foo* bar = malloc (sizeof (foo));
- if (!bar)
- return -1;
- bar->data = malloc (size);
- rtems_chain_append (&chain, &bar->node);
- }
-
-The chain is initialized and the nodes allocated and appended to the
-chain. This is an example of a pool of buffers.
-
-Iterating a Chain
------------------
-.. index:: chain iterate
-
-Iterating a chain is a common function. The example shows how to
-iterate the buffer pool chain created in the last section to find
-buffers starting with a specific string. If the buffer is located it is
-extracted from the chain and placed on another chain:
-.. code:: c
-
- void foobar (const char* match,
- rtems_chain_control* chain,
- rtems_chain_control* out)
- {
- rtems_chain_node* node;
- foo* bar;
- rtems_chain_initialize_empty (out);
- node = chain->first;
- while (!rtems_chain_is_tail (chain, node))
- {
- bar = (foo*) node;
- rtems_chain_node* next_node = node->next;
- if (strcmp (match, bar->data) == 0)
- {
- rtems_chain_extract (node);
- rtems_chain_append (out, node);
- }
- node = next_node;
- }
- }
-
-Directives
-==========
-
-The section details the Chains directives.
-
-.. COMMENT: Initialize this Chain With Nodes
-
-Initialize Chain With Nodes
----------------------------
-.. index:: chain initialize
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_initialize
-
-.. code:: c
-
- void rtems_chain_initialize(
- rtems_chain_control \*the_chain,
- void \*starting_address,
- size_t number_nodes,
- size_t node_size
- )
-
-**RETURNS**
-
-Returns nothing.
-
-**DESCRIPTION:**
-
-This function take in a pointer to a chain control and initializes it
-to contain a set of chain nodes. The chain will contain ``number_nodes``
-chain nodes from the memory pointed to by ``start_address``. Each node
-is assumed to be ``node_size`` bytes.
-
-**NOTES:**
-
-This call will discard any nodes on the chain.
-
-This call does NOT inititialize any user data on each node.
-
-.. COMMENT: Initialize this Chain as Empty
-
-Initialize Empty
-----------------
-.. index:: chain initialize empty
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_initialize_empty
-
-.. code:: c
-
- void rtems_chain_initialize_empty(
- rtems_chain_control \*the_chain
- );
-
-**RETURNS**
-
-Returns nothing.
-
-**DESCRIPTION:**
-
-This function take in a pointer to a chain control and initializes it
-to empty.
-
-**NOTES:**
-
-This call will discard any nodes on the chain.
-
-Is Null Node ?
---------------
-.. index:: chain is node null
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_is_null_node
-
-.. code:: c
-
- bool rtems_chain_is_null_node(
- const rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-Returns ``true`` is the node point is NULL and ``false`` if the node is not
-NULL.
-
-**DESCRIPTION:**
-
-Tests the node to see if it is a NULL returning ``true`` if a null.
-
-Head
-----
-.. index:: chain get head
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_head
-
-.. code:: c
-
- rtems_chain_node \*rtems_chain_head(
- rtems_chain_control \*the_chain
- )
-
-**RETURNS**
-
-Returns the permanent head node of the chain.
-
-**DESCRIPTION:**
-
-This function returns a pointer to the first node on the chain.
-
-Tail
-----
-.. index:: chain get tail
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_tail
-
-.. code:: c
-
- rtems_chain_node \*rtems_chain_tail(
- rtems_chain_control \*the_chain
- );
-
-**RETURNS**
-
-Returns the permanent tail node of the chain.
-
-**DESCRIPTION:**
-
-This function returns a pointer to the last node on the chain.
-
-Are Two Nodes Equal ?
----------------------
-.. index:: chare are nodes equal
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_are_nodes_equal
-
-.. code:: c
-
- bool rtems_chain_are_nodes_equal(
- const rtems_chain_node \*left,
- const rtems_chain_node \*right
- );
-
-**RETURNS**
-
-This function returns ``true`` if the left node and the right node are
-equal, and ``false`` otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if the left node and the right node are
-equal, and ``false`` otherwise.
-
-Is the Chain Empty
-------------------
-.. index:: chain is chain empty
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_is_empty
-
-.. code:: c
-
- bool rtems_chain_is_empty(
- rtems_chain_control \*the_chain
- );
-
-**RETURNS**
-
-This function returns ``true`` if there a no nodes on the chain and ``false``
-otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if there a no nodes on the chain and ``false``
-otherwise.
-
-Is this the First Node on the Chain ?
--------------------------------------
-.. index:: chain is node the first
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_is_first
-
-.. code:: c
-
- bool rtems_chain_is_first(
- const rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-This function returns ``true`` if the node is the first node on a chain
-and ``false`` otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if the node is the first node on a chain
-and ``false`` otherwise.
-
-Is this the Last Node on the Chain ?
-------------------------------------
-.. index:: chain is node the last
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_is_last
-
-.. code:: c
-
- bool rtems_chain_is_last(
- const rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-This function returns ``true`` if the node is the last node on a chain and``false`` otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if the node is the last node on a chain and``false`` otherwise.
-
-Does this Chain have only One Node ?
-------------------------------------
-.. index:: chain only one node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_has_only_one_node
-
-.. code:: c
-
- bool rtems_chain_has_only_one_node(
- const rtems_chain_control \*the_chain
- );
-
-**RETURNS**
-
-This function returns ``true`` if there is only one node on the chain and``false`` otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if there is only one node on the chain and``false`` otherwise.
-
-Returns the node count of the chain (unprotected)
--------------------------------------------------
-.. index:: chain only one node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_node_count_unprotected
-
-.. code:: c
-
- size_t rtems_chain_node_count_unprotected(
- const rtems_chain_control \*the_chain
- );
-
-**RETURNS**
-
-This function returns the node count of the chain.
-
-**DESCRIPTION:**
-
-This function returns the node count of the chain.
-
-Is this Node the Chain Head ?
------------------------------
-.. index:: chain is node the head
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_is_head
-
-.. code:: c
-
- bool rtems_chain_is_head(
- rtems_chain_control \*the_chain,
- rtems_const chain_node \*the_node
- );
-
-**RETURNS**
-
-This function returns ``true`` if the node is the head of the chain and``false`` otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if the node is the head of the chain and``false`` otherwise.
-
-Is this Node the Chain Tail ?
------------------------------
-.. index:: chain is node the tail
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_is_tail
-
-.. code:: c
-
- bool rtems_chain_is_tail(
- rtems_chain_control \*the_chain,
- const rtems_chain_node \*the_node
- )
-
-**RETURNS**
-
-This function returns ``true`` if the node is the tail of the chain and``false`` otherwise.
-
-**DESCRIPTION:**
-
-This function returns ``true`` if the node is the tail of the chain and``false`` otherwise.
-
-Extract a Node
---------------
-.. index:: chain extract a node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_extract
-
-.. code:: c
-
- void rtems_chain_extract(
- rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-Returns nothing.
-
-**DESCRIPTION:**
-
-This routine extracts the node from the chain on which it resides.
-
-**NOTES:**
-
-Interrupts are disabled while extracting the node to ensure the
-atomicity of the operation.
-
-Use ``rtems_chain_extract_unprotected()`` to avoid disabling of
-interrupts.
-
-Get the First Node
-------------------
-.. index:: chain get first node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_get
-
-.. code:: c
-
- rtems_chain_node \*rtems_chain_get(
- rtems_chain_control \*the_chain
- );
-
-**RETURNS**
-
-Returns a pointer a node. If a node was removed, then a pointer to
-that node is returned. If the chain was empty, then NULL is
-returned.
-
-**DESCRIPTION:**
-
-This function removes the first node from the chain and returns a
-pointer to that node. If the chain is empty, then NULL is returned.
-
-**NOTES:**
-
-Interrupts are disabled while obtaining the node to ensure the
-atomicity of the operation.
-
-Use ``rtems_chain_get_unprotected()`` to avoid disabling of
-interrupts.
-
-Get the First Node (unprotected)
---------------------------------
-.. index:: chain get first node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_get_first_unprotected
-
-.. code:: c
-
- rtems_chain_node \*rtems_chain_get_first_unprotected(
- rtems_chain_control \*the_chain
- );
-
-**RETURNS:**
-
-A pointer to the former first node is returned.
-
-**DESCRIPTION:**
-
-Removes the first node from the chain and returns a pointer to it. In case the
-chain was empty, then the results are unpredictable.
-
-**NOTES:**
-
-The function does nothing to ensure the atomicity of the operation.
-
-Insert a Node
--------------
-.. index:: chain insert a node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_insert
-
-.. code:: c
-
- void rtems_chain_insert(
- rtems_chain_node \*after_node,
- rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-Returns nothing.
-
-**DESCRIPTION:**
-
-This routine inserts a node on a chain immediately following the
-specified node.
-
-**NOTES:**
-
-Interrupts are disabled during the insert to ensure the atomicity of
-the operation.
-
-Use ``rtems_chain_insert_unprotected()`` to avoid disabling of
-interrupts.
-
-Append a Node
--------------
-.. index:: chain append a node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_append
-
-.. code:: c
-
- void rtems_chain_append(
- rtems_chain_control \*the_chain,
- rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-Returns nothing.
-
-**DESCRIPTION:**
-
-This routine appends a node to the end of a chain.
-
-**NOTES:**
-
-Interrupts are disabled during the append to ensure the atomicity of
-the operation.
-
-Use ``rtems_chain_append_unprotected()`` to avoid disabling of
-interrupts.
-
-Prepend a Node
---------------
-.. index:: prepend node
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_chain_prepend
-
-.. code:: c
-
- void rtems_chain_prepend(
- rtems_chain_control \*the_chain,
- rtems_chain_node \*the_node
- );
-
-**RETURNS**
-
-Returns nothing.
-
-**DESCRIPTION:**
-
-This routine prepends a node to the front of the chain.
-
-**NOTES:**
-
-Interrupts are disabled during the prepend to ensure the atomicity of
-the operation.
-
-Use ``rtems_chain_prepend_unprotected()`` to avoid disabling of
-interrupts.
-
-.. COMMENT: Copyright 2014 Gedare Bloom.
-
-.. COMMENT: All rights reserved.
-
-Red-Black Trees
-###############
-
-.. index:: rbtrees
-
-Introduction
-============
-
-The Red-Black Tree API is an interface to the SuperCore (score) rbtree
-implementation. Within RTEMS, red-black trees are used when a binary search
-tree is needed, including dynamic priority thread queues and non-contiguous
-heap memory. The Red-Black Tree API provided by RTEMS is:
-
-- build_id
-
-- ``rtems_rtems_rbtree_node`` - Red-Black Tree node embedded in another struct
-
-- ``rtems_rtems_rbtree_control`` - Red-Black Tree control node for an entire tree
-
-- ``rtems_rtems_rbtree_initialize`` - initialize the red-black tree with nodes
-
-- ``rtems_rtems_rbtree_initialize_empty`` - initialize the red-black tree as empty
-
-- ``rtems_rtems_rbtree_set_off_tree`` - Clear a node’s links
-
-- ``rtems_rtems_rbtree_root`` - Return the red-black tree’s root node
-
-- ``rtems_rtems_rbtree_min`` - Return the red-black tree’s minimum node
-
-- ``rtems_rtems_rbtree_max`` - Return the red-black tree’s maximum node
-
-- ``rtems_rtems_rbtree_left`` - Return a node’s left child node
-
-- ``rtems_rtems_rbtree_right`` - Return a node’s right child node
-
-- ``rtems_rtems_rbtree_parent`` - Return a node’s parent node
-
-- ``rtems_rtems_rbtree_are_nodes_equal`` - Are the node’s equal ?
-
-- ``rtems_rtems_rbtree_is_empty`` - Is the red-black tree empty ?
-
-- ``rtems_rtems_rbtree_is_min`` - Is the Node the minimum in the red-black tree ?
-
-- ``rtems_rtems_rbtree_is_max`` - Is the Node the maximum in the red-black tree ?
-
-- ``rtems_rtems_rbtree_is_root`` - Is the Node the root of the red-black tree ?
-
-- ``rtems_rtems_rbtree_find`` - Find the node with a matching key in the red-black tree
-
-- ``rtems_rtems_rbtree_predecessor`` - Return the in-order predecessor of a node.
-
-- ``rtems_rtems_rbtree_successor`` - Return the in-order successor of a node.
-
-- ``rtems_rtems_rbtree_extract`` - Remove the node from the red-black tree
-
-- ``rtems_rtems_rbtree_get_min`` - Remove the minimum node from the red-black tree
-
-- ``rtems_rtems_rbtree_get_max`` - Remove the maximum node from the red-black tree
-
-- ``rtems_rtems_rbtree_peek_min`` - Returns the minimum node from the red-black tree
-
-- ``rtems_rtems_rbtree_peek_max`` - Returns the maximum node from the red-black tree
-
-- ``rtems_rtems_rbtree_insert`` - Add the node to the red-black tree
-
-Background
-==========
-
-The Red-Black Trees API is a thin layer above the SuperCore Red-Black Trees
-implementation. A Red-Black Tree is defined by a control node with pointers to
-the root, minimum, and maximum nodes in the tree. Each node in the tree
-consists of a parent pointer, two children pointers, and a color attribute. A
-tree is parameterized as either unique, meaning identical keys are rejected, or
-not, in which case duplicate keys are allowed.
-
-Users must provide a comparison functor that gets passed to functions that need
-to compare nodes. In addition, no internal synchronization is offered within
-the red-black tree implementation, thus users must ensure at most one thread
-accesses a red-black tree instance at a time.
-
-Nodes
------
-
-A red-black tree is made up from nodes that orginate from a red-black tree control
-object. A node is of type ``rtems_rtems_rbtree_node``. The node
-is designed to be part of a user data structure. To obtain the encapsulating
-structure users can use the ``RTEMS_CONTAINER_OF`` macro.
-The node can be placed anywhere within the user’s structure and the macro will
-calculate the structure’s address from the node’s address.
-
-Controls
---------
-
-A red-black tree is rooted with a control object. Red-Black Tree control
-provide the user with access to the nodes on the red-black tree. The
-implementation does not require special checks for manipulating the root of the
-red-black tree. To accomplish this the``rtems_rtems_rbtree_control`` structure is treated as a``rtems_rtems_rbtree_node`` structure with a ``NULL`` parent
-and left child pointing to the root.
-
-Operations
-==========
-
-Examples for using the red-black trees
-can be found in the testsuites/sptests/sprbtree01/init.c file.
-
-Directives
-==========
-
-Documentation for the Red-Black Tree Directives
------------------------------------------------
-.. index:: rbtree doc
-
-Source documentation for the Red-Black Tree API can be found in the
-generated Doxygen output for cpukit/sapi.
-
-.. COMMENT: COPYRIGHT (c) 1988-2012.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Timespec Helpers
-################
-
-Introduction
-============
-
-The Timespec helpers manager provides directives to assist in manipulating
-instances of the POSIX ``struct timespec`` structure.
-
-The directives provided by the timespec helpers manager are:
-
-- ``rtems_timespec_set`` - Set timespec’s value
-
-- ``rtems_timespec_zero`` - Zero timespec’s value
-
-- ``rtems_timespec_is_valid`` - Check if timespec is valid
-
-- ``rtems_timespec_add_to`` - Add two timespecs
-
-- ``rtems_timespec_subtract`` - Subtract two timespecs
-
-- ``rtems_timespec_divide`` - Divide two timespecs
-
-- ``rtems_timespec_divide_by_integer`` - Divide timespec by integer
-
-- ``rtems_timespec_less_than`` - Less than operator
-
-- ``rtems_timespec_greater_than`` - Greater than operator
-
-- ``rtems_timespec_equal_to`` - Check if two timespecs are equal
-
-- ``rtems_timespec_get_seconds`` - Obtain seconds portion of timespec
-
-- ``rtems_timespec_get_nanoseconds`` - Obtain nanoseconds portion of timespec
-
-- ``rtems_timespec_to_ticks`` - Convert timespec to number of ticks
-
-- ``rtems_timespec_from_ticks`` - Convert ticks to timespec
-
-Background
-==========
-
-Time Storage Conventions
-------------------------
-
-Time can be stored in many ways. One of them is the ``struct timespec``
-format which is a structure that consists of the fields ``tv_sec``
-to represent seconds and ``tv_nsec`` to represent nanoseconds. The``struct timeval`` structure is simular and consists of seconds (stored
-in ``tv_sec``) and microseconds (stored in ``tv_usec``). Either``struct timespec`` or ``struct timeval`` can be used to represent
-elapsed time, time of executing some operations, or time of day.
-
-Operations
-==========
-
-Set and Obtain Timespec Value
------------------------------
-
-A user may write a specific time by passing the desired seconds and
-nanoseconds values and the destination ``struct timespec`` using the``rtems_timespec_set`` directive.
-
-The ``rtems_timespec_zero`` directive is used to zero the seconds
-and nanoseconds portions of a ``struct timespec`` instance.
-
-Users may obtain the seconds or nanoseconds portions of a ``struct
-timespec`` instance with the ``rtems_timespec_get_seconds`` or``rtems_timespec_get_nanoseconds`` methods, respectively.
-
-Timespec Math
--------------
-
-A user can perform multiple operations on ``struct timespec``
-instances. The helpers in this manager assist in adding, subtracting, and
-performing divison on ``struct timespec`` instances.
-
-- Adding two ``struct timespec`` can be done using the``rtems_timespec_add_to`` directive. This directive is used mainly
- to calculate total amount of time consumed by multiple operations.
-
-- The ``rtems_timespec_subtract`` is used to subtract two``struct timespecs`` instances and determine the elapsed time between
- those two points in time.
-
-- The ``rtems_timespec_divide`` is used to use to divide one``struct timespec`` instance by another. This calculates the percentage
- with a precision to three decimal points.
-
-- The ``rtems_timespec_divide_by_integer`` is used to divide a``struct timespec`` instance by an integer. It is commonly used in
- benchmark calculations to dividing duration by the number of iterations
- performed.
-
-Comparing struct timespec Instances
------------------------------------
-
-A user can compare two ``struct timespec`` instances using the``rtems_timespec_less_than``, ``rtems_timespec_greater_than``
-or ``rtems_timespec_equal_to`` routines.
-
-Conversions and Validity Check
-------------------------------
-
-Conversion to and from clock ticks may be performed by using the``rtems_timespec_to_ticks`` and ``rtems_timespec_from_ticks``
-directives.
-
-User can also check validity of timespec with``rtems_timespec_is_valid`` routine.
-
-Directives
-==========
-
-This section details the Timespec Helpers 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.
-
-TIMESPEC_SET - Set struct timespec Instance
--------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_timespec_set(
- struct timespec \*time,
- time_t seconds,
- uint32_t nanoseconds
- );
-
-.. index:: rtems_timespec_set
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This directive sets the ``struct timespec`` ``time`` value to the
-desired ``seconds`` and ``nanoseconds`` values.
-
-**NOTES:**
-
-This method does NOT check if ``nanoseconds`` is less than the
-maximum number of nanoseconds in a second.
-
-TIMESPEC_ZERO - Zero struct timespec Instance
----------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_timespec_zero(
- struct timespec \*time
- );
-
-.. index:: rtems_timespec_zero
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This routine sets the contents of the ``struct timespec`` instance``time`` to zero.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_IS_VALID - Check validity of a struct timespec instance
-----------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- bool rtems_timespec_is_valid(
- const struct timespec \*time
- );
-
-.. index:: rtems_timespec_is_valid
-
-**STATUS CODES:**
-
-This method returns ``true`` if the instance is valid, and ``false``
-otherwise.
-
-**DESCRIPTION:**
-
-This routine check validity of a ``struct timespec`` instance. It
-checks if the nanoseconds portion of the ``struct timespec`` instanceis
-in allowed range (less than the maximum number of nanoseconds per second).
-
-**NOTES:**
-
-TIMESPEC_ADD_TO - Add Two struct timespec Instances
----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- uint32_t rtems_timespec_add_to(
- struct timespec \*time,
- const struct timespec \*add
- );
-
-.. index:: rtems_timespec_add_to
-
-**STATUS CODES:**
-
-The method returns the number of seconds ``time`` increased by.
-
-**DESCRIPTION:**
-
-This routine adds two ``struct timespec`` instances. The second argument is added to the first. The parameter ``time`` is the base time to which the ``add`` parameter is added.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
-----------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_timespec_subtract(
- const struct timespec \*start,
- const struct timespec \*end,
- struct timespec \*result
- );
-
-.. index:: rtems_timespec_subtract
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This routine subtracts ``start`` from ``end`` saves the difference
-in ``result``. The primary use of this directive is to calculate
-elapsed time.
-
-**NOTES:**
-
-It is possible to subtract when ``end`` is less than ``start``
-and it produce negative ``result``. When doing this you should be
-careful and remember that only the seconds portion of a ``struct
-timespec`` instance is signed, which means that nanoseconds portion is
-always increasing. Due to that when your timespec has seconds = -1 and
-nanoseconds=500,000,000 it means that result is -0.5 second, NOT the
-expected -1.5!
-
-TIMESPEC_DIVIDE - Divide Two struct timespec Instances
-------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_timespec_divide(
- const struct timespec \*lhs,
- const struct timespec \*rhs,
- uint32_t \*ival_percentage,
- uint32_t \*fval_percentage
- );
-
-.. index:: rtems_timespec_divide
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This routine divides the ``struct timespec`` instance ``lhs`` by
-the ``struct timespec`` instance ``rhs``. The result is returned
-in the ``ival_percentage`` and ``fval_percentage``, representing
-the integer and fractional results of the division respectively.
-
-The ``ival_percentage`` is integer value of calculated percentage and ``fval_percentage`` is fractional part of calculated percentage.
-
-**NOTES:**
-
-The intended use is calculating percentges to three decimal points.
-
-When dividing by zero, this routine return both ``ival_percentage``
-and ``fval_percentage`` equal zero.
-
-The division is performed using exclusively integer operations.
-
-TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
-----------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int rtems_timespec_divide_by_integer(
- const struct timespec \*time,
- uint32_t iterations,
- struct timespec \*result
- );
-
-.. index:: rtems_timespec_divide_by_integer
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This routine divides the ``struct timespec`` instance ``time`` by the integer value ``iterations``.
-The result is saved in ``result``.
-
-**NOTES:**
-
-The expected use is to assist in benchmark calculations where you
-typically divide a duration (``time``) by a number of iterations what
-gives average time.
-
-TIMESPEC_LESS_THAN - Less than operator
----------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- bool rtems_timespec_less_than(
- const struct timespec \*lhs,
- const struct timespec \*rhs
- );
-
-.. index:: rtems_timespec_less_than
-
-**STATUS CODES:**
-
-This method returns ``struct true`` if ``lhs`` is less than``rhs`` and ``struct false`` otherwise.
-
-**DESCRIPTION:**
-
-This method is the less than operator for ``struct timespec`` instances. The first parameter is the left hand side and the second is the right hand side of the comparison.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_GREATER_THAN - Greater than operator
----------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- bool rtems_timespec_greater_than(
- const struct timespec \*_lhs,
- const struct timespec \*_rhs
- );
-
-.. index:: rtems_timespec_greater_than
-
-**STATUS CODES:**
-
-This method returns ``struct true`` if ``lhs`` is greater than``rhs`` and ``struct false`` otherwise.
-
-**DESCRIPTION:**
-
-This method is greater than operator for ``struct timespec`` instances.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_EQUAL_TO - Check equality of timespecs
------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- bool rtems_timespec_equal_to(
- const struct timespec \*lhs,
- const struct timespec \*rhs
- );
-
-.. index:: rtems_timespec_equal_to
-
-**STATUS CODES:**
-
-This method returns ``struct true`` if ``lhs`` is equal to``rhs`` and ``struct false`` otherwise.
-
-**DESCRIPTION:**
-
-This method is equality operator for ``struct timespec`` instances.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
-----------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- time_t rtems_timespec_get_seconds(
- struct timespec \*time
- );
-
-.. index:: rtems_timespec_get_seconds
-
-**STATUS CODES:**
-
-This method returns the seconds portion of the specified ``struct
-timespec`` instance.
-
-**DESCRIPTION:**
-
-This method returns the seconds portion of the specified ``struct timespec`` instance ``time``.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
-----------------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- uint32_t rtems_timespec_get_nanoseconds(
- struct timespec \*_time
- );
-
-.. index:: rtems_timespec_get_nanoseconds
-
-**STATUS CODES:**
-
-This method returns the nanoseconds portion of the specified ``struct
-timespec`` instance.
-
-**DESCRIPTION:**
-
-This method returns the nanoseconds portion of the specified timespec
-which is pointed by ``_time``.
-
-**NOTES:**
-
-TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
--------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- uint32_t rtems_timespec_to_ticks(
- const struct timespec \*time
- );
-
-.. index:: rtems_timespec_to_ticks
-
-**STATUS CODES:**
-
-This directive returns the number of ticks computed.
-
-**DESCRIPTION:**
-
-This directive converts the ``time`` timespec to the corresponding number of clock ticks.
-
-**NOTES:**
-
-NONE
-
-TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
----------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void rtems_timespec_from_ticks(
- uint32_t ticks,
- struct timespec \*time
- );
-
-.. index:: rtems_timespec_from_ticks
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-This routine converts the ``ticks`` to the corresponding ``struct timespec`` representation and stores it in ``time``.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: COPYRIGHT (c) 2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Constant Bandwidth Server Scheduler API
-#######################################
-
-.. index:: cbs
-
-Introduction
-============
-
-Unlike simple schedulers, the Constant Bandwidth Server (CBS) requires
-a special API for tasks to indicate their scheduling parameters.
-The directives provided by the CBS API are:
-
-- ``rtems_cbs_initialize`` - Initialize the CBS library
-
-- ``rtems_cbs_cleanup`` - Cleanup the CBS library
-
-- ``rtems_cbs_create_server`` - Create a new bandwidth server
-
-- ``rtems_cbs_attach_thread`` - Attach a thread to server
-
-- ``rtems_cbs_detach_thread`` - Detach a thread from server
-
-- ``rtems_cbs_destroy_server`` - Destroy a bandwidth server
-
-- ``rtems_cbs_get_server_id`` - Get an ID of a server
-
-- ``rtems_cbs_get_parameters`` - Get scheduling parameters of a server
-
-- ``rtems_cbs_set_parameters`` - Set scheduling parameters of a server
-
-- ``rtems_cbs_get_execution_time`` - Get elapsed execution time
-
-- ``rtems_cbs_get_remaining_budget`` - Get remainig execution time
-
-- ``rtems_cbs_get_approved_budget`` - Get scheduler approved execution time
-
-Background
-==========
-
-Constant Bandwidth Server Definitions
--------------------------------------
-.. index:: CBS parameters
-
-.. index:: rtems_cbs_parameters
-
-The Constant Bandwidth Server API enables tasks to communicate with
-the scheduler and indicate its scheduling parameters. The scheduler
-has to be set up first (by defining ``CONFIGURE_SCHEDULER_CBS`` macro).
-
-The difference to a plain EDF is the presence of servers.
-It is a budget aware extention of the EDF scheduler, therefore, tasks
-attached to servers behave in a similar way as with EDF unless they
-exceed their budget.
-
-The intention of servers is reservation of a certain computation
-time (budget) of the processor for all subsequent periods. The structure``rtems_cbs_parameters`` determines the behavior of
-a server. It contains ``deadline`` which is equal to period,
-and ``budget`` which is the time the server is allowed to
-spend on CPU per each period. The ratio between those two parameters
-yields the maximum percentage of the CPU the server can use
-(bandwidth). Moreover, thanks to this limitation the overall
-utilization of CPU is under control, and the sum of bandwidths
-of all servers in the system yields the overall reserved portion
-of processor. The rest is still available for ordinary tasks that
-are not attached to any server.
-
-In order to make the server effective to the executing tasks,
-tasks have to be attached to the servers. The``rtems_cbs_server_id`` is a type denoting an id of a server
-and ``rtems_id`` a type for id of tasks.
-
-Handling Periodic Tasks
------------------------
-.. index:: CBS periodic tasks
-
-Each task’s execution begins with a default background priority
-(see the chapter Scheduling Concepts to understand the concept of
-priorities in EDF). Once you decide the tasks should start periodic
-execution, you have two possibilities. Either you use only the Rate
-Monotonic manager which takes care of periodic behavior, or you declare
-deadline and budget using the CBS API in which case these properties
-are constant for all subsequent periods, unless you change them using
-the CBS API again. Task now only has to indicate and end of
-each period using ``rtems_rate_monotonic_period``.
-
-Registering a Callback Function
--------------------------------
-.. index:: CBS overrun handler
-
-In case tasks attached to servers are not aware of their execution time
-and happen to exceed it, the scheduler does not guarantee execution any
-more and pulls the priority of the task to background, which would
-possibly lead to immediate preemption (if there is at least one ready
-task with a higher pirority). However, the task is not blocked but a
-callback function is invoked. The callback function
-(``rtems_cbs_budget_overrun``) might be optionally registered upon
-a server creation (``rtems_cbs_create_server``).
-
-This enables the user to define what should happen in case of budget
-overrun. There is obviously no space for huge operations because the
-priority is down and not real time any more, however, you still can at
-least in release resources for other tasks, restart the task or log an
-error information. Since the routine is called directly from kernel,
-use ``printk()`` instead of ``printf()``.
-
-The calling convention of the callback function is:.. index:: rtems_asr
-
-.. code:: c
-
- void overrun_handler(
- rtems_cbs_server_id server_id
- );
-
-Limitations
------------
-.. index:: CBS limitations
-
-When using this scheduler you have to keep in mind several things:
-
-- it_limitations
-
-- In the current implementation it is possible to attach only
- a single task to each server.
-
-- If you have a task attached to a server and you voluntatily
- block it in the beginning of its execution, its priority will be
- probably pulled to background upon unblock, thus not guaranteed
- deadline any more. This is because you are effectively raising
- computation time of the task. When unbocking, you should be always
- sure that the ratio between remaining computation time and remaining
- deadline is not higher that the utilization you have agreed with the
- scheduler.
-
-Operations
-==========
-
-Setting up a server
--------------------
-
-The directive ``rtems_cbs_create_server`` is used to create a new
-server that is characterized by ``rtems_cbs_parameters``. You also
-might want to register the ``rtems_cbs_budget_overrun`` callback
-routine. After this step tasks can be attached to the server. The directive``rtems_cbs_set_parameters`` can change the scheduling parameters
-to avoid destroying and creating a new server again.
-
-Attaching Task to a Server
---------------------------
-
-If a task is attached to a server using ``rtems_cbs_attach_thread``,
-the task’s computation time per period is limited by the server and
-the deadline (period) of task is equal to deadline of the server which
-means if you conclude a period using ``rate_monotonic_period``,
-the length of next period is always determined by the server’s property.
-
-The task has a guaranteed bandwidth given by the server but should not
-exceed it, otherwise the priority is pulled to background until the
-start of next period and the ``rtems_cbs_budget_overrun`` callback
-function is invoked.
-
-When attaching a task to server, the preemptability flag of the task
-is raised, otherwise it would not be possible to control the execution
-of the task.
-
-Detaching Task from a Server
-----------------------------
-
-The directive ``rtems_cbs_detach_thread`` is just an inverse
-operation to the previous one, the task continues its execution with
-the initial priority.
-
-Preemptability of the task is restored to the initial value.
-
-Examples
---------
-
-The following example presents a simple common use of the API.
-
-You can see the initialization and cleanup call here, if there are
-multiple tasks in the system, it is obvious that the initialization
-should be called before creating the task.
-
-Notice also that in this case we decided to register an overrun handler,
-instead of which there could be ``NULL``. This handler just prints
-a message to terminal, what else may be done here depends on a specific
-application.
-
-During the periodic execution, remaining budget should be watched
-to avoid overrun.
-.. code:: c
-
- void overrun_handler (
- rtems_cbs_server_id server_id
- )
- {
- printk( "Budget overrun, fixing the task\\n" );
- return;
- }
- rtems_task Tasks_Periodic(
- rtems_task_argument argument
- )
- {
- rtems_id rmid;
- rtems_cbs_server_id server_id;
- rtems_cbs_parameters params;
- params.deadline = 10;
- params.budget = 4;
- rtems_cbs_initialize();
- rtems_cbs_create_server( &params, &overrun_handler, &server_id )
- rtems_cbs_attach_thread( server_id, SELF );
- rtems_rate_monotonic_create( argument, &rmid );
- while ( 1 ) {
- if (rtems_rate_monotonic_period(rmid, params.deadline)==RTEMS_TIMEOUT)
- break;
- /* Perform some periodic action \*/
- }
- rtems_rate_monotonic_delete( rmid );
- rtems_cbs_cleanup();
- exit( 1 );
- }
-
-Directives
-==========
-
-This section details the Constant Bandwidth Server’s directives.
-A subsection is dedicated to each of this manager’s directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-CBS_INITIALIZE - Initialize the CBS library
--------------------------------------------
-.. index:: initialize the CBS library
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_initialize
-
-.. code:: c
-
- int rtems_cbs_initialize( void );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful initialization
-``RTEMS_CBS_ERROR_NO_MEMORY`` - not enough memory for data
-
-**DESCRIPTION:**
-
-This routine initializes the library in terms of allocating necessary memory
-for the servers. In case not enough memory is available in the system,``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise``RTEMS_CBS_OK``.
-
-**NOTES:**
-
-Additional memory per each server is allocated upon invocation of``rtems_cbs_create_server``.
-
-Tasks in the system are not influenced, they still keep executing
-with their initial parameters.
-
-CBS_CLEANUP - Cleanup the CBS library
--------------------------------------
-.. index:: cleanup the CBS library
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_cleanup
-
-.. code:: c
-
- int rtems_cbs_cleanup( void );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - always successful
-
-**DESCRIPTION:**
-
-This routine detaches all tasks from their servers, destroys all servers
-and returns memory back to the system.
-
-**NOTES:**
-
-All tasks continue executing with their initial priorities.
-
-CBS_CREATE_SERVER - Create a new bandwidth server
--------------------------------------------------
-.. index:: create a new bandwidth server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_create_server
-
-.. code:: c
-
- int rtems_cbs_create_server (
- rtems_cbs_parameters \*params,
- rtems_cbs_budget_overrun budget_overrun_callback,
- rtems_cbs_server_id \*server_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successfully created
-``RTEMS_CBS_ERROR_NO_MEMORY`` - not enough memory for data
-``RTEMS_CBS_ERROR_FULL`` - maximum servers exceeded
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-
-**DESCRIPTION:**
-
-This routine prepares an instance of a constant bandwidth server.
-The input parameter ``rtems_cbs_parameters`` specifies scheduling
-parameters of the server (period and budget). If these are not valid,``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned.
-The ``budget_overrun_callback`` is an optional callback function, which is
-invoked in case the server’s budget within one period is exceeded.
-Output parameter ``server_id`` becomes an id of the newly created server.
-If there is not enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY``
-is returned. If the maximum server count in the system is exceeded,``RTEMS_CBS_ERROR_FULL`` is returned.
-
-**NOTES:**
-
-No task execution is being influenced so far.
-
-CBS_ATTACH_THREAD - Attach a thread to server
----------------------------------------------
-.. index:: attach a thread to server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_attach_thread
-
-.. code:: c
-
- int rtems_cbs_attach_thread (
- rtems_cbs_server_id server_id,
- rtems_id task_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successfully attached
-``RTEMS_CBS_ERROR_FULL`` - server maximum tasks exceeded
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-Attaches a task (``task_id``) to a server (``server_id``).
-The server has to be previously created. Now, the task starts
-to be scheduled according to the server parameters and not
-using initial priority. This implementation allows only one task
-per server, if the user tries to bind another task to the same
-server, ``RTEMS_CBS_ERROR_FULL`` is returned.
-
-**NOTES:**
-
-Tasks attached to servers become preemptible.
-
-CBS_DETACH_THREAD - Detach a thread from server
------------------------------------------------
-.. index:: detach a thread from server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_detach_thread
-
-.. code:: c
-
- int rtems_cbs_detach_thread (
- rtems_cbs_server_id server_id,
- rtems_id task_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successfully detached
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive detaches a thread from server. The task continues its
-execution with initial priority.
-
-**NOTES:**
-
-The server can be reused for any other task.
-
-CBS_DESTROY_SERVER - Destroy a bandwidth server
------------------------------------------------
-.. index:: destroy a bandwidth server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_destroy_server
-
-.. code:: c
-
- int rtems_cbs_destroy_server (
- rtems_cbs_server_id server_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successfully destroyed
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive destroys a server. If any task was attached to the server,
-the task is detached and continues its execution according to EDF rules
-with initial properties.
-
-**NOTES:**
-
-This again enables one more task to be created.
-
-CBS_GET_SERVER_ID - Get an ID of a server
------------------------------------------
-.. index:: get an ID of a server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_get_server_id
-
-.. code:: c
-
- int rtems_cbs_get_server_id (
- rtems_id task_id,
- rtems_cbs_server_id \*server_id
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive returns an id of server belonging to a given task.
-
-CBS_GET_PARAMETERS - Get scheduling parameters of a server
-----------------------------------------------------------
-.. index:: get scheduling parameters of a server
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_get_parameters
-
-.. code:: c
-
- rtems_cbs_get_parameters (
- rtems_cbs_server_id server_id,
- rtems_cbs_parameters \*params
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive returns a structure with current scheduling parameters
-of a given server (period and execution time).
-
-**NOTES:**
-
-It makes no difference if any task is assigned or not.
-
-CBS_SET_PARAMETERS - Set scheduling parameters
-----------------------------------------------
-.. index:: set scheduling parameters
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_set_parameters
-
-.. code:: c
-
- int rtems_cbs_set_parameters (
- rtems_cbs_server_id server_id,
- rtems_cbs_parameters \*params
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive sets new scheduling parameters to the server. This operation
-can be performed regardless of whether a task is assigned or not.
-If a task is assigned, the parameters become effective imediately, therefore it
-is recommended to apply the change between two subsequent periods.
-
-**NOTES:**
-
-There is an upper limit on both period and budget equal to (2^31)-1 ticks.
-
-CBS_GET_EXECUTION_TIME - Get elapsed execution time
----------------------------------------------------
-.. index:: get elapsed execution time
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_get_execution_time
-
-.. code:: c
-
- int rtems_cbs_get_execution_time (
- rtems_cbs_server_id server_id,
- time_t \*exec_time,
- time_t \*abs_time
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This routine returns consumed execution time (``exec_time``) of a server
-during the current period.
-
-**NOTES:**
-
-Absolute time (``abs_time``) not supported now.
-
-CBS_GET_REMAINING_BUDGET - Get remaining execution time
--------------------------------------------------------
-.. index:: get remaining execution time
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_get_remaining_budget
-
-.. code:: c
-
- int rtems_cbs_get_remaining_budget (
- rtems_cbs_server_id server_id,
- time_t \*remaining_budget
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive returns remaining execution time of a given server for
-current period.
-
-**NOTES:**
-
-If the execution time approaches zero, the assigned task should finish
-computations of the current period.
-
-CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time
----------------------------------------------------------------
-.. index:: get scheduler approved execution time
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_cbs_get_approved_budget
-
-.. code:: c
-
- int rtems_cbs_get_approved_budget (
- rtems_cbs_server_id server_id,
- time_t \*appr_budget
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_CBS_OK`` - successful
-``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
-``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
-
-**DESCRIPTION:**
-
-This directive returns server’s approved budget for subsequent periods.
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Directive Status Codes
-######################
-
-Introduction
-============
-
-*``RTEMS_SUCCESSFUL`` - successful completion*
-
-*``RTEMS_TASK_EXITTED`` - returned from a task*
-
-*``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured*
-
-*``RTEMS_INVALID_NAME`` - invalid object name*
-
-*``RTEMS_INVALID_ID`` - invalid object id*
-
-*``RTEMS_TOO_MANY`` - too many*
-
-*``RTEMS_TIMEOUT`` - timed out waiting*
-
-*``RTEMS_OBJECT_WAS_DELETED`` - object was deleted while waiting*
-
-*``RTEMS_INVALID_SIZE`` - invalid specified size*
-
-*``RTEMS_INVALID_ADDRESS`` - invalid address specified*
-
-*``RTEMS_INVALID_NUMBER`` - number was invalid*
-
-*``RTEMS_NOT_DEFINED`` - item not initialized*
-
-*``RTEMS_RESOURCE_IN_USE`` - resources outstanding*
-
-*``RTEMS_UNSATISFIED`` - request not satisfied*
-
-*``RTEMS_INCORRECT_STATE`` - task is in wrong state*
-
-*``RTEMS_ALREADY_SUSPENDED`` - task already in state*
-
-*``RTEMS_ILLEGAL_ON_SELF`` - illegal for calling task*
-
-*``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - illegal for remote object*
-
-*``RTEMS_CALLED_FROM_ISR`` - invalid environment*
-
-*``RTEMS_INVALID_PRIORITY`` - invalid task priority*
-
-*``RTEMS_INVALID_CLOCK`` - invalid time buffer*
-
-*``RTEMS_INVALID_NODE`` - invalid node id*
-
-*``RTEMS_NOT_CONFIGURED`` - directive not configured*
-
-*``RTEMS_NOT_OWNER_OF_RESOURCE`` - not owner of resource*
-
-*``RTEMS_NOT_IMPLEMENTED`` - directive not implemented*
-
-*``RTEMS_INTERNAL_ERROR`` - RTEMS inconsistency detected*
-
-*``RTEMS_NO_MEMORY`` - could not get enough memory*
-
-Directives
-==========
-
-STATUS_TEXT - Returns the enumeration name for a status code
-------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_status_text
-
-.. code:: c
-
- const char \*rtems_status_text(
- rtems_status_code code
- );
-
-**DIRECTIVE STATUS CODES**
-
-The status code enumeration name or "?" in case the status code is invalid.
-
-**DESCRIPTION:**
-
-Returns the enumeration name for the specified status code.
-
-.. COMMENT: Copyright 2015 embedded brains GmbH
-
-.. COMMENT: All rights reserved.
-
-Linker Sets
-###########
-
-.. index:: linkersets
-
-Introduction
-============
-
-Linker sets are a flexible means to create arrays of items out of a set of
-object files at link-time. For example its possible to define an item *I*
-of type *T* in object file *A* and an item *J* of type *T*
-in object file *B* to be a member of a linker set *S*. The linker
-will then collect these two items *I* and *J* and place them in
-consecutive memory locations, so that they can be accessed like a normal array
-defined in one object file. The size of a linker set is defined by its begin
-and end markers. A linker set may be empty. It should only contain items of
-the same type.
-
-The following macros are provided to create, populate and use linker sets.
-
-- ``RTEMS_LINKER_SET_BEGIN`` - Designator of the linker set begin marker
-
-- ``RTEMS_LINKER_SET_END`` - Designator of the linker set end marker
-
-- ``RTEMS_LINKER_SET_SIZE`` - The linker set size in characters
-
-- ``RTEMS_LINKER_ROSET_DECLARE`` - Declares a read-only linker set
-
-- ``RTEMS_LINKER_ROSET`` - Defines a read-only linker set
-
-- ``RTEMS_LINKER_ROSET_ITEM_DECLARE`` - Declares a read-only linker set item
-
-- ``RTEMS_LINKER_ROSET_ITEM_REFERENCE`` - References a read-only linker set item
-
-- ``RTEMS_LINKER_ROSET_ITEM`` - Defines a read-only linker set item
-
-- ``RTEMS_LINKER_ROSET_ITEM_ORDERED`` - Defines an ordered read-only linker set item
-
-- ``RTEMS_LINKER_RWSET_DECLARE`` - Declares a read-write linker set
-
-- ``RTEMS_LINKER_RWSET`` - Defines a read-write linker set
-
-- ``RTEMS_LINKER_RWSET_ITEM_DECLARE`` - Declares a read-write linker set item
-
-- ``RTEMS_LINKER_RWSET_ITEM_REFERENCE`` - References a read-write linker set item
-
-- ``RTEMS_LINKER_RWSET_ITEM`` - Defines a read-write linker set item
-
-- ``RTEMS_LINKER_RWSET_ITEM_ORDERED`` - Defines an ordered read-write linker set item
-
-Background
-==========
-
-Linker sets are used not only in RTEMS, but also for example in Linux, in
-FreeBSD, for the GNU C constructor extension and for global C++ constructors.
-They provide a space efficient and flexible means to initialize modules. A
-linker set consists of
-
-- dedicated input sections for the linker (e.g. ``.ctors`` and``.ctors.*`` in the case of global constructors),
-
-- a begin marker (e.g. provided by ``crtbegin.o``, and
-
-- an end marker (e.g. provided by ``ctrend.o``).
-
-A module may place a certain data item into the dedicated input section. The
-linker will collect all such data items in this section and creates a begin and
-end marker. The initialization code can then use the begin and end markers to
-find all the collected data items (e.g. pointers to initialization functions).
-
-In the linker command file of the GNU linker we need the following output
-section descriptions.
-.. code:: c
-
- /* To be placed in a read-only memory region \*/
- .rtemsroset : {
- KEEP (\*(SORT(.rtemsroset.*)))
- }
- /* To be placed in a read-write memory region \*/
- .rtemsrwset : {
- KEEP (\*(SORT(.rtemsrwset.*)))
- }
-
-The ``KEEP()`` ensures that a garbage collection by the linker will not
-discard the content of this section. This would normally be the case since the
-linker set items are not referenced directly. The ``SORT()`` directive
-sorts the input sections lexicographically. Please note the lexicographical
-order of the ``.begin``, ``.content`` and ``.end`` section name parts
-in the RTEMS linker sets macros which ensures that the position of the begin
-and end markers are right.
-
-So, what is the benefit of using linker sets to initialize modules? It can be
-used to initialize and include only those RTEMS managers and other components
-which are used by the application. For example, in case an application uses
-message queues, it must call ``rtems_message_queue_create()``. In the
-module implementing this function, we can place a linker set item and register
-the message queue handler constructor. Otherwise, in case the application does
-not use message queues, there will be no reference to the``rtems_message_queue_create()`` function and the constructor is not
-registered, thus nothing of the message queue handler will be in the final
-executable.
-
-For an example see test program :file:`sptests/splinkersets01`.
-
-Directives
-==========
-
-RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker
-------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_SET_BEGIN
-
-.. code:: c
-
- volatile type \*begin = RTEMS_LINKER_SET_BEGIN( set );
-
-**DESCRIPTION:**
-
-This macro generates the designator of the begin marker of the linker set
-identified by ``set``. The item at the begin marker address is the first
-member of the linker set if it exists, e.g. the linker set is not empty. A
-linker set is empty, if and only if the begin and end markers have the same
-address.
-The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set.
-
-RTEMS_LINKER_SET_END - Designator of the linker set end marker
---------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_SET_END
-
-.. code:: c
-
- volatile type \*end = RTEMS_LINKER_SET_END( set );
-
-**DESCRIPTION:**
-
-This macro generates the designator of the end marker of the linker set
-identified by ``set``. The item at the end marker address is not a member
-of the linker set. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set.
-
-RTEMS_LINKER_SET_SIZE - The linker set size in characters
----------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_SET_SIZE
-
-.. code:: c
-
- size_t size = RTEMS_LINKER_SET_SIZE( set );
-
-**DESCRIPTION:**
-
-This macro returns the size of the linker set identified by ``set`` in
-characters. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set.
-
-RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set
-------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_ROSET_DECLARE
-
-.. code:: c
-
- RTEMS_LINKER_ROSET_DECLARE( set, type );
-
-**DESCRIPTION:**
-
-This macro generates declarations for the begin and end markers of a read-only
-linker set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set.
-
-RTEMS_LINKER_ROSET - Defines a read-only linker set
----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_ROSET
-
-.. code:: c
-
- RTEMS_LINKER_ROSET( set, type );
-
-**DESCRIPTION:**
-
-This macro generates definitions for the begin and end markers of a read-only
-linker set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set.
-
-RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item
-----------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE
-
-.. code:: c
-
- RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item );
-
-**DESCRIPTION:**
-
-This macro generates a declaration of an item contained in the read-only linker
-set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set.
-
-RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item
---------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE
-
-.. code:: c
-
- RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item );
-
-**DESCRIPTION:**
-
-This macro generates a reference to an item contained in the read-only linker set
-identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set.
-
-RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item
--------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_ROSET_ITEM
-
-.. code:: c
-
- RTEMS_LINKER_ROSET_ITEM( set, type, item );
-
-**DESCRIPTION:**
-
-This macro generates a definition of an item contained in the read-only linker set
-identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set.
-
-RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item
-------------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED
-
-.. code:: c
-
- RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order );
-
-**DESCRIPTION:**
-
-This macro generates a definition of an ordered item contained in the read-only
-linker set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set.
-The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set. The ``order`` parameter must be a valid linker input section name part on
-which macro expansion is performed. The items are lexicographically ordered
-according to the ``order`` parameter within a linker set. Ordered items are
-placed before unordered items in the linker set.
-
-**NOTES:**
-
-To be resilient to typos in the order parameter, it is recommended to use the
-following construct in macros defining items for a particular linker set (see
-enum in ``XYZ_ITEM()``).
-.. code:: c
-
- #include <rtems/linkersets.h>
- typedef struct {
- int foo;
- } xyz_item;
- /* The XYZ-order defines \*/
- #define XYZ_ORDER_FIRST 0x00001000
- #define XYZ_ORDER_AND_SO_ON 0x00002000
- /* Defines an ordered XYZ-item \*/
- #define XYZ_ITEM( item, order ) \\
- enum { xyz_##item = order - order }; \\
- RTEMS_LINKER_ROSET_ITEM_ORDERED( \\
- xyz, const xyz_item \*, item, order \\
- ) = { &item }
- /* Example item \*/
- static const xyz_item some_item = { 123 };
- XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
-
-RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set
--------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_RWSET_DECLARE
-
-.. code:: c
-
- RTEMS_LINKER_RWSET_DECLARE( set, type );
-
-**DESCRIPTION:**
-
-This macro generates declarations for the begin and end markers of a read-write
-linker set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set.
-
-RTEMS_LINKER_RWSET - Defines a read-write linker set
-----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_RWSET
-
-.. code:: c
-
- RTEMS_LINKER_RWSET( set, type );
-
-**DESCRIPTION:**
-
-This macro generates definitions for the begin and end markers of a read-write
-linker set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set.
-
-RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item
------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE
-
-.. code:: c
-
- RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item );
-
-**DESCRIPTION:**
-
-This macro generates a declaration of an item contained in the read-write linker
-set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set.
-
-RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item
----------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE
-
-.. code:: c
-
- RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item );
-
-**DESCRIPTION:**
-
-This macro generates a reference to an item contained in the read-write linker set
-identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set.
-
-RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item
---------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_RWSET_ITEM
-
-.. code:: c
-
- RTEMS_LINKER_RWSET_ITEM( set, type, item );
-
-**DESCRIPTION:**
-
-This macro generates a definition of an item contained in the read-write linker set
-identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set.
-
-RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item
--------------------------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED
-
-.. code:: c
-
- RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order );
-
-**DESCRIPTION:**
-
-This macro generates a definition of an ordered item contained in the read-write
-linker set identified by ``set``. The ``set`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items. The type
-must be the same for all macro invocations of a particular linker set.
-The ``item`` parameter itself must be a valid C designator on which no macro
-expansion is performed. It uniquely identifies an item in the linker set. The ``order`` parameter must be a valid linker input section name part on
-which macro expansion is performed. The items are lexicographically ordered
-according to the ``order`` parameter within a linker set. Ordered items are
-placed before unordered items in the linker set.
-
-**NOTES:**
-
-To be resilient to typos in the order parameter, it is recommended to use the
-following construct in macros defining items for a particular linker set (see
-enum in ``XYZ_ITEM()``).
-.. code:: c
-
- #include <rtems/linkersets.h>
- typedef struct {
- int foo;
- } xyz_item;
- /* The XYZ-order defines \*/
- #define XYZ_ORDER_FIRST 0x00001000
- #define XYZ_ORDER_AND_SO_ON 0x00002000
- /* Defines an ordered XYZ-item \*/
- #define XYZ_ITEM( item, order ) \\
- enum { xyz_##item = order - order }; \\
- RTEMS_LINKER_RWSET_ITEM_ORDERED( \\
- xyz, const xyz_item \*, item, order \\
- ) = { &item }
- /* Example item \*/
- static const xyz_item some_item = { 123 };
- XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
-
-.. COMMENT: COPYRIGHT (c) 1989-2014.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Example Application
-###################
-
-.. code:: c
-
- /*
- * This file contains an example of a simple RTEMS
- * application. It instantiates the RTEMS Configuration
- * Information using confdef.h and contains two tasks:
- * a user initialization task and a simple task.
- \*/
- #include <rtems.h>
- rtems_task user_application(rtems_task_argument argument);
- rtems_task init_task(
- rtems_task_argument ignored
- )
- {
- rtems_id tid;
- rtems_status_code status;
- rtems_name name;
- name = rtems_build_name( 'A', 'P', 'P', '1' )
- status = rtems_task_create(
- name, 1, RTEMS_MINIMUM_STACK_SIZE,
- RTEMS_NO_PREEMPT, RTEMS_FLOATING_POINT, &tid
- );
- if ( status != RTEMS_STATUS_SUCCESSFUL ) {
- printf( "rtems_task_create failed with status of %d.\\n", status );
- exit( 1 );
- }
- status = rtems_task_start( tid, user_application, 0 );
- if ( status != RTEMS_STATUS_SUCCESSFUL ) {
- printf( "rtems_task_start 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 );
- }
- rtems_task user_application(rtems_task_argument argument)
- {
- /* application specific initialization goes here \*/
- while ( 1 ) { /* infinite loop \*/
- /* APPLICATION CODE GOES HERE
- *
- * This code will typically include at least one
- * directive which causes the calling task to
- * give up the processor.
- \*/
- }
- }
- /* The Console Driver supplies Standard I/O. \*/
- #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
- /* The Clock Driver supplies the clock tick. \*/
- #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
- #define CONFIGURE_MAXIMUM_TASKS 2
- #define CONFIGURE_INIT_TASK_NAME rtems_build_name( 'E', 'X', 'A', 'M' )
- #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
- #define CONFIGURE_INIT
- #include <rtems/confdefs.h>
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Glossary
-########
-
-:dfn:`active`
- A term used to describe an object
- which has been created by an application.
-
-:dfn:`aperiodic task`
- A task which must execute only at
- irregular intervals and has only a soft deadline.
-
-:dfn:`application`
- In this document, software which makes
- use of RTEMS.
-
-:dfn:`ASR`
- see Asynchronous Signal Routine.
-
-:dfn:`asynchronous`
- Not related in order or timing to
- other occurrences in the system.
-
-:dfn:`Asynchronous Signal Routine`
- Similar to a hardware
- interrupt except that it is associated with a task and is run in
- the context of a task. The directives provided by the signal
- manager are used to service signals.
-
-:dfn:`atomic operations`
- Atomic operations are defined in terms of *ISO/IEC 9899:2011*.
-
-:dfn:`awakened`
- A term used to describe a task that has
- been unblocked and may be scheduled to the CPU.
-
-:dfn:`big endian`
- A data representation scheme in which
- the bytes composing a numeric value are arranged such that the
- most significant byte is at the lowest address.
-
-:dfn:`bit-mapped`
- A data encoding scheme in which each bit
- in a variable is used to represent something different. This
- makes for compact data representation.
-
-:dfn:`block`
- A physically contiguous area of memory.
-
-:dfn:`blocked task`
- The task state entered by a task which has been previously started and cannot
- continue execution until the reason for waiting has been satisfied. Blocked
- tasks are not an element of the set of ready tasks of a scheduler instance.
-
-:dfn:`broadcast`
- To simultaneously send a message to a
- logical set of destinations.
-
-:dfn:`BSP`
- see Board Support Package.
-
-:dfn:`Board Support Package`
- A collection of device
- initialization and control routines specific to a particular
- type of board or collection of boards.
-
-:dfn:`buffer`
- A fixed length block of memory allocated
- from a partition.
-
-:dfn:`calling convention`
- The processor and compiler
- dependent rules which define the mechanism used to invoke
- subroutines in a high-level language. These rules define the
- passing of arguments, the call and return mechanism, and the
- register set which must be preserved.
-
-:dfn:`Central Processing Unit`
- This term is equivalent to
- the terms processor and microprocessor.
-
-:dfn:`chain`
- A data structure which allows for efficient
- dynamic addition and removal of elements. It differs from an
- array in that it is not limited to a predefined size.
-
-:dfn:`cluster`
- We have clustered scheduling in case the set of processors of a system is
- partitioned into non-empty pairwise disjoint subsets. These subsets are called:dfn:`clusters`. Clusters with a cardinality of one are partitions. Each
- cluster is owned by exactly one scheduler instance.
-
-:dfn:`coalesce`
- The process of merging adjacent holes into
- a single larger hole. Sometimes this process is referred to as
- garbage collection.
-
-:dfn:`Configuration Table`
- A table which contains
- information used to tailor RTEMS for a particular application.
-
-:dfn:`context`
- All of the processor registers and
- operating system data structures associated with a task.
-
-:dfn:`context switch`
- Alternate term for task switch.
- Taking control of the processor from one task and transferring
- it to another task.
-
-:dfn:`control block`
- A data structure used by the
- executive to define and control an object.
-
-:dfn:`core`
- When used in this manual, this term refers to
- the internal executive utility functions. In the interest of
- application portability, the core of the executive should not be
- used directly by applications.
-
-:dfn:`CPU`
- An acronym for Central Processing Unit.
-
-:dfn:`critical section`
- A section of code which must be
- executed indivisibly.
-
-:dfn:`CRT`
- An acronym for Cathode Ray Tube. Normally used
- in reference to the man-machine interface.
-
-:dfn:`deadline`
- A fixed time limit by which a task must
- have completed a set of actions. Beyond this point, the results
- are of reduced value and may even be considered useless or
- harmful.
-
-:dfn:`device`
- A peripheral used by the application that
- requires special operation software. See also device driver.
-
-:dfn:`device driver`
- Control software for special
- peripheral devices used by the application.
-
-:dfn:`directives`
- RTEMS’ provided routines that provide
- support mechanisms for real-time applications.
-
-:dfn:`dispatch`
- The act of loading a task’s context onto
- the CPU and transferring control of the CPU to that task.
-
-:dfn:`dormant`
- The state entered by a task after it is
- created and before it has been started.
-
-:dfn:`Device Driver Table`
- A table which contains the
- entry points for each of the configured device drivers.
-
-:dfn:`dual-ported`
- A term used to describe memory which
- can be accessed at two different addresses.
-
-:dfn:`embedded`
- An application that is delivered as a
- hidden part of a larger system. For example, the software in a
- fuel-injection control system is an embedded application found
- in many late-model automobiles.
-
-:dfn:`envelope`
- A buffer provided by the MPCI layer to
- RTEMS which is used to pass messages between nodes in a
- multiprocessor system. It typically contains routing
- information needed by the MPCI. The contents of an envelope are
- referred to as a packet.
-
-:dfn:`entry point`
- The address at which a function or task
- begins to execute. In C, the entry point of a function is the
- function’s name.
-
-:dfn:`events`
- A method for task communication and
- synchronization. The directives provided by the event manager
- are used to service events.
-
-:dfn:`exception`
- A synonym for interrupt.
-
-:dfn:`executing task`
- The task state entered by a task after it has been given control of the
- processor. On SMP configurations a task may be registered as executing on more
- than one processor for short time frames during task migration. Blocked tasks
- can be executing until they issue a thread dispatch.
-
-:dfn:`executive`
- In this document, this term is used to
- referred to RTEMS. Commonly, an executive is a small real-time
- operating system used in embedded systems.
-
-:dfn:`exported`
- An object known by all nodes in a
- multiprocessor system. An object created with the GLOBAL
- attribute will be exported.
-
-:dfn:`external address`
- The address used to access
- dual-ported memory by all the nodes in a system which do not own
- the memory.
-
-:dfn:`FIFO`
- An acronym for First In First Out.
-
-:dfn:`First In First Out`
- A discipline for manipulating entries in a data structure.
-
-:dfn:`floating point coprocessor`
- A component used in
- computer systems to enhance performance in mathematically
- intensive situations. It is typically viewed as a logical
- extension of the primary processor.
-
-:dfn:`freed`
- A resource that has been released by the
- application to RTEMS.
-
-:dfn:`Giant lock`
- The :dfn:`Giant lock` is a recursive SMP lock protecting most parts of the
- operating system state. Virtually every operating system service must acquire
- and release the Giant lock during its operation.
-
-:dfn:`global`
- An object that has been created with the
- GLOBAL attribute and exported to all nodes in a multiprocessor
- system.
-
-:dfn:`handler`
- The equivalent of a manager, except that it
- is internal to RTEMS and forms part of the core. A handler is a
- collection of routines which provide a related set of functions.
- For example, there is a handler used by RTEMS to manage all
- objects.
-
-:dfn:`hard real-time system`
- A real-time system in which a
- missed deadline causes the worked performed to have no value or
- to result in a catastrophic effect on the integrity of the
- system.
-
-:dfn:`heap`
- A data structure used to dynamically allocate
- and deallocate variable sized blocks of memory.
-
-:dfn:`heir task`
- A task is an :dfn:`heir` if it is registered as an heir in a processor of the
- system. A task can be the heir on at most one processor in the system. In
- case the executing and heir tasks differ on a processor and a thread dispatch
- is marked as necessary, then the next thread dispatch will make the heir task
- the executing task.
-
-:dfn:`heterogeneous`
- A multiprocessor computer system composed of dissimilar processors.
-
-:dfn:`homogeneous`
- A multiprocessor computer system composed of a single type of processor.
-
-:dfn:`ID`
- An RTEMS assigned identification tag used to
- access an active object.
-
-:dfn:`IDLE task`
- A special low priority task which assumes
- control of the CPU when no other task is able to execute.
-
-:dfn:`interface`
- A specification of the methodology used
- to connect multiple independent subsystems.
-
-:dfn:`internal address`
- The address used to access
- dual-ported memory by the node which owns the memory.
-
-:dfn:`interrupt`
- A hardware facility that causes the CPU
- to suspend execution, save its status, and transfer control to a
- specific location.
-
-:dfn:`interrupt level`
- A mask used to by the CPU to
- determine which pending interrupts should be serviced. If a
- pending interrupt is below the current interrupt level, then the
- CPU does not recognize that interrupt.
-
-:dfn:`Interrupt Service Routine`
- An ISR is invoked by the
- CPU to process a pending interrupt.
-
-:dfn:`I/O`
- An acronym for Input/Output.
-
-:dfn:`ISR`
- An acronym for Interrupt Service Routine.
-
-:dfn:`kernel`
- In this document, this term is used as a
- synonym for executive.
-
-:dfn:`list`
- A data structure which allows for dynamic
- addition and removal of entries. It is not statically limited
- to a particular size.
-
-:dfn:`little endian`
- A data representation scheme in which
- the bytes composing a numeric value are arranged such that the
- least significant byte is at the lowest address.
-
-:dfn:`local`
- An object which was created with the LOCAL
- attribute and is accessible only on the node it was created and
- resides upon. In a single processor configuration, all objects
- are local.
-
-:dfn:`local operation`
- The manipulation of an object which
- resides on the same node as the calling task.
-
-:dfn:`logical address`
- An address used by an application.
- In a system without memory management, logical addresses will
- equal physical addresses.
-
-:dfn:`loosely-coupled`
- A multiprocessor configuration
- where shared memory is not used for communication.
-
-:dfn:`major number`
- The index of a device driver in the
- Device Driver Table.
-
-:dfn:`manager`
- A group of related RTEMS’ directives which
- provide access and control over resources.
-
-:dfn:`memory pool`
- Used interchangeably with heap.
-
-:dfn:`message`
- A sixteen byte entity used to communicate
- between tasks. Messages are sent to message queues and stored
- in message buffers.
-
-:dfn:`message buffer`
- A block of memory used to store
- messages.
-
-:dfn:`message queue`
- An RTEMS object used to synchronize
- and communicate between tasks by transporting messages between
- sending and receiving tasks.
-
-:dfn:`Message Queue Control Block`
- A data structure associated with each message queue used by RTEMS
- to manage that message queue.
-
-:dfn:`minor number`
- A numeric value passed to a device
- driver, the exact usage of which is driver dependent.
-
-:dfn:`mode`
- An entry in a task’s control block that is
- used to determine if the task allows preemption, timeslicing,
- processing of signals, and the interrupt disable level used by
- the task.
-
-:dfn:`MPCI`
- An acronym for Multiprocessor Communications
- Interface Layer.
-
-:dfn:`multiprocessing`
- The simultaneous execution of two
- or more processes by a multiple processor computer system.
-
-:dfn:`multiprocessor`
- A computer with multiple CPUs
- available for executing applications.
-
-:dfn:`Multiprocessor Communications Interface Layer`
- A set
- of user-provided routines which enable the nodes in a
- multiprocessor system to communicate with one another.
-
-:dfn:`Multiprocessor Configuration Table`
- The data structure defining the characteristics of the multiprocessor
- target system with which RTEMS will communicate.
-
-:dfn:`multitasking`
- The alternation of execution amongst a
- group of processes on a single CPU. A scheduling algorithm is
- used to determine which process executes at which time.
-
-:dfn:`mutual exclusion`
- A term used to describe the act of
- preventing other tasks from accessing a resource simultaneously.
-
-:dfn:`nested`
- A term used to describe an ASR that occurs
- during another ASR or an ISR that occurs during another ISR.
-
-:dfn:`node`
- A term used to reference a processor running
- RTEMS in a multiprocessor system.
-
-:dfn:`non-existent`
- The state occupied by an uncreated or
- deleted task.
-
-:dfn:`numeric coprocessor`
- A component used in computer
- systems to enhance performance in mathematically intensive
- situations. It is typically viewed as a logical extension of
- the primary processor.
-
-:dfn:`object`
- In this document, this term is used to refer
- collectively to tasks, timers, message queues, partitions,
- regions, semaphores, ports, and rate monotonic periods. All
- RTEMS objects have IDs and user-assigned names.
-
-:dfn:`object-oriented`
- A term used to describe systems
- with common mechanisms for utilizing a variety of entities.
- Object-oriented systems shield the application from
- implementation details.
-
-:dfn:`operating system`
- The software which controls all
- the computer’s resources and provides the base upon which
- application programs can be written.
-
-:dfn:`overhead`
- The portion of the CPUs processing power
- consumed by the operating system.
-
-:dfn:`packet`
- A buffer which contains the messages passed
- between nodes in a multiprocessor system. A packet is the
- contents of an envelope.
-
-:dfn:`partition`
- An RTEMS object which is used to allocate
- and deallocate fixed size blocks of memory from an dynamically
- specified area of memory.
-
-:dfn:`partition`
- Clusters with a cardinality of one are :dfn:`partitions`.
-
-:dfn:`Partition Control Block`
- A data structure associated
- with each partition used by RTEMS to manage that partition.
-
-:dfn:`pending`
- A term used to describe a task blocked
- waiting for an event, message, semaphore, or signal.
-
-:dfn:`periodic task`
- A task which must execute at regular
- intervals and comply with a hard deadline.
-
-:dfn:`physical address`
- The actual hardware address of a
- resource.
-
-:dfn:`poll`
- A mechanism used to determine if an event has
- occurred by periodically checking for a particular status.
- Typical events include arrival of data, completion of an action,
- and errors.
-
-:dfn:`pool`
- A collection from which resources are
- allocated.
-
-:dfn:`portability`
- A term used to describe the ease with
- which software can be rehosted on another computer.
-
-:dfn:`posting`
- The act of sending an event, message,
- semaphore, or signal to a task.
-
-:dfn:`preempt`
- The act of forcing a task to relinquish the
- processor and dispatching to another task.
-
-:dfn:`priority`
- A mechanism used to represent the relative
- importance of an element in a set of items. RTEMS uses priority
- to determine which task should execute.
-
-:dfn:`priority boosting`
- A simple approach to extend the priority inheritance protocol for clustered
- scheduling is :dfn:`priority boosting`. In case a mutex is owned by a task of
- another cluster, then the priority of the owner task is raised to an
- artificially high priority, the pseudo-interrupt priority.
-
-:dfn:`priority inheritance`
- 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. This avoids the problem of priority
- inversion.
-
-:dfn:`priority inversion`
- A form of indefinite
- postponement which occurs when a high priority tasks requests
- access to shared resource currently allocated to low priority
- task. The high priority task must block until the low priority
- task releases the resource.
-
-:dfn:`processor utilization`
- The percentage of processor
- time used by a task or a set of tasks.
-
-:dfn:`proxy`
- An RTEMS control structure used to represent,
- on a remote node, a task which must block as part of a remote
- operation.
-
-:dfn:`Proxy Control Block`
- A data structure associated
- with each proxy used by RTEMS to manage that proxy.
-
-:dfn:`PTCB`
- An acronym for Partition Control Block.
-
-:dfn:`PXCB`
- An acronym for Proxy Control Block.
-
-:dfn:`quantum`
- The application defined unit of time in
- which the processor is allocated.
-
-:dfn:`queue`
- Alternate term for message queue.
-
-:dfn:`QCB`
- An acronym for Message Queue Control Block.
-
-:dfn:`ready task`
- A task occupies this state when it is available to be given control of a
- processor. A ready task has no processor assigned. The scheduler decided that
- other tasks are currently more important. A task that is ready to execute and
- has a processor assigned is called scheduled.
-
-:dfn:`real-time`
- A term used to describe systems which are
- characterized by requiring deterministic response times to
- external stimuli. The external stimuli require that the
- response occur at a precise time or the response is incorrect.
-
-:dfn:`reentrant`
- A term used to describe routines which do
- not modify themselves or global variables.
-
-:dfn:`region`
- An RTEMS object which is used to allocate
- and deallocate variable size blocks of memory from a dynamically
- specified area of memory.
-
-:dfn:`Region Control Block`
- A data structure associated
- with each region used by RTEMS to manage that region.
-
-:dfn:`registers`
- Registers are locations physically
- located within a component, typically used for device control or
- general purpose storage.
-
-:dfn:`remote`
- Any object that does not reside on the local
- node.
-
-:dfn:`remote operation`
- The manipulation of an object
- which does not reside on the same node as the calling task.
-
-:dfn:`return code`
- Also known as error code or return
- value.
-
-:dfn:`resource`
- A hardware or software entity to which
- access must be controlled.
-
-:dfn:`resume`
- Removing a task from the suspend state. If
- the task’s state is ready following a call to the ``rtems_task_resume``
- directive, then the task is available for scheduling.
-
-:dfn:`return code`
- A value returned by RTEMS directives to
- indicate the completion status of the directive.
-
-:dfn:`RNCB`
- An acronym for Region Control Block.
-
-:dfn:`round-robin`
- A task scheduling discipline in which
- tasks of equal priority are executed in the order in which they
- are made ready.
-
-:dfn:`RS-232`
- A standard for serial communications.
-
-:dfn:`running`
- The state of a rate monotonic timer while
- it is being used to delineate a period. The timer exits this
- state by either expiring or being canceled.
-
-:dfn:`schedulable`
- A set of tasks which can be guaranteed
- to meet their deadlines based upon a specific scheduling
- algorithm.
-
-:dfn:`schedule`
- The process of choosing which task should
- next enter the executing state.
-
-:dfn:`scheduled task`
- A task is :dfn:`scheduled` if it is allowed to execute and has a processor
- assigned. Such a task executes currently on a processor or is about to start
- execution. A task about to start execution it is an heir task on exactly one
- processor in the system.
-
-:dfn:`scheduler`
- A :dfn:`scheduler` or :dfn:`scheduling algorithm` allocates processors to a
- subset of its set of ready tasks. So it manages access to the processor
- resource. Various algorithms exist to choose the tasks allowed to use a
- processor out of the set of ready tasks. One method is to assign each task a
- priority number and assign the tasks with the lowest priority number to one
- processor of the set of processors owned by a scheduler instance.
-
-:dfn:`scheduler instance`
- A :dfn:`scheduler instance` is a scheduling algorithm with a corresponding
- context to store its internal state. Each processor in the system is owned by
- at most one scheduler instance. The processor to scheduler instance assignment
- is determined at application configuration time. See `Configuring a System`_.
-
-:dfn:`segments`
- Variable sized memory blocks allocated
- from a region.
-
-:dfn:`semaphore`
- An RTEMS object which is used to
- synchronize tasks and provide mutually exclusive access to
- resources.
-
-:dfn:`Semaphore Control Block`
- A data structure associated
- with each semaphore used by RTEMS to manage that semaphore.
-
-:dfn:`shared memory`
- Memory which is accessible by
- multiple nodes in a multiprocessor system.
-
-:dfn:`signal`
- An RTEMS provided mechanism to communicate
- asynchronously with a task. Upon reception of a signal, the ASR
- of the receiving task will be invoked.
-
-:dfn:`signal set`
- A thirty-two bit entity which is used to
- represent a task’s collection of pending signals and the signals
- sent to a task.
-
-:dfn:`SMCB`
- An acronym for Semaphore Control Block.
-
-:dfn:`SMP locks`
- The :dfn:`SMP locks` ensure mutual exclusion on the lowest level and are a
- replacement for the sections of disabled interrupts. Interrupts are usually
- disabled while holding an SMP lock. They are implemented using atomic
- operations. Currently a ticket lock is used in RTEMS.
-
-:dfn:`SMP barriers`
- The :dfn:`SMP barriers` ensure that a defined set of independent threads of
- execution on a set of processors reaches a common synchronization point in
- time. They are implemented using atomic operations. Currently a sense barrier
- is used in RTEMS.
-
-:dfn:`soft real-time system`
- A real-time system in which a
- missed deadline does not compromise the integrity of the system.
-
-:dfn:`sporadic task`
- A task which executes at irregular
- intervals and must comply with a hard deadline. A minimum
- period of time between successive iterations of the task can be
- guaranteed.
-
-:dfn:`stack`
- A data structure that is managed using a Last
- In First Out (LIFO) discipline. Each task has a stack
- associated with it which is used to store return information
- and local variables.
-
-:dfn:`status code`
- Also known as error code or return
- value.
-
-:dfn:`suspend`
- A term used to describe a task that is not
- competing for the CPU because it has had a ``rtems_task_suspend`` directive.
-
-:dfn:`synchronous`
- Related in order or timing to other
- occurrences in the system.
-
-:dfn:`system call`
- In this document, this is used as an
- alternate term for directive.
-
-:dfn:`target`
- The system on which the application will
- ultimately execute.
-
-:dfn:`task`
- A logically complete thread of execution. It consists normally of a set of
- registers and a stack. The terms :dfn:`task` and :dfn:`thread` are synonym in
- RTEMS. The scheduler assigns processors to a subset of the ready tasks.
-
-:dfn:`Task Control Block`
- A data structure associated with
- each task used by RTEMS to manage that task.
-
-:dfn:`task migration`
- :dfn:`Task migration` happens in case a task stops execution on one processor
- and resumes execution on another processor.
-
-:dfn:`task processor affinity`
- The set of processors on which a task is allowed to execute.
-
-:dfn:`task switch`
- Alternate terminology for context
- switch. Taking control of the processor from one task and given
- to another.
-
-:dfn:`TCB`
- An acronym for Task Control Block.
-
-:dfn:`thread dispatch`
- The :dfn:`thread dispatch` transfers control of the processor from the currently
- executing thread to the heir thread of the processor.
-
-:dfn:`tick`
- The basic unit of time used by RTEMS. It is a
- user-configurable number of microseconds. The current tick
- expires when the ``rtems_clock_tick``
- directive is invoked.
-
-:dfn:`tightly-coupled`
- A multiprocessor configuration
- system which communicates via shared memory.
-
-:dfn:`timeout`
- An argument provided to a number of
- directives which determines the maximum length of time an
- application task is willing to wait to acquire the resource if
- it is not immediately available.
-
-:dfn:`timer`
- An RTEMS object used to invoke subprograms at
- a later time.
-
-:dfn:`Timer Control Block`
- A data structure associated
- with each timer used by RTEMS to manage that timer.
-
-:dfn:`timeslicing`
- A task scheduling discipline in which
- tasks of equal priority are executed for a specific period of
- time before being preempted by another task.
-
-:dfn:`timeslice`
- The application defined unit of time in
- which the processor is allocated.
-
-:dfn:`TMCB`
- An acronym for Timer Control Block.
-
-:dfn:`transient overload`
- A temporary rise in system
- activity which may cause deadlines to be missed. Rate Monotonic
- Scheduling can be used to determine if all deadlines will be met
- under transient overload.
-
-:dfn:`user extensions`
- Software routines provided by the
- application to enhance the functionality of RTEMS.
-
-:dfn:`User Extension Table`
- A table which contains the
- entry points for each user extensions.
-
-:dfn:`User Initialization Tasks Table`
- A table which
- contains the information needed to create and start each of the
- user initialization tasks.
-
-:dfn:`user-provided`
- Alternate term for user-supplied.
- This term is used to designate any software routines which must
- be written by the application designer.
-
-:dfn:`user-supplied`
- Alternate term for user-provided.
- This term is used to designate any software routines which must
- be written by the application designer.
-
-:dfn:`vector`
- Memory pointers used by the processor to
- fetch the address of routines which will handle various
- exceptions and interrupts.
-
-:dfn:`wait queue`
- The list of tasks blocked pending the
- release of a particular resource. Message queues, regions, and
- semaphores have a wait queue associated with them.
-
-:dfn:`yield`
- When a task voluntarily releases control of the processor.
-
-Command and Variable Index
-##########################
-
-.. COMMENT: There are currently no Command and Variable Index entries.
-
-Concept Index
-#############
-
-.. COMMENT: There are currently no Concept Index entries.
-
diff --git a/cpu_supplement/cpu_supplement_old_reference_only.rst b/cpu_supplement/cpu_supplement_old_reference_only.rst
deleted file mode 100644
index afad822..0000000
--- a/cpu_supplement/cpu_supplement_old_reference_only.rst
+++ /dev/null
@@ -1,4762 +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 CPU Supplement
-
-.. 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 RTEMS CPU Architecture Supplement
-
-=================================
-RTEMS CPU Architecture Supplement
-=================================
-
-.. 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 CPU Architecture Supplement
-#################################
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Preface
-#######
-
-The Real Time Executive for Multiprocessor Systems
-(RTEMS) is designed to be portable across multiple processor
-architectures. However, the nature of real-time systems makes
-it essential that the application designer understand certain
-processor dependent implementation details. These processor
-dependencies include calling convention, board support package
-issues, interrupt processing, exact RTEMS memory requirements,
-performance data, header files, and the assembly language
-interface to the executive.
-
-Each architecture represents a CPU family and usually there are
-a wide variety of CPU models within it. These models share a
-common Instruction Set Architecture (ISA) which often varies
-based upon some well-defined rules. There are often
-multiple implementations of the ISA and these may be from
-one or multiple vendors.
-
-On top of variations in the ISA, there may also be variations
-which occur when a CPU core implementation is combined with
-a set of peripherals to form a system on chip. For example,
-there are many ARM CPU models from numerous semiconductor
-vendors and a wide variety of peripherals. But at the
-ISA level, they share a common compatibility.
-
-RTEMS depends upon this core similarity across the CPU models
-and leverages that to minimize the source code that is specific
-to any particular CPU core implementation or CPU model.
-
-This manual is separate and distinct from the RTEMS Porting
-Guide. That manual is a guide on porting RTEMS to a new
-architecture. This manual is focused on the more mundane
-CPU architecture specific issues that may impact
-application development. For example, if you need to write
-a subroutine in assembly language, it is critical to understand
-the calling conventions for the target architecture.
-
-The first chapter in this manual describes these issues
-in general terms. In a sense, it is posing the questions
-one should be aware may need to be answered and understood
-when porting an RTEMS application to a new architecture.
-Each subsequent chapter gives the answers to those questions
-for a particular CPU architecture.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Port Specific Information
-#########################
-
-This chaper provides a general description of the type of
-architecture specific information which is in each of
-the architecture specific chapters that follow. The outline
-of this chapter is identical to that of the architecture
-specific chapters.
-
-In each of the architecture specific chapters, this
-introductory section will provide an overview of the
-architecture
-
-**Architecture Documents**
-
-In each of the architecture specific chapters, this
-section will provide pointers on where to obtain
-documentation.
-
-CPU Model Dependent Features
-============================
-
-Microprocessors are generally classified into families with a variety of
-CPU models or implementations within that family. Within a processor
-family, there is a high level of binary compatibility. This family
-may be based on either an architectural specification or on maintaining
-compatibility with a popular processor. Recent microprocessor families
-such as the SPARC or PowerPC are based on an architectural specification
-which is independent or any particular CPU model or implementation.
-Older families such as the Motorola 68000 and the Intel x86 evolved as the
-manufacturer strived to produce higher performance processor models which
-maintained binary compatibility with older models.
-
-RTEMS takes advantage of the similarity of the various models within a
-CPU family. Although the models do vary in significant ways, the high
-level of compatibility makes it possible to share the bulk of the CPU
-dependent executive code across the entire family. Each processor family
-supported by RTEMS has a list of features which vary between CPU models
-within a family. For example, the most common model dependent feature
-regardless of CPU family is the presence or absence of a floating point
-unit or coprocessor. When defining the list of features present on a
-particular CPU model, one simply notes that floating point hardware
-is or is not present and defines a single constant appropriately.
-Conditional compilation is utilized to include the appropriate source
-code for this CPU model’s feature set. It is important to note that
-this means that RTEMS is thus compiled using the appropriate feature set
-and compilation flags optimal for this CPU model used. The alternative
-would be to generate a binary which would execute on all family members
-using only the features which were always present.
-
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/CPU/rtems/score/cpu.h`` based upon the GNU tools
-multilib variant that is appropriate for the particular CPU model defined
-on the compilation command line.
-
-In each of the architecture specific chapters, this section presents
-the set of features which vary across various implementations of the
-architecture that may be of importance to RTEMS application developers.
-
-The subsections will vary amongst the target architecture chapters as
-the specific features may vary. However, each port will include a few
-common features such as the CPU Model Name and presence of a hardware
-Floating Point Unit. The common features are described here.
-
-CPU Model Name
---------------
-
-The macro ``CPU_MODEL_NAME`` is a string which designates
-the name of this CPU model. For example, for the MC68020
-processor model from the m68k architecture, this macro
-is set to the string "mc68020".
-
-Floating Point Unit
--------------------
-
-In most architectures, the presence of a floating point unit is an option.
-It does not matter whether the hardware floating point support is
-incorporated on-chip or is an external coprocessor as long as it
-appears an FPU per the ISA. However, if a hardware FPU is not present,
-it is possible that the floating point emulation library for this
-CPU is not reentrant and thus context switched by RTEMS.
-
-RTEMS provides two feature macros to indicate the FPU configuration:
-
-- CPU_HARDWARE_FP
- is set to TRUE to indicate that a hardware FPU is present.
-
-- CPU_SOFTWARE_FP
- is set to TRUE to indicate that a hardware FPU is not present and that
- the FP software emulation will be context switched.
-
-Multilibs
-=========
-
-Newlib and GCC provide several target libraries like the :file:`libc.a`,:file:`libm.a` and :file:`libgcc.a`. These libraries are artifacts of the GCC
-build process. Newlib is built together with GCC. To provide optimal support
-for various chip derivatives and instruction set revisions multiple variants of
-these libraries are available for each architecture. For example one set may
-use software floating point support and another set may use hardware floating
-point instructions. These sets of libraries are called *multilibs*. Each
-library set corresponds to an application binary interface (ABI) and
-instruction set.
-
-A multilib variant can be usually detected via built-in compiler defines at
-compile-time. This mechanism is used by RTEMS to select for example the
-context switch support for a particular BSP. The built-in compiler defines
-corresponding to multilibs are the only architecture specific defines allowed
-in the ``cpukit`` area of the RTEMS sources.
-
-Invoking the GCC with the ``-print-multi-lib`` option lists the available
-multilibs. Each line of the output describes one multilib variant. The
-default variant is denoted by ``.`` which is selected when no or
-contradicting GCC machine options are selected. The multilib selection for a
-target is specified by target makefile fragments (see file :file:`t-rtems` in
-the GCC sources and section`The Target Makefile Fragment <https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment>`_
-in the `GCC Internals Manual <https://gcc.gnu.org/onlinedocs/gccint/>`_.
-
-Calling Conventions
-===================
-
-Each high-level language compiler generates subroutine entry and exit
-code based upon a set of rules known as the compiler’s calling convention.
-These rules address the following issues:
-
-- register preservation and usage
-
-- parameter passing
-
-- call and return mechanism
-
-A compiler’s calling convention is of importance when
-interfacing to subroutines written in another language either
-assembly or high-level. Even when the high-level language and
-target processor are the same, different compilers may use
-different calling conventions. As a result, calling conventions
-are both processor and compiler dependent.
-
-Calling Mechanism
------------------
-
-In each of the architecture specific chapters, this subsection will
-describe the instruction(s) used to perform a *normal* subroutine
-invocation. All RTEMS directives are invoked as *normal* C language
-functions so it is important to the user application to understand the
-call and return mechanism.
-
-Register Usage
---------------
-
-In each of the architecture specific chapters, this subsection will
-detail the set of registers which are *NOT* preserved across subroutine
-invocations. The registers which are not preserved are assumed to be
-available for use as scratch registers. Therefore, the contents of these
-registers should not be assumed upon return from any RTEMS directive.
-
-In some architectures, there may be a set of registers made available
-automatically as a side-effect of the subroutine invocation
-mechanism.
-
-Parameter Passing
------------------
-
-In each of the architecture specific chapters, this subsection will
-describe the mechanism by which the parameters or arguments are passed
-by the caller to a subroutine. In some architectures, all parameters
-are passed on the stack while in others some are passed in registers.
-
-User-Provided Routines
-----------------------
-
-All user-provided routines invoked by RTEMS, such as
-user extensions, device drivers, and MPCI routines, must also
-adhere to these calling conventions.
-
-Memory Model
-============
-
-A processor may support any combination of memory
-models ranging from pure physical addressing to complex demand
-paged virtual memory systems. RTEMS supports a flat memory
-model which ranges contiguously over the processor’s allowable
-address space. RTEMS does not support segmentation or virtual
-memory of any kind. The appropriate memory model for RTEMS
-provided by the targeted processor and related characteristics
-of that model are described in this chapter.
-
-Flat Memory Model
------------------
-
-Most RTEMS target processors can be initialized to support a flat address
-space. Although the size of addresses varies between architectures, on
-most RTEMS targets, an address is 32-bits wide which defines addresses
-ranging from 0x00000000 to 0xFFFFFFFF (4 gigabytes). Each address is
-represented by a 32-bit value and is byte addressable. The address may be
-used to reference a single byte, word (2-bytes), or long word (4 bytes).
-Memory accesses within this address space may be performed in little or
-big endian fashion.
-
-On smaller CPU architectures supported by RTEMS, the address space
-may only be 20 or 24 bits wide.
-
-If the CPU model has support for virtual memory or segmentation, it is
-the responsibility of the Board Support Package (BSP) to initialize the
-MMU hardware to perform address translations which correspond to flat
-memory model.
-
-In each of the architecture specific chapters, this subsection will
-describe any architecture characteristics that differ from this general
-description.
-
-Interrupt Processing
-====================
-
-Different types of processors respond to the occurrence of an interrupt
-in its own unique fashion. In addition, each processor type provides
-a control mechanism to allow for the proper handling of an interrupt.
-The processor dependent response to the interrupt modifies the current
-execution state and results in a change in the execution stream. Most
-processors require that an interrupt handler utilize some special control
-mechanisms to return to the normal processing stream. Although RTEMS
-hides many of the processor dependent details of interrupt processing,
-it is important to understand how the RTEMS interrupt manager is mapped
-onto the processor’s unique architecture.
-
-RTEMS supports a dedicated interrupt stack for all architectures.
-On architectures with hardware support for a dedicated interrupt stack,
-it will be initialized such that when an interrupt occurs, the processor
-automatically switches to this dedicated stack. On architectures without
-hardware support for a dedicated interrupt stack which is separate from
-those of the tasks, RTEMS will support switching to a dedicated stack
-for interrupt processing.
-
-Without a dedicated interrupt stack, every task in
-the system MUST have enough stack space to accommodate the worst
-case stack usage of that particular task and the interrupt
-service routines COMBINED. By supporting a dedicated interrupt
-stack, RTEMS significantly lowers the stack requirements for
-each task.
-
-A nested interrupt is processed similarly with the exception that since
-the CPU is already executing on the interrupt stack, there is no need
-to switch to the interrupt stack.
-
-In some configurations, RTEMS allocates the interrupt stack from the
-Workspace Area. The amount of memory allocated for the interrupt stack
-is user configured and based upon the ``confdefs.h`` parameter``CONFIGURE_INTERRUPT_STACK_SIZE``. This parameter is described
-in detail in the Configuring a System chapter of the User’s Guide.
-On configurations in which RTEMS allocates the interrupt stack, during
-the initialization process, RTEMS will also install its interrupt stack.
-In other configurations, the interrupt stack is allocated and installed
-by the Board Support Package (BSP).
-
-In each of the architecture specific chapters, this section discesses
-the interrupt response and control mechanisms of the architecture as
-they pertain to RTEMS.
-
-Vectoring of an Interrupt Handler
----------------------------------
-
-In each of the architecture specific chapters, this subsection will
-describe the architecture specific details of the interrupt vectoring
-process. In particular, it should include a description of the
-Interrupt Stack Frame (ISF).
-
-Interrupt Levels
-----------------
-
-In each of the architecture specific chapters, this subsection will
-describe how the interrupt levels available on this particular architecture
-are mapped onto the 255 reserved in the task mode. The interrupt level
-value of zero (0) should always mean that interrupts are enabled.
-
-Any use of an interrupt level that is is not undefined on a particular
-architecture may result in behavior that is unpredictable.
-
-Disabling of Interrupts by RTEMS
---------------------------------
-
-During the execution of directive calls, critical sections of code may
-be executed. When these sections are encountered, RTEMS disables all
-external interrupts before the execution of this section and restores
-them to the previous level upon completion of the section. RTEMS has
-been optimized to ensure that interrupts are disabled for the shortest
-number of instructions possible. Since the precise number of instructions
-and their execution time varies based upon target CPU family, CPU model,
-board memory speed, compiler version, and optimization level, it is
-not practical to provide the precise number for all possible RTEMS
-configurations.
-
-Historically, the measurements were made by hand analyzing and counting
-the execution time of instruction sequences during interrupt disable
-critical sections. For reference purposes, on a 16 Mhz Motorola
-MC68020, the maximum interrupt disable period was typically approximately
-ten (10) to thirteen (13) microseconds. This architecture was memory bound
-and had a slow bit scan instruction. In contrast, during the same
-period a 14 Mhz SPARC would have a worst case disable time of approximately
-two (2) to three (3) microseconds because it had a single cycle bit scan
-instruction and used fewer cycles for memory accesses.
-
-If you are interested in knowing the worst case execution time for
-a particular version of RTEMS, please contact OAR Corporation and
-we will be happy to product the results as a consulting service.
-
-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.
-
-Default Fatal Error Processing
-==============================
-
-Upon detection of a fatal error by either the application or RTEMS during
-initialization the ``rtems_fatal_error_occurred`` directive supplied
-by the Fatal Error Manager is invoked. The Fatal Error Manager will
-invoke the user-supplied fatal error handlers. If no user-supplied
-handlers are configured or all of them return without taking action to
-shutdown the processor or reset, a default fatal error handler is invoked.
-
-Most of the action performed as part of processing the fatal error are
-described in detail in the Fatal Error Manager chapter in the User’s
-Guide. However, the if no user provided extension or BSP specific fatal
-error handler takes action, the final default action is to invoke a
-CPU architecture specific function. Typically this function disables
-interrupts and halts the processor.
-
-In each of the architecture specific chapters, this describes the precise
-operations of the default CPU specific fatal error handler.
-
-Symmetric Multiprocessing
-=========================
-
-This section contains information about the Symmetric Multiprocessing (SMP)
-status of a particular architecture.
-
-Thread-Local Storage
-====================
-
-In order to support thread-local storage (TLS) the CPU port must implement the
-facilities mandated by the application binary interface (ABI) of the CPU
-architecture. The CPU port must initialize the TLS area in the``_CPU_Context_Initialize()`` function. There are support functions available
-via ``#include <rtems/score/tls.h>`` which implement Variants I and II
-according to Ulrich Drepper, *ELF Handling For Thread-Local Storage*.
-
-``_TLS_TCB_at_area_begin_initialize()``
- Uses Variant I, TLS offsets emitted by linker takes the TCB into account. For
- a reference implementation see :file:`cpukit/score/cpu/arm/cpu.c`.
-
-``_TLS_TCB_before_TLS_block_initialize()``
- Uses Variant I, TLS offsets emitted by linker neglects the TCB. For a
- reference implementation see:file:`c/src/lib/libcpu/powerpc/new-exceptions/cpu.c`.
-
-``_TLS_TCB_after_TLS_block_initialize()``
- Uses Variant II. For a reference implementation see:file:`cpukit/score/cpu/sparc/cpu.c`.
-
-The board support package (BSP) must provide the following sections and symbols
-in its linker command file:
-.. code:: c
-
- .tdata : {
- _TLS_Data_begin = .;
- \*(.tdata .tdata.* .gnu.linkonce.td.*)
- _TLS_Data_end = .;
- }
- .tbss : {
- _TLS_BSS_begin = .;
- \*(.tbss .tbss.* .gnu.linkonce.tb.*) \*(.tcommon)
- _TLS_BSS_end = .;
- }
- _TLS_Data_size = _TLS_Data_end - _TLS_Data_begin;
- _TLS_Data_begin = _TLS_Data_size != 0 ? _TLS_Data_begin : _TLS_BSS_begin;
- _TLS_Data_end = _TLS_Data_size != 0 ? _TLS_Data_end : _TLS_BSS_begin;
- _TLS_BSS_size = _TLS_BSS_end - _TLS_BSS_begin;
- _TLS_Size = _TLS_BSS_end - _TLS_Data_begin;
- _TLS_Alignment = MAX (ALIGNOF (.tdata), ALIGNOF (.tbss));
-
-CPU counter
-===========
-
-The CPU support must implement the CPU counter interface. A CPU counter is
-some free-running counter. It ticks usually with a frequency close to the CPU
-or system bus clock. On some architectures the actual implementation is board
-support package dependent. The CPU counter is used for profiling of low-level
-functions. It is also used to implement two busy wait functions``rtems_counter_delay_ticks()`` and ``rtems_counter_delay_nanoseconds()``
-which may be used in device drivers. It may be also used as an entropy source
-for random number generators.
-
-The CPU counter interface uses a CPU port specific unsigned integer type``CPU_Counter_ticks`` to represent CPU counter values. The CPU port must
-provide the following two functions
-
-- ``_CPU_Counter_read()`` to read the current CPU counter value, and
-
-- ``_CPU_Counter_difference()`` to get the difference between two CPU
- counter values.
-
-Interrupt Profiling
-===================
-
-The RTEMS profiling needs support by the CPU port for the interrupt entry and
-exit 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) the CPU port may provide data for the
-interrupt entry and exit times of the outer-most interrupt. The CPU port can
-feed interrupt entry and exit times with the``_Profiling_Outer_most_interrupt_entry_and_exit()`` function
-(``#include <rtems/score/profiling.h>``). For an example please have a look
-at ``cpukit/score/cpu/arm/arm_exc_interrupt.S``.
-
-Board Support Packages
-======================
-
-An RTEMS Board Support Package (BSP) must be designed to support a
-particular processor model and target board combination.
-
-In each of the architecture specific chapters, this section will present
-a discussion of architecture specific BSP issues. For more information
-on developing a BSP, refer to BSP and Device Driver Development Guide
-and the chapter titled Board Support Packages in the RTEMS
-Applications User’s Guide.
-
-System Reset
-------------
-
-An RTEMS based application is initiated or re-initiated when the processor
-is reset or transfer is passed to it from a boot monitor or ROM monitor.
-
-In each of the architecture specific chapters, this subsection describes
-the actions that the BSP must tak assuming the application gets control
-when the microprocessor is reset.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-ARM Specific Information
-########################
-
-This chapter discusses the`ARM architecture <http://en.wikipedia.org/wiki/ARM_architecture>`_
-dependencies in this port of RTEMS. The ARMv4T (and compatible), ARMv7-A,
-ARMv7-R and ARMv7-M architecture versions are supported by RTEMS. Processors
-with a MMU use a static configuration which is set up during system start. SMP
-is supported.
-
-**Architecture Documents**
-
-For information on the ARM architecture refer to the`ARM Infocenter <http://infocenter.arm.com>`_.
-
-CPU Model Dependent Features
-============================
-
-This section presents the set of features which vary
-across ARM implementations and are of importance to RTEMS. The set of CPU
-model feature macros are defined in the file:file:`cpukit/score/cpu/arm/rtems/score/arm.h` based upon the particular CPU
-model flags specified on the compilation command line.
-
-CPU Model Name
---------------
-
-The macro ``CPU_MODEL_NAME`` is a string which designates
-the architectural level of this CPU model. See in:file:`cpukit/score/cpu/arm/rtems/score/arm.h` for the values.
-
-Count Leading Zeroes Instruction
---------------------------------
-
-The ARMv5 and later has the count leading zeroes ``clz`` instruction which
-could be used to speed up the find first bit operation. The use of this
-instruction should significantly speed up the scheduling associated with a
-thread blocking. This is currently not used.
-
-Floating Point Unit
--------------------
-
-The following floating point units are supported.
-
-- VFPv3-D32/NEON (for example available on Cortex-A processors)
-
-- VFPv3-D16 (for example available on Cortex-R processors)
-
-- FPv4-SP-D16 (for example available on Cortex-M processors)
-
-Multilibs
-=========
-
-The following multilibs are available:
-
-# ``.``: ARMv4T, ARM instruction set
-
-# ``thumb``: ARMv4T, Thumb-1 instruction set
-
-# ``thumb/armv6-m``: ARMv6M, subset of Thumb-2 instruction set
-
-# ``thumb/armv7-a``: ARMv7-A, Thumb-2 instruction set
-
-# ``thumb/armv7-a/neon/hard``: ARMv7-A, Thumb-2 instruction set with
- hard-float ABI Neon and VFP-D32 support
-
-# ``thumb/armv7-r``: ARMv7-R, Thumb-2 instruction set
-
-# ``thumb/armv7-r/vfpv3-d16/hard``: ARMv7-R, Thumb-2 instruction set
- with hard-float ABI VFP-D16 support
-
-# ``thumb/armv7-m``: ARMv7-M, Thumb-2 instruction set with hardware
- integer division (SDIV/UDIV)
-
-# ``thumb/armv7-m/fpv4-sp-d16``: ARMv7-M, Thumb-2 instruction set with
- hardware integer division (SDIV/UDIV) and hard-float ABI FPv4-SP support
-
-# ``eb/thumb/armv7-r``: ARMv7-R, Big-endian Thumb-2 instruction set
-
-# ``eb/thumb/armv7-r/vfpv3-d16/hard``: ARMv7-R, Big-endian Thumb-2
- instruction set with hard-float ABI VFP-D16 support
-
-Multilib 1. and 2. support the standard ARM7TDMI and ARM926EJ-S targets.
-
-Multilib 3. supports the Cortex-M0 and Cortex-M1 cores.
-
-Multilib 8. supports the Cortex-M3 and Cortex-M4 cores, which have a special
-hardware integer division instruction (this is not present in the A and R
-profiles).
-
-Multilib 9. supports the Cortex-M4 cores with a floating point unit.
-
-Multilib 4. and 5. support the Cortex-A processors.
-
-Multilib 6., 7., 10. and 11. support the Cortex-R processors. Here also
-big-endian variants are available.
-
-Use for example the following GCC options
-.. code:: c
-
- -mthumb -march=armv7-a -mfpu=neon -mfloat-abi=hard -mtune=cortex-a9
-
-to build an application or BSP for the ARMv7-A architecture and tune the code
-for a Cortex-A9 processor. It is important to select the options used for the
-multilibs. For example
-.. code:: c
-
- -mthumb -mcpu=cortex-a9
-
-alone will not select the ARMv7-A multilib.
-
-Calling Conventions
-===================
-
-Please refer to the`Procedure Call Standard for the ARM Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042c/IHI0042C_aapcs.pdf>`_.
-
-Memory Model
-============
-
-A flat 32-bit memory model is supported. The board support package must take
-care about the MMU if necessary.
-
-Interrupt Processing
-====================
-
-The ARMv4T (and compatible) architecture has seven exception types:
-
-- Reset
-
-- Undefined
-
-- Software Interrupt (SWI)
-
-- Prefetch Abort
-
-- Data Abort
-
-- Interrupt (IRQ)
-
-- Fast Interrupt (FIQ)
-
-Of these types only the IRQ has explicit operating system support. It is
-intentional that the FIQ is not supported by the operating system. Without
-operating system support for the FIQ it is not necessary to disable them during
-critical sections of the system.
-
-The ARMv7-M architecture has a completely different exception model. Here
-interrupts are disabled with a write of 0x80 to the ``basepri_max``
-register. This means that all exceptions and interrupts with a priority value
-of greater than or equal to 0x80 are disabled. Thus exceptions and interrupts
-with a priority value of less than 0x80 are non-maskable with respect to the
-operating system and therefore must not use operating system services. Several
-support libraries of chip vendors implicitly shift the priority value somehow
-before the value is written to the NVIC IPR register. This can easily lead to
-confusion.
-
-Interrupt Levels
-----------------
-
-There are exactly two interrupt levels on ARM with respect to RTEMS. Level
-zero corresponds to interrupts enabled. Level one corresponds to interrupts
-disabled.
-
-Interrupt Stack
----------------
-
-The board support package must initialize the interrupt stack. The memory for
-the stacks is usually reserved in the linker script.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture performs the
-following actions:
-
-- disables operating system supported interrupts (IRQ),
-
-- places the error code in ``r0``, and
-
-- executes an infinite loop to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is supported on ARMv7-A. Available platforms are the Altera Cyclone V and
-the Xilinx Zynq.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is supported.
-
-.. COMMENT: COPYRIGHT (c) 1988-2009.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Atmel AVR Specific Information
-##############################
-
-This chapter discusses the AVR architecture dependencies in this
-port of RTEMS.
-
-**Architecture Documents**
-
-For information on the AVR architecture, refer to the following
-documents available from Atmel.
-
-TBD
-
-- See other CPUs for documentation reference formatting examples.
-
-CPU Model Dependent Features
-============================
-
-CPUs of the AVR 53X only differ in the peripherals and thus in the
-device drivers. This port does not yet support the 56X dual core variants.
-
-Count Leading Zeroes Instruction
---------------------------------
-
-The AVR CPU has the XXX instruction which could be used to speed
-up the find first bit operation. The use of this instruction should
-significantly speed up the scheduling associated with a thread blocking.
-
-Calling Conventions
-===================
-
-Processor Background
---------------------
-
-The AVR architecture supports a simple call and return mechanism.
-A subroutine is invoked via the call (``call``) instruction.
-This instruction saves the return address in the ``RETS`` register
-and transfers the execution to the given address.
-
-It is the called funcions responsability to use the link instruction
-to reserve space on the stack for the local variables. Returning from
-a subroutine is done by using the RTS (``RTS``) instruction which
-loads the PC with the adress stored in RETS.
-
-It is is important to note that the ``call`` instruction does not
-automatically save or restore any registers. It is the responsibility
-of the high-level language compiler to define the register preservation
-and usage convention.
-
-Register Usage
---------------
-
-A called function may clobber all registers, except RETS, R4-R7, P3-P5,
-FP and SP. It may also modify the first 12 bytes in the caller’s stack
-frame which is used as an argument area for the first three arguments
-(which are passed in R0...R3 but may be placed on the stack by the
-called function).
-
-Parameter Passing
------------------
-
-RTEMS assumes that the AVR GCC calling convention is followed.
-The first three parameters are stored in registers R0, R1, and R2.
-All other parameters are put pushed on the stack. The result is returned
-through register R0.
-
-Memory Model
-============
-
-The AVR family architecutre support a single unified 4 GB byte
-address space using 32-bit addresses. It maps all resources like internal
-and external memory and IO registers into separate sections of this
-common address space.
-
-The AVR architcture supports some form of memory
-protection via its Memory Management Unit. Since the
-AVR port runs in supervisior mode this memory
-protection mechanisms are not used.
-
-Interrupt Processing
-====================
-
-Discussed in this chapter are the AVR’s interrupt response and
-control mechanisms as they pertain to RTEMS.
-
-Vectoring of an Interrupt Handler
----------------------------------
-
-TBD
-
-Disabling of Interrupts by RTEMS
---------------------------------
-
-During interrupt disable critical sections, RTEMS disables interrupts to
-level N (N) before the execution of this section and restores them
-to the previous level upon completion of the section. RTEMS uses the
-instructions CLI and STI to enable and disable Interrupts. Emulation,
-Reset, NMI and Exception Interrupts are never disabled.
-
-Interrupt Stack
----------------
-
-The AVR Architecture works with two different kind of stacks,
-User and Supervisor Stack. Since RTEMS and its Application run
-in supervisor mode, all interrupts will use the interrupted
-tasks stack for execution.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for the AVR performs the following
-actions:
-
-- disables processor interrupts,
-
-- places the error code in *r0*, and
-
-- executes an infinite loop (``while(0);`` to
- simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not supported due to a broken tool chain.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-TBD
-
-.. COMMENT: COPYRIGHT (c) 1988-2006.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Blackfin Specific Information
-#############################
-
-This chapter discusses the Blackfin architecture dependencies in this
-port of RTEMS.
-
-**Architecture Documents**
-
-For information on the Blackfin architecture, refer to the following
-documents available from Analog Devices.
-
-TBD
-
-- *"ADSP-BF533 Blackfin Processor Hardware Reference."*:file:`http://www.analog.com/UploadedFiles/Associated_Docs/892485982bf533_hwr.pdf`
-
-CPU Model Dependent Features
-============================
-
-CPUs of the Blackfin 53X only differ in the peripherals and thus in the
-device drivers. This port does not yet support the 56X dual core variants.
-
-Count Leading Zeroes Instruction
---------------------------------
-
-The Blackfin CPU has the BITTST instruction which could be used to speed
-up the find first bit operation. The use of this instruction should
-significantly speed up the scheduling associated with a thread blocking.
-
-Calling Conventions
-===================
-
-This section is heavily based on content taken from the Blackfin uCLinux
-documentation wiki which is edited by Analog Devices and Arcturus
-Networks. :file:`http://docs.blackfin.uclinux.org/`
-
-Processor Background
---------------------
-
-The Blackfin architecture supports a simple call and return mechanism.
-A subroutine is invoked via the call (``call``) instruction.
-This instruction saves the return address in the ``RETS`` register
-and transfers the execution to the given address.
-
-It is the called funcions responsability to use the link instruction
-to reserve space on the stack for the local variables. Returning from
-a subroutine is done by using the RTS (``RTS``) instruction which
-loads the PC with the adress stored in RETS.
-
-It is is important to note that the ``call`` instruction does not
-automatically save or restore any registers. It is the responsibility
-of the high-level language compiler to define the register preservation
-and usage convention.
-
-Register Usage
---------------
-
-A called function may clobber all registers, except RETS, R4-R7, P3-P5,
-FP and SP. It may also modify the first 12 bytes in the caller’s stack
-frame which is used as an argument area for the first three arguments
-(which are passed in R0...R3 but may be placed on the stack by the
-called function).
-
-Parameter Passing
------------------
-
-RTEMS assumes that the Blackfin GCC calling convention is followed.
-The first three parameters are stored in registers R0, R1, and R2.
-All other parameters are put pushed on the stack. The result is returned
-through register R0.
-
-Memory Model
-============
-
-The Blackfin family architecutre support a single unified 4 GB byte
-address space using 32-bit addresses. It maps all resources like internal
-and external memory and IO registers into separate sections of this
-common address space.
-
-The Blackfin architcture supports some form of memory
-protection via its Memory Management Unit. Since the
-Blackfin port runs in supervisior mode this memory
-protection mechanisms are not used.
-
-Interrupt Processing
-====================
-
-Discussed in this chapter are the Blackfin’s interrupt response and
-control mechanisms as they pertain to RTEMS. The Blackfin architecture
-support 16 kinds of interrupts broken down into Core and general-purpose
-interrupts.
-
-Vectoring of an Interrupt Handler
----------------------------------
-
-RTEMS maps levels 0 -15 directly to Blackfins event vectors EVT0 -
-EVT15. Since EVT0 - EVT6 are core events and it is suggested to use
-EVT15 and EVT15 for Software interrupts, 7 Interrupts (EVT7-EVT13)
-are left for periferical use.
-
-When installing an RTEMS interrupt handler RTEMS installs a generic
-Interrupt Handler which saves some context and enables nested interrupt
-servicing and then vectors to the users interrupt handler.
-
-Disabling of Interrupts by RTEMS
---------------------------------
-
-During interrupt disable critical sections, RTEMS disables interrupts to
-level four (4) before the execution of this section and restores them
-to the previous level upon completion of the section. RTEMS uses the
-instructions CLI and STI to enable and disable Interrupts. Emulation,
-Reset, NMI and Exception Interrupts are never disabled.
-
-Interrupt Stack
----------------
-
-The Blackfin Architecture works with two different kind of stacks,
-User and Supervisor Stack. Since RTEMS and its Application run
-in supervisor mode, all interrupts will use the interrupted
-tasks stack for execution.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for the Blackfin performs the following
-actions:
-
-- disables processor interrupts,
-
-- places the error code in *r0*, and
-
-- executes an infinite loop (``while(0);`` to
- simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-TBD
-
-.. COMMENT: Copyright (c) 2015 University of York.
-
-.. COMMENT: Hesham ALMatary <hmka501@york.ac.uk>
-
-Epiphany Specific Information
-#############################
-
-This chapter discusses the`Epiphany Architecture <http://adapteva.com/docs/epiphany_sdk_ref.pdf>`_
-dependencies in this port of RTEMS. Epiphany is a chip that can come with 16 and
-64 cores, each of which can run RTEMS separately or they can work together to
-run a SMP RTEMS application.
-
-**Architecture Documents**
-
-For information on the Epiphany architecture refer to the`Epiphany Architecture Reference <http://adapteva.com/docs/epiphany_arch_ref.pdf>`_.
-
-Calling Conventions
-===================
-
-Please refer to the`Epiphany SDK <http://adapteva.com/docs/epiphany_sdk_ref.pdf>`_
-Appendix A: Application Binary Interface
-
-Floating Point Unit
--------------------
-
-A floating point unit is currently not supported.
-
-Memory Model
-============
-
-A flat 32-bit memory model is supported, no caches. Each core has its own 32 KiB
-strictly ordered local memory along with an access to a shared 32 MiB external
-DRAM.
-
-Interrupt Processing
-====================
-
-Every Epiphany core has 10 exception types:
-
-- Reset
-
-- Software Exception
-
-- Data Page Fault
-
-- Timer 0
-
-- Timer 1
-
-- Message Interrupt
-
-- DMA0 Interrupt
-
-- DMA1 Interrupt
-
-- WANT Interrupt
-
-- User Interrupt
-
-Interrupt Levels
-----------------
-
-There are only two levels: interrupts enabled and interrupts disabled.
-
-Interrupt Stack
----------------
-
-The Epiphany RTEMS port uses a dedicated software interrupt stack.
-The stack for interrupts is allocated during interrupt driver initialization.
-When an interrupt is entered, the _ISR_Handler routine is responsible for
-switching from the interrupted task stack to RTEMS software interrupt stack.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture performs the
-following actions:
-
-- disables operating system supported interrupts (IRQ),
-
-- places the error code in ``r0``, and
-
-- executes an infinite loop to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Intel/AMD x86 Specific Information
-##################################
-
-This chapter discusses the Intel x86 architecture dependencies
-in this port of RTEMS. This family has multiple implementations
-from multiple vendors and suffers more from having evolved rather
-than being designed for growth.
-
-For information on the i386 processor, refer to the
-following documents:
-
-- *386 Programmer’s Reference Manual, Intel, Order No. 230985-002*.
-
-- *386 Microprocessor Hardware Reference Manual, Intel,
- Order No. 231732-003*.
-
-- *80386 System Software Writer’s Guide, Intel, Order No. 231499-001*.
-
-- *80387 Programmer’s Reference Manual, Intel, Order No. 231917-001*.
-
-CPU Model Dependent Features
-============================
-
-This section presents the set of features which vary
-across i386 implementations and are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/i386/i386.h`` based upon the particular CPU
-model specified on the compilation command line.
-
-bswap Instruction
------------------
-
-The macro ``I386_HAS_BSWAP`` is set to 1 to indicate that
-this CPU model has the ``bswap`` instruction which
-endian swaps a thirty-two bit quantity. This instruction
-appears to be present in all CPU models
-i486’s and above.
-
-Calling Conventions
-===================
-
-Processor Background
---------------------
-
-The i386 architecture supports a simple yet effective
-call and return mechanism. A subroutine is invoked via the call
-(``call``) instruction. This instruction pushes the return address
-on the stack. The return from subroutine (``ret``) instruction pops
-the return address off the current stack and transfers control
-to that instruction. It is is important to note that the i386
-call and return mechanism does not automatically save or restore
-any registers. It is the responsibility of the high-level
-language compiler to define the register preservation and usage
-convention.
-
-Calling Mechanism
------------------
-
-All RTEMS directives are invoked using a call instruction and return to
-the user application via the ret instruction.
-
-Register Usage
---------------
-
-As discussed above, the call instruction does not automatically save
-any registers. RTEMS uses the registers EAX, ECX, and EDX as scratch
-registers. These registers are not preserved by RTEMS directives
-therefore, the contents of these registers should not be assumed upon
-return from any RTEMS directive.
-
-Parameter Passing
------------------
-
-RTEMS assumes that arguments are placed on the
-current stack before the directive is invoked via the call
-instruction. The first argument is assumed to be closest to the
-return address on the stack. This means that the first argument
-of the C calling sequence is pushed last. The following
-pseudo-code illustrates the typical sequence used to call a
-RTEMS directive with three (3) arguments:
-.. code:: c
-
- push third argument
- push second argument
- push first argument
- invoke directive
- remove arguments from the stack
-
-The arguments to RTEMS are typically pushed onto the
-stack using a push instruction. These arguments must be removed
-from the stack after control is returned to the caller. This
-removal is typically accomplished by adding the size of the
-argument list in bytes to the stack pointer.
-
-Memory Model
-============
-
-Flat Memory Model
------------------
-
-RTEMS supports the i386 protected mode, flat memory
-model with paging disabled. In this mode, the i386
-automatically converts every address from a logical to a
-physical address each time it is used. The i386 uses
-information provided in the segment registers and the Global
-Descriptor Table to convert these addresses. RTEMS assumes the
-existence of the following segments:
-
-- a single code segment at protection level (0) which
- contains all application and executive code.
-
-- a single data segment at protection level zero (0) which
- contains all application and executive data.
-
-The i386 segment registers and associated selectors
-must be initialized when the initialize_executive directive is
-invoked. RTEMS treats the segment registers as system registers
-and does not modify or context switch them.
-
-This i386 memory model supports a flat 32-bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes). Each address is represented by a 32-bit value and
-is byte addressable. The address may be used to reference a
-single byte, half-word (2-bytes), or word (4 bytes).
-
-Interrupt Processing
-====================
-
-Although RTEMS hides many of the processor
-dependent details of interrupt processing, it is important to
-understand how the RTEMS interrupt manager is mapped onto the
-processor’s unique architecture. Discussed in this chapter are
-the the processor’s response and control mechanisms as they
-pertain to RTEMS.
-
-Vectoring of Interrupt Handler
-------------------------------
-
-Although the i386 supports multiple privilege levels,
-RTEMS and all user software executes at privilege level 0. This
-decision was made by the RTEMS designers to enhance
-compatibility with processors which do not provide sophisticated
-protection facilities like those of the i386. This decision
-greatly simplifies the discussion of i386 processing, as one
-need only consider interrupts without privilege transitions.
-
-Upon receipt of an interrupt the i386 automatically
-performs the following actions:
-
-- pushes the EFLAGS register
-
-- pushes the far address of the interrupted instruction
-
-- vectors to the interrupt service routine (ISR).
-
-A nested interrupt is processed similarly by the
-i386.
-
-Interrupt Stack Frame
----------------------
-
-The structure of the Interrupt Stack Frame for the
-i386 which is placed on the interrupt stack by the processor in
-response to an interrupt is as follows:
-
-+----------------------+-------+
-| Old EFLAGS Register | ESP+8 |
-+----------+-----------+-------+
-| UNUSED | Old CS | ESP+4 |
-+----------+-----------+-------+
-| Old EIP | ESP |
-+----------------------+-------+
-
-
-Interrupt Levels
-----------------
-
-Although RTEMS supports 256 interrupt levels, the
-i386 only supports two – enabled and disabled. Interrupts are
-enabled when the interrupt-enable flag (IF) in the extended
-flags (EFLAGS) is set. Conversely, interrupt processing is
-inhibited when the IF is cleared. During a non-maskable
-interrupt, all other interrupts, including other non-maskable
-ones, are inhibited.
-
-RTEMS interrupt levels 0 and 1 such that level zero
-(0) indicates that interrupts are fully enabled and level one
-that interrupts are disabled. All other RTEMS interrupt levels
-are undefined and their behavior is unpredictable.
-
-Interrupt Stack
----------------
-
-The i386 family does not support a dedicated hardware
-interrupt stack. On this processor, RTEMS allocates and manages
-a dedicated interrupt stack. As part of vectoring a non-nested
-interrupt service routine, RTEMS switches from the stack of the
-interrupted task to a dedicated interrupt stack. When a
-non-nested interrupt returns, RTEMS switches back to the stack
-of the interrupted stack. The current stack pointer is not
-altered by RTEMS on nested interrupt.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture disables processor
-interrupts, places the error code in EAX, and executes a HLT instruction
-to halt the processor.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-An RTEMS based application is initiated when the i386 processor is reset.
-When the i386 is reset,
-
-- The EAX register is set to indicate the results of the processor’s
- power-up self test. If the self-test was not executed, the contents of
- this register are undefined. Otherwise, a non-zero value indicates the
- processor is faulty and a zero value indicates a successful self-test.
-
-- The DX register holds a component identifier and revision level. DH
- contains 3 to indicate an i386 component and DL contains a unique revision
- level indicator.
-
-- Control register zero (CR0) is set such that the processor is in real
- mode with paging disabled. Other portions of CR0 are used to indicate the
- presence of a numeric coprocessor.
-
-- All bits in the extended flags register (EFLAG) which are not
- permanently set are cleared. This inhibits all maskable interrupts.
-
-- The Interrupt Descriptor Register (IDTR) is set to point at address
- zero.
-
-- All segment registers are set to zero.
-
-- The instruction pointer is set to 0x0000FFF0. The first instruction
- executed after a reset is actually at 0xFFFFFFF0 because the i386 asserts
- the upper twelve address until the first intersegment (FAR) JMP or CALL
- instruction. When a JMP or CALL is executed, the upper twelve address
- lines are lowered and the processor begins executing in the first megabyte
- of memory.
-
-Typically, an intersegment JMP to the application’s initialization code is
-placed at address 0xFFFFFFF0.
-
-Processor Initialization
-------------------------
-
-This initialization code is responsible for initializing all data
-structures required by the i386 in protected mode and for actually entering
-protected mode. The i386 must be placed in protected mode and the segment
-registers and associated selectors must be initialized before the
-initialize_executive directive is invoked.
-
-The initialization code is responsible for initializing the Global
-Descriptor Table such that the i386 is in the thirty-two bit flat memory
-model with paging disabled. In this mode, the i386 automatically converts
-every address from a logical to a physical address each time it is used.
-For more information on the memory model used by RTEMS, please refer to the
-Memory Model chapter in this document.
-
-Since the processor is in real mode upon reset, the processor must be
-switched to protected mode before RTEMS can execute. Before switching to
-protected mode, at least one descriptor table and two descriptors must be
-created. Descriptors are needed for a code segment and a data segment. (
-This will give you the flat memory model.) The stack can be placed in a
-normal read/write data segment, so no descriptor for the stack is needed.
-Before the GDT can be used, the base address and limit must be loaded into
-the GDTR register using an LGDT instruction.
-
-If the hardware allows an NMI to be generated, you need to create the IDT
-and a gate for the NMI interrupt handler. Before the IDT can be used, the
-base address and limit for the idt must be loaded into the IDTR register
-using an LIDT instruction.
-
-Protected mode is entered by setting thye PE bit in the CR0 register.
-Either a LMSW or MOV CR0 instruction may be used to set this bit. Because
-the processor overlaps the interpretation of several instructions, it is
-necessary to discard the instructions from the read-ahead cache. A JMP
-instruction immediately after the LMSW changes the flow and empties the
-processor if intructions which have been pre-fetched and/or decoded. At
-this point, the processor is in protected mode and begins to perform
-protected mode application initialization.
-
-If the application requires that the IDTR be some value besides zero, then
-it should set it to the required value at this point. All tasks share the
-same i386 IDTR value. Because interrupts are enabled automatically by
-RTEMS as part of the initialize_executive directive, the IDTR MUST be set
-properly before this directive is invoked to insure correct interrupt
-vectoring. If processor caching is to be utilized, then it should be
-enabled during the reset application initialization code. The reset code
-which is executed before the call to initialize_executive has the following
-requirements:
-
-For more information regarding the i386 data structures and their
-contents, refer to Intel’s 386 Programmer’s Reference Manual.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: Jukka Pietarinen <jukka.pietarinen@mrf.fi>, 2008,
-
-.. COMMENT: Micro-Research Finland Oy
-
-Lattice Mico32 Specific Information
-###################################
-
-This chaper discusses the Lattice Mico32 architecture dependencies in
-this port of RTEMS. The Lattice Mico32 is a 32-bit Harvard, RISC
-architecture "soft" microprocessor, available for free with an open IP
-core licensing agreement. Although mainly targeted for Lattice FPGA
-devices the microprocessor can be implemented on other vendors’ FPGAs,
-too.
-
-**Architecture Documents**
-
-For information on the Lattice Mico32 architecture, refer to the
-following documents available from Lattice Semiconductor:file:`http://www.latticesemi.com/`.
-
-- *"LatticeMico32 Processor Reference Manual"*:file:`http://www.latticesemi.com/dynamic/view_document.cfm?document_id=20890`
-
-CPU Model Dependent Features
-============================
-
-The Lattice Mico32 architecture allows for different configurations of
-the processor. This port is based on the assumption that the following options are implemented:
-
-- hardware multiplier
-
-- hardware divider
-
-- hardware barrel shifter
-
-- sign extension instructions
-
-- instruction cache
-
-- data cache
-
-- debug
-
-Register Architecture
-=====================
-
-This section gives a brief introduction to the register architecture
-of the Lattice Mico32 processor.
-
-The Lattice Mico32 is a RISC archictecture processor with a
-32-register file of 32-bit registers.
-
-Register Name
-
-Function
-
-r0
-
-holds value zero
-
-r1-r25
-
-general purpose
-
-r26/gp
-
-general pupose / global pointer
-
-r27/fp
-
-general pupose / frame pointer
-
-r28/sp
-
-stack pointer
-
-r29/ra
-
-return address
-
-r30/ea
-
-exception address
-
-r31/ba
-
-breakpoint address
-
-Note that on processor startup all register values are undefined
-including r0, thus r0 has to be initialized to zero.
-
-Calling Conventions
-===================
-
-Calling Mechanism
------------------
-
-A call instruction places the return address to register r29 and a
-return from subroutine (ret) is actually a branch to r29/ra.
-
-Register Usage
---------------
-
-A subroutine may freely use registers r1 to r10 which are *not*
-preserved across subroutine invocations.
-
-Parameter Passing
------------------
-
-When calling a C function the first eight arguments are stored in
-registers r1 to r8. Registers r1 and r2 hold the return value.
-
-Memory Model
-============
-
-The Lattice Mico32 processor supports a flat memory model with a 4
-Gbyte address space with 32-bit addresses.
-
-The following data types are supported:
-
-Type
-
-Bits
-
-C Compiler Type
-
-unsigned byte
-
-8
-
-unsigned char
-
-signed byte
-
-8
-
-char
-
-unsigned half-word
-
-16
-
-unsigned short
-
-signed half-word
-
-16
-
-short
-
-unsigned word
-
-32
-
-unsigned int / unsigned long
-
-signed word
-
-32
-
-int / long
-
-Data accesses need to be aligned, with unaligned accesses result are
-undefined.
-
-Interrupt Processing
-====================
-
-The Lattice Mico32 has 32 interrupt lines which are however served by
-only one exception vector. When an interrupt occurs following happens:
-
-- address of next instruction placed in r30/ea
-
-- IE field of IE CSR saved to EIE field and IE field cleared preventing further exceptions from occuring.
-
-- branch to interrupt exception address EBA CSR + 0xC0
-
-The interrupt exception handler determines from the state of the
-interrupt pending registers (IP CSR) and interrupt enable register (IE
-CSR) which interrupt to serve and jumps to the interrupt routine
-pointed to by the corresponding interrupt vector.
-
-For now there is no dedicated interrupt stack so every task in
-the system MUST have enough stack space to accommodate the worst
-case stack usage of that particular task and the interrupt
-service routines COMBINED.
-
-Nested interrupts are not supported.
-
-Default Fatal Error Processing
-==============================
-
-Upon detection of a fatal error by either the application or RTEMS during
-initialization the ``rtems_fatal_error_occurred`` directive supplied
-by the Fatal Error Manager is invoked. The Fatal Error Manager will
-invoke the user-supplied fatal error handlers. If no user-supplied
-handlers are configured or all of them return without taking action to
-shutdown the processor or reset, a default fatal error handler is invoked.
-
-Most of the action performed as part of processing the fatal error are
-described in detail in the Fatal Error Manager chapter in the User’s
-Guide. However, the if no user provided extension or BSP specific fatal
-error handler takes action, the final default action is to invoke a
-CPU architecture specific function. Typically this function disables
-interrupts and halts the processor.
-
-In each of the architecture specific chapters, this describes the precise
-operations of the default CPU specific fatal error handler.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-Board Support Packages
-======================
-
-An RTEMS Board Support Package (BSP) must be designed to support a
-particular processor model and target board combination.
-
-In each of the architecture specific chapters, this section will present
-a discussion of architecture specific BSP issues. For more information
-on developing a BSP, refer to BSP and Device Driver Development Guide
-and the chapter titled Board Support Packages in the RTEMS
-Applications User’s Guide.
-
-System Reset
-------------
-
-An RTEMS based application is initiated or re-initiated when the processor
-is reset.
-
-.. COMMENT: Copyright (c) 2014 embedded brains GmbH. All rights reserved.
-
-Renesas M32C Specific Information
-#################################
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-M68xxx and Coldfire Specific Information
-########################################
-
-This chapter discusses the Freescale (formerly Motorola) MC68xxx
-and Coldfire architectural dependencies. The MC68xxx family has a
-wide variety of CPU models within it based upon different CPU core
-implementations. Ignoring the Coldfire parts, the part numbers for
-these models are generally divided into MC680xx and MC683xx. The MC680xx
-models are more general purpose processors with no integrated peripherals.
-The MC683xx models, on the other hand, are more specialized and have a
-variety of peripherals on chip including sophisticated timers and serial
-communications controllers.
-
-**Architecture Documents**
-
-For information on the MC68xxx and Coldfire architecture, refer to the following documents available from Freescale website (:file:`http//www.freescale.com/`):
-
-- *M68000 Family Reference, Motorola, FR68K/D*.
-
-- *MC68020 User’s Manual, Motorola, MC68020UM/AD*.
-
-- *MC68881/MC68882 Floating-Point Coprocessor User’s Manual,
- Motorola, MC68881UM/AD*.
-
-CPU Model Dependent Features
-============================
-
-This section presents the set of features which vary
-across m68k/Coldfire implementations that are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/m68k/m68k.h`` based upon the particular CPU
-model selected on the compilation command line.
-
-BFFFO Instruction
------------------
-
-The macro ``M68K_HAS_BFFFO`` is set to 1 to indicate that
-this CPU model has the bfffo instruction.
-
-Vector Base Register
---------------------
-
-The macro ``M68K_HAS_VBR`` is set to 1 to indicate that
-this CPU model has a vector base register (vbr).
-
-Separate Stacks
----------------
-
-The macro ``M68K_HAS_SEPARATE_STACKS`` is set to 1 to
-indicate that this CPU model has separate interrupt, user, and
-supervisor mode stacks.
-
-Pre-Indexing Address Mode
--------------------------
-
-The macro ``M68K_HAS_PREINDEXING`` is set to 1 to indicate that
-this CPU model has the pre-indexing address mode.
-
-Extend Byte to Long Instruction
--------------------------------
-
-The macro ``M68K_HAS_EXTB_L`` is set to 1 to indicate that this CPU model
-has the extb.l instruction. This instruction is supposed to be available
-in all models based on the cpu32 core as well as mc68020 and up models.
-
-Calling Conventions
-===================
-
-The MC68xxx architecture supports a simple yet effective call and
-return mechanism. A subroutine is invoked via the branch to subroutine
-(``bsr``) or the jump to subroutine (``jsr``) instructions.
-These instructions push the return address on the current stack.
-The return from subroutine (``rts``) instruction pops the return
-address off the current stack and transfers control to that instruction.
-It is is important to note that the MC68xxx call and return mechanism does
-not automatically save or restore any registers. It is the responsibility
-of the high-level language compiler to define the register preservation
-and usage convention.
-
-Calling Mechanism
------------------
-
-All RTEMS directives are invoked using either a ``bsr`` or ``jsr``
-instruction and return to the user application via the rts instruction.
-
-Register Usage
---------------
-
-As discussed above, the ``bsr`` and ``jsr`` instructions do not
-automatically save any registers. RTEMS uses the registers D0, D1,
-A0, and A1 as scratch registers. These registers are not preserved by
-RTEMS directives therefore, the contents of these registers should not
-be assumed upon return from any RTEMS directive.
-
-Parameter Passing
------------------
-
-RTEMS assumes that arguments are placed on the current stack before
-the directive is invoked via the bsr or jsr instruction. The first
-argument is assumed to be closest to the return address on the stack.
-This means that the first argument of the C calling sequence is pushed
-last. The following pseudo-code illustrates the typical sequence used
-to call a RTEMS directive with three (3) arguments:
-.. code:: c
-
- push third argument
- push second argument
- push first argument
- invoke directive
- remove arguments from the stack
-
-The arguments to RTEMS are typically pushed onto the stack using a move
-instruction with a pre-decremented stack pointer as the destination.
-These arguments must be removed from the stack after control is returned
-to the caller. This removal is typically accomplished by adding the
-size of the argument list in bytes to the current stack pointer.
-
-Memory Model
-============
-
-The MC68xxx family supports a flat 32-bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes). Each address is represented by a 32-bit value and
-is byte addressable. The address may be used to reference a
-single byte, word (2-bytes), or long word (4 bytes). Memory
-accesses within this address space are performed in big endian
-fashion by the processors in this family.
-
-Some of the MC68xxx family members such as the
-MC68020, MC68030, and MC68040 support virtual memory and
-segmentation. The MC68020 requires external hardware support
-such as the MC68851 Paged Memory Management Unit coprocessor
-which is typically used to perform address translations for
-these systems. RTEMS does not support virtual memory or
-segmentation on any of the MC68xxx family members.
-
-Interrupt Processing
-====================
-
-Discussed in this section are the MC68xxx’s interrupt response and
-control mechanisms as they pertain to RTEMS.
-
-Vectoring of an Interrupt Handler
----------------------------------
-
-Depending on whether or not the particular CPU supports a separate
-interrupt stack, the MC68xxx family has two different interrupt handling
-models.
-
-Models Without Separate Interrupt Stacks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Upon receipt of an interrupt the MC68xxx family members without separate
-interrupt stacks automatically perform the following actions:
-
-- To Be Written
-
-Models With Separate Interrupt Stacks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Upon receipt of an interrupt the MC68xxx family members with separate
-interrupt stacks automatically perform the following actions:
-
-- saves the current status register (SR),
-
-- clears the master/interrupt (M) bit of the SR to
- indicate the switch from master state to interrupt state,
-
-- sets the privilege mode to supervisor,
-
-- suppresses tracing,
-
-- sets the interrupt mask level equal to the level of the
- interrupt being serviced,
-
-- pushes an interrupt stack frame (ISF), which includes
- the program counter (PC), the status register (SR), and the
- format/exception vector offset (FVO) word, onto the supervisor
- and interrupt stacks,
-
-- switches the current stack to the interrupt stack and
- vectors to an interrupt service routine (ISR). If the ISR was
- installed with the interrupt_catch directive, then the RTEMS
- interrupt handler will begin execution. The RTEMS interrupt
- handler saves all registers which are not preserved according to
- the calling conventions and invokes the application’s ISR.
-
-A nested interrupt is processed similarly by these
-CPU models with the exception that only a single ISF is placed
-on the interrupt stack and the current stack need not be
-switched.
-
-The FVO word in the Interrupt Stack Frame is examined
-by RTEMS to determine when an outer most interrupt is being
-exited. Since the FVO is used by RTEMS for this purpose, the
-user application code MUST NOT modify this field.
-
-The following shows the Interrupt Stack Frame for
-MC68xxx CPU models with separate interrupt stacks:
-
-+----------------------+-----+
-| Status Register | 0x0 |
-+----------------------+-----+
-| Program Counter High | 0x2 |
-+----------------------+-----+
-| Program Counter Low | 0x4 |
-+----------------------+-----+
-| Format/Vector Offset | 0x6 |
-+----------------------+-----+
-
-
-CPU Models Without VBR and RAM at 0
------------------------------------
-
-This is from a post by Zoltan Kocsi <zoltan@bendor.com.au> and is
-a nice trick in certain situations. In his words:
-
-I think somebody on this list asked about the interupt vector handling
-w/o VBR and RAM at 0. The usual trick is to initialise the vector table
-(except the first 2 two entries, of course) to point to the same location
-BUT you also add the vector number times 0x1000000 to them. That is,
-bits 31-24 contain the vector number and 23-0 the address of the common
-handler. Since the PC is 32 bit wide but the actual address bus is only
-24, the top byte will be in the PC but will be ignored when jumping onto
-your routine.
-
-Then your common interrupt routine gets this info by loading the PC
-into some register and based on that info, you can jump to a vector in
-a vector table pointed by a virtual VBR:
-.. code:: c
-
- //
- // Real vector table at 0
- //
- .long initial_sp
- .long initial_pc
- .long myhandler+0x02000000
- .long myhandler+0x03000000
- .long myhandler+0x04000000
- ...
- .long myhandler+0xff000000
- //
- // This handler will jump to the interrupt routine of which
- // the address is stored at VBR[ vector_no ]
- // The registers and stackframe will be intact, the interrupt
- // routine will see exactly what it would see if it was called
- // directly from the HW vector table at 0.
- //
- .comm VBR,4,2 // This defines the 'virtual' VBR
- // From C: extern void \*VBR;
- myhandler: // At entry, PC contains the full vector
- move.l %d0,-(%sp) // Save d0
- move.l %a0,-(%sp) // Save a0
- lea 0(%pc),%a0 // Get the value of the PC
- move.l %a0,%d0 // Copy it to a data reg, d0 is VV??????
- swap %d0 // Now d0 is ????VV??
- and.w #0xff00,%d0 // Now d0 is ????VV00 (1)
- lsr.w #6,%d0 // Now d0.w contains the VBR table offset
- move.l VBR,%a0 // Get the address from VBR to a0
- move.l (%a0,%d0.w),%a0 // Fetch the vector
- move.l 4(%sp),%d0 // Restore d0
- move.l %a0,4(%sp) // Place target address to the stack
- move.l (%sp)+,%a0 // Restore a0, target address is on TOS
- ret // This will jump to the handler and
- // restore the stack
- (1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
- after the vector table then that insn is not needed.
-
-There are probably shorter ways to do this, but it I believe is enough
-to illustrate the trick. Optimisation is left as an exercise to the
-reader :-)
-
-Interrupt Levels
-----------------
-
-Eight levels (0-7) of interrupt priorities are
-supported by MC68xxx family members with level seven (7) being
-the highest priority. Level zero (0) indicates that interrupts
-are fully enabled. Interrupt requests for interrupts with
-priorities less than or equal to the current interrupt mask
-level are ignored.
-
-Although RTEMS supports 256 interrupt levels, the
-MC68xxx family only supports eight. RTEMS interrupt levels 0
-through 7 directly correspond to MC68xxx interrupt levels. All
-other RTEMS interrupt levels are undefined and their behavior is
-unpredictable.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture disables processor
-interrupts to level 7, places the error code in D0, and executes a``stop`` instruction to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is supported.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-An RTEMS based application is initiated or re-initiated when the MC68020
-processor is reset. When the MC68020 is reset, the processor performs
-the following actions:
-
-- The tracing bits of the status register are cleared to
- disable tracing.
-
-- The supervisor interrupt state is entered by setting the
- supervisor (S) bit and clearing the master/interrupt (M) bit of
- the status register.
-
-- The interrupt mask of the status register is set to
- level 7 to effectively disable all maskable interrupts.
-
-- The vector base register (VBR) is set to zero.
-
-- The cache control register (CACR) is set to zero to
- disable and freeze the processor cache.
-
-- The interrupt stack pointer (ISP) is set to the value
- stored at vector 0 (bytes 0-3) of the exception vector table
- (EVT).
-
-- The program counter (PC) is set to the value stored at
- vector 1 (bytes 4-7) of the EVT.
-
-- The processor begins execution at the address stored in
- the PC.
-
-Processor Initialization
-------------------------
-
-The address of the application’s initialization code should be stored in
-the first vector of the EVT which will allow the immediate vectoring to
-the application code. If the application requires that the VBR be some
-value besides zero, then it should be set to the required value at this
-point. All tasks share the same MC68020’s VBR value. Because interrupts
-are enabled automatically by RTEMS as part of the context switch to the
-first task, the VBR MUST be set by either RTEMS of the BSP before this
-occurs ensure correct interrupt vectoring. If processor caching is
-to be utilized, then it should be enabled during the reset application
-initialization code.
-
-In addition to the requirements described in the
-Board Support Packages chapter of the Applications User’s
-Manual for the reset code which is executed before the call to
-initialize executive, the MC68020 version has the following
-specific requirements:
-
-- Must leave the S bit of the status register set so that
- the MC68020 remains in the supervisor state.
-
-- Must set the M bit of the status register to remove the
- MC68020 from the interrupt state.
-
-- Must set the master stack pointer (MSP) such that a
- minimum stack size of MINIMUM_STACK_SIZE bytes is provided for
- the initialize executive directive.
-
-- Must initialize the MC68020’s vector table.
-
-.. COMMENT: Copyright (c) 2014 embedded brains GmbH. All rights reserved.
-
-Xilinx MicroBlaze Specific Information
-######################################
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-MIPS Specific Information
-#########################
-
-This chapter discusses the MIPS architecture dependencies
-in this port of RTEMS. The MIPS family has a wide variety
-of implementations by a wide range of vendors. Consequently,
-there are many, many CPU models within it.
-
-**Architecture Documents**
-
-IDT docs are online at http://www.idt.com/products/risc/Welcome.html
-
-For information on the XXX architecture, refer to the following documents
-available from VENDOR (:file:`http//www.XXX.com/`):
-
-- *XXX Family Reference, VENDOR, PART NUMBER*.
-
-CPU Model Dependent Features
-============================
-
-This section presents the set of features which vary
-across MIPS implementations and are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/mips/mips.h`` based upon the particular CPU
-model specified on the compilation command line.
-
-Another Optional Feature
-------------------------
-
-The macro XXX
-
-Calling Conventions
-===================
-
-Processor Background
---------------------
-
-TBD
-
-Calling Mechanism
------------------
-
-TBD
-
-Register Usage
---------------
-
-TBD
-
-Parameter Passing
------------------
-
-TBD
-
-Memory Model
-============
-
-Flat Memory Model
------------------
-
-The MIPS family supports a flat 32-bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes). Each address is represented by a 32-bit value and
-is byte addressable. The address may be used to reference a
-single byte, word (2-bytes), or long word (4 bytes). Memory
-accesses within this address space are performed in big endian
-fashion by the processors in this family.
-
-Some of the MIPS family members such as the support virtual memory and
-segmentation. RTEMS does not support virtual memory or
-segmentation on any of these family members.
-
-Interrupt Processing
-====================
-
-Although RTEMS hides many of the processor dependent
-details of interrupt processing, it is important to understand
-how the RTEMS interrupt manager is mapped onto the processor’s
-unique architecture. Discussed in this chapter are the MIPS’s
-interrupt response and control mechanisms as they pertain to
-RTEMS.
-
-Vectoring of an Interrupt Handler
----------------------------------
-
-Upon receipt of an interrupt the XXX family
-members with separate interrupt stacks automatically perform the
-following actions:
-
-- TBD
-
-A nested interrupt is processed similarly by these
-CPU models with the exception that only a single ISF is placed
-on the interrupt stack and the current stack need not be
-switched.
-
-Interrupt Levels
-----------------
-
-TBD
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this target architecture disables
-processor interrupts, places the error code in *XXX*, and executes a``XXX`` instruction to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-An RTEMS based application is initiated or
-re-initiated when the processor is reset. When the
-processor is reset, it performs the following actions:
-
-- TBD
-
-Processor Initialization
-------------------------
-
-TBD
-
-.. COMMENT: Copyright (c) 2014 embedded brains GmbH. All rights reserved.
-
-Altera Nios II Specific Information
-###################################
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-.. COMMENT: COPYRIGHT (c) 2014 Hesham ALMatary <heshamelmatary@gmail.com>
-
-.. COMMENT: All rights reserved.
-
-OpenRISC 1000 Specific Information
-##################################
-
-This chapter discusses the`OpenRISC 1000 architecture <http://opencores.org/or1k/Main_Page>`_
-dependencies in this port of RTEMS. There are many implementations
-for OpenRISC like or1200 and mor1kx. Currently RTEMS supports basic
-features that all implementations should have.
-
-**Architecture Documents**
-
-For information on the OpenRISC 1000 architecture refer to the`OpenRISC 1000 architecture manual <http://openrisc.github.io/or1k.html>`_.
-
-Calling Conventions
-===================
-
-Please refer to the`Function Calling Sequence <http://openrisc.github.io/or1k.html#__RefHeading__504887_595890882>`_.
-
-Floating Point Unit
--------------------
-
-A floating point unit is currently not supported.
-
-Memory Model
-============
-
-A flat 32-bit memory model is supported.
-
-Interrupt Processing
-====================
-
-OpenRISC 1000 architecture has 13 exception types:
-
-- Reset
-
-- Bus Error
-
-- Data Page Fault
-
-- Instruction Page Fault
-
-- Tick Timer
-
-- Alignment
-
-- Illegal Instruction
-
-- External Interrupt
-
-- D-TLB Miss
-
-- I-TLB Miss
-
-- Range
-
-- System Call
-
-- Floating Point
-
-- Trap
-
-Interrupt Levels
-----------------
-
-There are only two levels: interrupts enabled and interrupts disabled.
-
-Interrupt Stack
----------------
-
-The OpenRISC RTEMS port uses a dedicated software interrupt stack.
-The stack for interrupts is allocated during interrupt driver initialization.
-When an interrupt is entered, the _ISR_Handler routine is responsible for
-switching from the interrupted task stack to RTEMS software interrupt stack.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture performs the
-following actions:
-
-- disables operating system supported interrupts (IRQ),
-
-- places the error code in ``r0``, and
-
-- executes an infinite loop to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-.. COMMENT: COPYRIGHT (c) 1989-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-PowerPC Specific Information
-############################
-
-This chapter discusses the PowerPC architecture dependencies
-in this port of RTEMS. The PowerPC family has a wide variety
-of implementations by a range of vendors. Consequently,
-there are many, many CPU models within it.
-
-It is highly recommended that the PowerPC RTEMS
-application developer obtain and become familiar with the
-documentation for the processor being used as well as the
-specification for the revision of the PowerPC architecture which
-corresponds to that processor.
-
-**PowerPC Architecture Documents**
-
-For information on the PowerPC architecture, refer to
-the following documents available from Motorola and IBM:
-
-- *PowerPC Microprocessor Family: The Programming Environment*
- (Motorola Document MPRPPCFPE-01).
-
-- *IBM PPC403GB Embedded Controller User’s Manual*.
-
-- *PoweRisControl MPC500 Family RCPU RISC Central Processing
- Unit Reference Manual* (Motorola Document RCPUURM/AD).
-
-- *PowerPC 601 RISC Microprocessor User’s Manual*
- (Motorola Document MPR601UM/AD).
-
-- *PowerPC 603 RISC Microprocessor User’s Manual*
- (Motorola Document MPR603UM/AD).
-
-- *PowerPC 603e RISC Microprocessor User’s Manual*
- (Motorola Document MPR603EUM/AD).
-
-- *PowerPC 604 RISC Microprocessor User’s Manual*
- (Motorola Document MPR604UM/AD).
-
-- *PowerPC MPC821 Portable Systems Microprocessor User’s Manual*
- (Motorola Document MPC821UM/AD).
-
-- *PowerQUICC MPC860 User’s Manual* (Motorola Document MPC860UM/AD).
-
-Motorola maintains an on-line electronic library for the PowerPC
-at the following URL:
-
-- http://www.mot.com/powerpc/library/library.html
-
-This site has a a wealth of information and examples. Many of the
-manuals are available from that site in electronic format.
-
-**PowerPC Processor Simulator Information**
-
-PSIM is a program which emulates the Instruction Set Architecture
-of the PowerPC microprocessor family. It is reely available in source
-code form under the terms of the GNU General Public License (version
-2 or later). PSIM can be integrated with the GNU Debugger (gdb) to
-execute and debug PowerPC executables on non-PowerPC hosts. PSIM
-supports the addition of user provided device models which can be
-used to allow one to develop and debug embedded applications using
-the simulator.
-
-The latest version of PSIM is included in GDB and enabled on pre-built
-binaries provided by the RTEMS Project.
-
-CPU Model Dependent Features
-============================
-
-This section presents the set of features which vary
-across PowerPC implementations and are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/powerpc/powerpc.h`` based upon the particular CPU
-model specified on the compilation command line.
-
-Alignment
----------
-
-The macro PPC_ALIGNMENT is set to the PowerPC model’s worst case alignment
-requirement for data types on a byte boundary. This value is used
-to derive the alignment restrictions for memory allocated from
-regions and partitions.
-
-Cache Alignment
----------------
-
-The macro PPC_CACHE_ALIGNMENT is set to the line size of the cache. It is
-used to align the entry point of critical routines so that as much code
-as possible can be retrieved with the initial read into cache. This
-is done for the interrupt handler as well as the context switch routines.
-
-In addition, the "shortcut" data structure used by the PowerPC implementation
-to ease access to data elements frequently accessed by RTEMS routines
-implemented in assembly language is aligned using this value.
-
-Maximum Interrupts
-------------------
-
-The macro PPC_INTERRUPT_MAX is set to the number of exception sources
-supported by this PowerPC model.
-
-Has Double Precision Floating Point
------------------------------------
-
-The macro PPC_HAS_DOUBLE is set to 1 to indicate that the PowerPC model
-has support for double precision floating point numbers. This is
-important because the floating point registers need only be four bytes
-wide (not eight) if double precision is not supported.
-
-Critical Interrupts
--------------------
-
-The macro PPC_HAS_RFCI is set to 1 to indicate that the PowerPC model
-has the Critical Interrupt capability as defined by the IBM 403 models.
-
-Use Multiword Load/Store Instructions
--------------------------------------
-
-The macro PPC_USE_MULTIPLE is set to 1 to indicate that multiword load and
-store instructions should be used to perform context switch operations.
-The relative efficiency of multiword load and store instructions versus
-an equivalent set of single word load and store instructions varies based
-upon the PowerPC model.
-
-Instruction Cache Size
-----------------------
-
-The macro PPC_I_CACHE is set to the size in bytes of the instruction cache.
-
-Data Cache Size
----------------
-
-The macro PPC_D_CACHE is set to the size in bytes of the data cache.
-
-Debug Model
------------
-
-The macro PPC_DEBUG_MODEL is set to indicate the debug support features
-present in this CPU model. The following debug support feature sets
-are currently supported:
-
-*``PPC_DEBUG_MODEL_STANDARD``*
- indicates that the single-step trace enable (SE) and branch trace
- enable (BE) bits in the MSR are supported by this CPU model.
-
-*``PPC_DEBUG_MODEL_SINGLE_STEP_ONLY``*
- indicates that only the single-step trace enable (SE) bit in the MSR
- is supported by this CPU model.
-
-*``PPC_DEBUG_MODEL_IBM4xx``*
- indicates that the debug exception enable (DE) bit in the MSR is supported
- by this CPU model. At this time, this particular debug feature set
- has only been seen in the IBM 4xx series.
-
-Low Power Model
-~~~~~~~~~~~~~~~
-
-The macro PPC_LOW_POWER_MODE is set to indicate the low power model
-supported by this CPU model. The following low power modes are currently
-supported.
-
-*``PPC_LOW_POWER_MODE_NONE``*
- indicates that this CPU model has no low power mode support.
-
-*``PPC_LOW_POWER_MODE_STANDARD``*
- indicates that this CPU model follows the low power model defined for
- the PPC603e.
-
-Multilibs
-=========
-
-The following multilibs are available:
-
-# ``.``: 32-bit PowerPC with FPU
-
-# ``nof``: 32-bit PowerPC with software floating point support
-
-# ``m403``: Instruction set for PPC403 with FPU
-
-# ``m505``: Instruction set for MPC505 with FPU
-
-# ``m603e``: Instruction set for MPC603e with FPU
-
-# ``m603e/nof``: Instruction set for MPC603e with software floating
- point support
-
-# ``m604``: Instruction set for MPC604 with FPU
-
-# ``m604/nof``: Instruction set for MPC604 with software floating point
- support
-
-# ``m860``: Instruction set for MPC860 with FPU
-
-# ``m7400``: Instruction set for MPC7500 with FPU
-
-# ``m7400/nof``: Instruction set for MPC7500 with software floating
- point support
-
-# ``m8540``: Instruction set for e200, e500 and e500v2 cores with
- single-precision FPU and SPE
-
-# ``m8540/gprsdouble``: Instruction set for e200, e500 and e500v2 cores
- with double-precision FPU and SPE
-
-# ``m8540/nof/nospe``: Instruction set for e200, e500 and e500v2 cores
- with software floating point support and no SPE
-
-# ``me6500/m32``: 32-bit instruction set for e6500 core with FPU and
- AltiVec
-
-# ``me6500/m32/nof/noaltivec``: 32-bit instruction set for e6500 core
- with software floating point support and no AltiVec
-
-Calling Conventions
-===================
-
-RTEMS supports the Embedded Application Binary Interface (EABI)
-calling convention. Documentation for EABI is available by sending
-a message with a subject line of "EABI" to eabi@goth.sis.mot.com.
-
-Programming Model
------------------
-
-This section discusses the programming model for the
-PowerPC architecture.
-
-Non-Floating Point Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The PowerPC architecture defines thirty-two non-floating point registers
-directly visible to the programmer. In thirty-two bit implementations, each
-register is thirty-two bits wide. In sixty-four bit implementations, each
-register is sixty-four bits wide.
-
-These registers are referred to as ``gpr0`` to ``gpr31``.
-
-Some of the registers serve defined roles in the EABI programming model.
-The following table describes the role of each of these registers:
-.. code:: c
-
- +---------------+----------------+------------------------------+
- | Register Name | Alternate Name | Description |
- +---------------+----------------+------------------------------+
- | r1 | sp | stack pointer |
- +---------------+----------------+------------------------------+
- | | | global pointer to the Small |
- | r2 | na | Constant Area (SDA2) |
- +---------------+----------------+------------------------------+
- | r3 - r12 | na | parameter and result passing |
- +---------------+----------------+------------------------------+
- | | | global pointer to the Small |
- | r13 | na | Data Area (SDA) |
- +---------------+----------------+------------------------------+
-
-Floating Point Registers
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The PowerPC architecture includes thirty-two, sixty-four bit
-floating point registers. All PowerPC floating point instructions
-interpret these registers as 32 double precision floating point registers,
-regardless of whether the processor has 64-bit or 32-bit implementation.
-
-The floating point status and control register (fpscr) records exceptions
-and the type of result generated by floating-point operations.
-Additionally, it controls the rounding mode of operations and allows the
-reporting of floating exceptions to be enabled or disabled.
-
-Special Registers
-~~~~~~~~~~~~~~~~~
-
-The PowerPC architecture includes a number of special registers
-which are critical to the programming model:
-
-*Machine State Register*
- The MSR contains the processor mode, power management mode, endian mode,
- exception information, privilege level, floating point available and
- floating point excepiton mode, address translation information and
- the exception prefix.
-
-*Link Register*
- The LR contains the return address after a function call. This register
- must be saved before a subsequent subroutine call can be made. The
- use of this register is discussed further in the *Call and Return
- Mechanism* section below.
-
-*Count Register*
- The CTR contains the iteration variable for some loops. It may also be used
- for indirect function calls and jumps.
-
-Call and Return Mechanism
--------------------------
-
-The PowerPC architecture supports a simple yet effective call
-and return mechanism. A subroutine is invoked
-via the "branch and link" (``bl``) and
-"brank and link absolute" (``bla``)
-instructions. This instructions place the return address
-in the Link Register (LR). The callee returns to the caller by
-executing a "branch unconditional to the link register" (``blr``)
-instruction. Thus the callee returns to the caller via a jump
-to the return address which is stored in the LR.
-
-The previous contents of the LR are not automatically saved
-by either the ``bl`` or ``bla``. It is the responsibility
-of the callee to save the contents of the LR before invoking
-another subroutine. If the callee invokes another subroutine,
-it must restore the LR before executing the ``blr`` instruction
-to return to the caller.
-
-It is important to note that the PowerPC subroutine
-call and return mechanism does not automatically save and
-restore any registers.
-
-The LR may be accessed as special purpose register 8 (``SPR8``) using the
-"move from special register" (``mfspr``) and
-"move to special register" (``mtspr``) instructions.
-
-Calling Mechanism
------------------
-
-All RTEMS directives are invoked using the regular
-PowerPC EABI calling convention via the ``bl`` or``bla`` instructions.
-
-Register Usage
---------------
-
-As discussed above, the call instruction does not
-automatically save any registers. It is the responsibility
-of the callee to save and restore any registers which must be preserved
-across subroutine calls. The callee is responsible for saving
-callee-preserved registers to the program stack and restoring them
-before returning to the caller.
-
-Parameter Passing
------------------
-
-RTEMS assumes that arguments are placed in the
-general purpose registers with the first argument in
-register 3 (``r3``), the second argument in general purpose
-register 4 (``r4``), and so forth until the seventh
-argument is in general purpose register 10 (``r10``).
-If there are more than seven arguments, then subsequent arguments
-are placed on the program stack. The following pseudo-code
-illustrates the typical sequence used to call a RTEMS directive
-with three (3) arguments:
-.. code:: c
-
- load third argument into r5
- load second argument into r4
- load first argument into r3
- invoke directive
-
-Memory Model
-============
-
-Flat Memory Model
------------------
-
-The PowerPC architecture supports a variety of memory models.
-RTEMS supports the PowerPC using a flat memory model with
-paging disabled. In this mode, the PowerPC automatically
-converts every address from a logical to a physical address
-each time it is used. The PowerPC uses information provided
-in the Block Address Translation (BAT) to convert these addresses.
-
-Implementations of the PowerPC architecture may be thirty-two or sixty-four bit.
-The PowerPC architecture supports a flat thirty-two or sixty-four bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes) in thirty-two bit implementations or to 0xFFFFFFFFFFFFFFFF
-in sixty-four bit implementations. Each address is represented
-by either a thirty-two bit or sixty-four bit value and is byte addressable.
-The address may be used to reference a single byte, half-word
-(2-bytes), word (4 bytes), or in sixty-four bit implementations a
-doubleword (8 bytes). Memory accesses within the address space are
-performed in big or little endian fashion by the PowerPC based
-upon the current setting of the Little-endian mode enable bit (LE)
-in the Machine State Register (MSR). While the processor is in
-big endian mode, memory accesses which are not properly aligned
-generate an "alignment exception" (vector offset 0x00600). In
-little endian mode, the PowerPC architecture does not require
-the processor to generate alignment exceptions.
-
-The following table lists the alignment requirements for a variety
-of data accesses:
-
-.. code:: c
-
- +--------------+-----------------------+
- | Data Type | Alignment Requirement |
- +--------------+-----------------------+
- | byte | 1 |
- | half-word | 2 |
- | word | 4 |
- | doubleword | 8 |
- +--------------+-----------------------+
-
-Doubleword load and store operations are only available in
-PowerPC CPU models which are sixty-four bit implementations.
-
-RTEMS does not directly support any PowerPC Memory Management
-Units, therefore, virtual memory or segmentation systems
-involving the PowerPC are not supported.
-
-.. COMMENT: COPYRIGHT (c) 1989-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Interrupt Processing
-====================
-
-Although RTEMS hides many of the processor dependent
-details of interrupt processing, it is important to understand
-how the RTEMS interrupt manager is mapped onto the processor’s
-unique architecture. Discussed in this chapter are the PowerPC’s
-interrupt response and control mechanisms as they pertain to
-RTEMS.
-
-RTEMS and associated documentation uses the terms interrupt and vector.
-In the PowerPC architecture, these terms correspond to exception and
-exception handler, respectively. The terms will be used interchangeably
-in this manual.
-
-Synchronous Versus Asynchronous Exceptions
-------------------------------------------
-
-In the PowerPC architecture exceptions can be either precise or
-imprecise and either synchronous or asynchronous. Asynchronous
-exceptions occur when an external event interrupts the processor.
-Synchronous exceptions are caused by the actions of an
-instruction. During an exception SRR0 is used to calculate where
-instruction processing should resume. All instructions prior to
-the resume instruction will have completed execution. SRR1 is used to
-store the machine status.
-
-There are two asynchronous nonmaskable, highest-priority exceptions
-system reset and machine check. There are two asynchrononous maskable
-low-priority exceptions external interrupt and decrementer. Nonmaskable
-execptions are never delayed, therefore if two nonmaskable, asynchronous
-exceptions occur in immediate succession, the state information saved by
-the first exception may be overwritten when the subsequent exception occurs.
-
-The PowerPC arcitecure defines one imprecise exception, the imprecise
-floating point enabled exception. All other synchronous exceptions are
-precise. The synchronization occuring during asynchronous precise
-exceptions conforms to the requirements for context synchronization.
-
-Vectoring of Interrupt Handler
-------------------------------
-
-Upon determining that an exception can be taken the PowerPC automatically
-performs the following actions:
-
-- an instruction address is loaded into SRR0
-
-- bits 33-36 and 42-47 of SRR1 are loaded with information
- specific to the exception.
-
-- bits 0-32, 37-41, and 48-63 of SRR1 are loaded with corresponding
- bits from the MSR.
-
-- the MSR is set based upon the exception type.
-
-- instruction fetch and execution resumes, using the new MSR value, at a location specific to the execption type.
-
-If the interrupt handler was installed as an RTEMS
-interrupt handler, then upon receipt of the interrupt, the
-processor passes control to the RTEMS interrupt handler which
-performs the following actions:
-
-- saves the state of the interrupted task on it’s stack,
-
-- saves all registers which are not normally preserved
- by the calling sequence so the user’s interrupt service
- routine can be written in a high-level language.
-
-- if this is the outermost (i.e. non-nested) interrupt,
- then the RTEMS interrupt handler switches from the current stack
- to the interrupt stack,
-
-- enables exceptions,
-
-- invokes the vectors to a user interrupt service routine (ISR).
-
-Asynchronous interrupts are ignored while exceptions are
-disabled. Synchronous interrupts which occur while are
-disabled result in the CPU being forced into an error mode.
-
-A nested interrupt is processed similarly with the
-exception that the current stack need not be switched to the
-interrupt stack.
-
-Interrupt Levels
-----------------
-
-The PowerPC architecture supports only a single external
-asynchronous interrupt source. This interrupt source
-may be enabled and disabled via the External Interrupt Enable (EE)
-bit in the Machine State Register (MSR). Thus only two level (enabled
-and disabled) of external device interrupt priorities are
-directly supported by the PowerPC architecture.
-
-Some PowerPC implementations include a Critical Interrupt capability
-which is often used to receive interrupts from high priority external
-devices.
-
-The RTEMS interrupt level mapping scheme for the PowerPC is not
-a numeric level as on most RTEMS ports. It is a bit mapping in
-which the least three significiant bits of the interrupt level
-are mapped directly to the enabling of specific interrupt
-sources as follows:
-
-*Critical Interrupt*
- Setting bit 0 (the least significant bit) of the interrupt level
- enables the Critical Interrupt source, if it is available on this
- CPU model.
-
-*Machine Check*
- Setting bit 1 of the interrupt level enables Machine Check execptions.
-
-*External Interrupt*
- Setting bit 2 of the interrupt level enables External Interrupt execptions.
-
-All other bits in the RTEMS task interrupt level are ignored.
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture performs the
-following actions:
-
-- places the error code in r3, and
-
-- executes a trap instruction which results in a Program Exception.
-
-If the Program Exception returns, then the following actions are performed:
-
-- disables all processor exceptions by loading a 0 into the MSR, and
-
-- goes into an infinite loop to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is supported. Available platforms are the Freescale QorIQ P series (e.g.
-P1020) and T series (e.g. T2080, T4240).
-
-Thread-Local Storage
-====================
-
-Thread-local storage is supported.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-An RTEMS based application is initiated or
-re-initiated when the PowerPC processor is reset. The PowerPC
-architecture defines a Reset Exception, but leaves the
-details of the CPU state as implementation specific. Please
-refer to the User’s Manual for the CPU model in question.
-
-In general, at power-up the PowerPC begin execution at address
-0xFFF00100 in supervisor mode with all exceptions disabled. For
-soft resets, the CPU will vector to either 0xFFF00100 or 0x00000100
-depending upon the setting of the Exception Prefix bit in the MSR.
-If during a soft reset, a Machine Check Exception occurs, then the
-CPU may execute a hard reset.
-
-Processor Initialization
-------------------------
-
-If this PowerPC implementation supports on-chip caching
-and this is to be utilized, then it should be enabled during the
-reset application initialization code. On-chip caching has been
-observed to prevent some emulators from working properly, so it
-may be necessary to run with caching disabled to use these emulators.
-
-In addition to the requirements described in the*Board Support Packages* chapter of the RTEMS C
-Applications User’s Manual for the reset code
-which is executed before the call to ``rtems_initialize_executive``,
-the PowrePC version has the following specific requirements:
-
-- Must leave the PR bit of the Machine State Register (MSR) set
- to 0 so the PowerPC remains in the supervisor state.
-
-- Must set stack pointer (sp or r1) such that a minimum stack
- size of MINIMUM_STACK_SIZE bytes is provided for the RTEMS initialization
- sequence.
-
-- Must disable all external interrupts (i.e. clear the EI (EE)
- bit of the machine state register).
-
-- Must enable traps so window overflow and underflow
- conditions can be properly handled.
-
-- Must initialize the PowerPC’s initial Exception Table with default
- handlers.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-SuperH Specific Information
-###########################
-
-This chapter discusses the SuperH architecture dependencies
-in this port of RTEMS. The SuperH family has a wide variety
-of implementations by a wide range of vendors. Consequently,
-there are many, many CPU models within it.
-
-**Architecture Documents**
-
-For information on the SuperH architecture,
-refer to the following documents available from VENDOR
-(:file:`http//www.XXX.com/`):
-
-- *SuperH Family Reference, VENDOR, PART NUMBER*.
-
-CPU Model Dependent Features
-============================
-
-This chapter presents the set of features which vary
-across SuperH implementations and are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/sh/sh.h`` based upon the particular CPU
-model specified on the compilation command line.
-
-Another Optional Feature
-------------------------
-
-The macro XXX
-
-Calling Conventions
-===================
-
-Calling Mechanism
------------------
-
-All RTEMS directives are invoked using a ``XXX``
-instruction and return to the user application via the``XXX`` instruction.
-
-Register Usage
---------------
-
-The SH1 has 16 general registers (r0..r15).
-
-- r0..r3 used as general volatile registers
-
-- r4..r7 used to pass up to 4 arguments to functions, arguments
- above 4 are
- passed via the stack)
-
-- r8..13 caller saved registers (i.e. push them to the stack if you
- need them inside of a function)
-
-- r14 frame pointer
-
-- r15 stack pointer
-
-Parameter Passing
------------------
-
-XXX
-
-Memory Model
-============
-
-Flat Memory Model
------------------
-
-The SuperH family supports a flat 32-bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes). Each address is represented by a 32-bit value and
-is byte addressable. The address may be used to reference a
-single byte, word (2-bytes), or long word (4 bytes). Memory
-accesses within this address space are performed in big endian
-fashion by the processors in this family.
-
-Some of the SuperH family members support virtual memory and
-segmentation. RTEMS does not support virtual memory or
-segmentation on any of the SuperH family members. It is the
-responsibility of the BSP to initialize the mapping for
-a flat memory model.
-
-Interrupt Processing
-====================
-
-Although RTEMS hides many of the processor dependent
-details of interrupt processing, it is important to understand
-how the RTEMS interrupt manager is mapped onto the processor’s
-unique architecture. Discussed in this chapter are the MIPS’s
-interrupt response and control mechanisms as they pertain to
-RTEMS.
-
-Vectoring of an Interrupt Handler
----------------------------------
-
-Upon receipt of an interrupt the XXX family
-members with separate interrupt stacks automatically perform the
-following actions:
-
-- TBD
-
-A nested interrupt is processed similarly by these
-CPU models with the exception that only a single ISF is placed
-on the interrupt stack and the current stack need not be
-switched.
-
-Interrupt Levels
-----------------
-
-TBD
-
-Default Fatal Error Processing
-==============================
-
-The default fatal error handler for this architecture disables processor
-interrupts, places the error code in *XXX*, and executes a ``XXX``
-instruction to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is not implemented.
-
-Board Support Packages
-======================
-
-System Reset
-------------
-
-An RTEMS based application is initiated or
-re-initiated when the processor is reset. When the
-processor is reset, it performs the following actions:
-
-- TBD
-
-Processor Initialization
-------------------------
-
-TBD
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-SPARC Specific Information
-##########################
-
-The Real Time Executive for Multiprocessor Systems
-(RTEMS) is designed to be portable across multiple processor
-architectures. However, the nature of real-time systems makes
-it essential that the application designer understand certain
-processor dependent implementation details. These processor
-dependencies include calling convention, board support package
-issues, interrupt processing, exact RTEMS memory requirements,
-performance data, header files, and the assembly language
-interface to the executive.
-
-This document discusses the SPARC architecture dependencies in this
-port of RTEMS. This architectural port is for SPARC Version 7 and
-8. Implementations for SPARC V9 are in the sparc64 target.
-
-It is highly recommended that the SPARC RTEMS
-application developer obtain and become familiar with the
-documentation for the processor being used as well as the
-specification for the revision of the SPARC architecture which
-corresponds to that processor.
-
-**SPARC Architecture Documents**
-
-For information on the SPARC architecture, refer to
-the following documents available from SPARC International, Inc.
-(http://www.sparc.com):
-
-- SPARC Standard Version 7.
-
-- SPARC Standard Version 8.
-
-**ERC32 Specific Information**
-
-The European Space Agency’s ERC32 is a three chip
-computing core implementing a SPARC V7 processor and associated
-support circuitry for embedded space applications. The integer
-and floating-point units (90C601E & 90C602E) are based on the
-Cypress 7C601 and 7C602, with additional error-detection and
-recovery functions. The memory controller (MEC) implements
-system support functions such as address decoding, memory
-interface, DMA interface, UARTs, timers, interrupt control,
-write-protection, memory reconfiguration and error-detection.
-The core is designed to work at 25MHz, but using space qualified
-memories limits the system frequency to around 15 MHz, resulting
-in a performance of 10 MIPS and 2 MFLOPS.
-
-Information on the ERC32 and a number of development
-support tools, such as the SPARC Instruction Simulator (SIS),
-are freely available on the Internet. The following documents
-and SIS are available via anonymous ftp or pointing your web
-browser at ftp://ftp.estec.esa.nl/pub/ws/wsd/erc32.
-
-- ERC32 System Design Document
-
-- MEC Device Specification
-
-Additionally, the SPARC RISC User’s Guide from Matra
-MHS documents the functionality of the integer and floating
-point units including the instruction set information. To
-obtain this document as well as ERC32 components and VHDL models
-contact:
-.. code:: c
-
- Matra MHS SA
- 3 Avenue du Centre, BP 309,
- 78054 St-Quentin-en-Yvelines,
- Cedex, France
- VOICE: +31-1-30607087
- FAX: +31-1-30640693
-
-Amar Guennon (amar.guennon@matramhs.fr) is familiar with the ERC32.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-CPU Model Dependent Features
-============================
-
-Microprocessors are generally classified into
-families with a variety of CPU models or implementations within
-that family. Within a processor family, there is a high level
-of binary compatibility. This family may be based on either an
-architectural specification or on maintaining compatibility with
-a popular processor. Recent microprocessor families such as the
-SPARC or PowerPC are based on an architectural specification
-which is independent or any particular CPU model or
-implementation. Older families such as the M68xxx and the iX86
-evolved as the manufacturer strived to produce higher
-performance processor models which maintained binary
-compatibility with older models.
-
-RTEMS takes advantage of the similarity of the
-various models within a CPU family. Although the models do vary
-in significant ways, the high level of compatibility makes it
-possible to share the bulk of the CPU dependent executive code
-across the entire family.
-
-CPU Model Feature Flags
------------------------
-
-Each processor family supported by RTEMS has a
-list of features which vary between CPU models
-within a family. For example, the most common model dependent
-feature regardless of CPU family is the presence or absence of a
-floating point unit or coprocessor. When defining the list of
-features present on a particular CPU model, one simply notes
-that floating point hardware is or is not present and defines a
-single constant appropriately. Conditional compilation is
-utilized to include the appropriate source code for this CPU
-model’s feature set. It is important to note that this means
-that RTEMS is thus compiled using the appropriate feature set
-and compilation flags optimal for this CPU model used. The
-alternative would be to generate a binary which would execute on
-all family members using only the features which were always
-present.
-
-This section presents the set of features which vary
-across SPARC implementations and are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file
-cpukit/score/cpu/sparc/sparc.h based upon the particular CPU
-model defined on the compilation command line.
-
-CPU Model Name
-~~~~~~~~~~~~~~
-
-The macro CPU_MODEL_NAME is a string which designates
-the name of this CPU model. For example, for the European Space
-Agency’s ERC32 SPARC model, this macro is set to the string
-"erc32".
-
-Floating Point Unit
-~~~~~~~~~~~~~~~~~~~
-
-The macro SPARC_HAS_FPU is set to 1 to indicate that
-this CPU model has a hardware floating point unit and 0
-otherwise.
-
-Bitscan Instruction
-~~~~~~~~~~~~~~~~~~~
-
-The macro SPARC_HAS_BITSCAN is set to 1 to indicate
-that this CPU model has the bitscan instruction. For example,
-this instruction is supported by the Fujitsu SPARClite family.
-
-Number of Register Windows
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to
-indicate the number of register window sets implemented by this
-CPU model. The SPARC architecture allows a for a maximum of
-thirty-two register window sets although most implementations
-only include eight.
-
-Low Power Mode
-~~~~~~~~~~~~~~
-
-The macro SPARC_HAS_LOW_POWER_MODE is set to one to
-indicate that this CPU model has a low power mode. If low power
-is enabled, then there must be CPU model specific implementation
-of the IDLE task in cpukit/score/cpu/sparc/cpu.c. The low
-power mode IDLE task should be of the form:
-.. code:: c
-
- while ( TRUE ) {
- enter low power mode
- }
-
-The code required to enter low power mode is CPU model specific.
-
-CPU Model Implementation Notes
-------------------------------
-
-The ERC32 is a custom SPARC V7 implementation based on the Cypress 601/602
-chipset. This CPU has a number of on-board peripherals and was developed by
-the European Space Agency to target space applications. RTEMS currently
-provides support for the following peripherals:
-
-- UART Channels A and B
-
-- General Purpose Timer
-
-- Real Time Clock
-
-- Watchdog Timer (so it can be disabled)
-
-- Control Register (so powerdown mode can be enabled)
-
-- Memory Control Register
-
-- Interrupt Control
-
-The General Purpose Timer and Real Time Clock Timer provided with the ERC32
-share the Timer Control Register. Because the Timer Control Register is write
-only, we must mirror it in software and insure that writes to one timer do not
-alter the current settings and status of the other timer. Routines are
-provided in erc32.h which promote the view that the two timers are completely
-independent. By exclusively using these routines to access the Timer Control
-Register, the application can view the system as having a General Purpose
-Timer Control Register and a Real Time Clock Timer Control Register
-rather than the single shared value.
-
-The RTEMS Idle thread take advantage of the low power mode provided by the
-ERC32. Low power mode is entered during idle loops and is enabled at
-initialization time.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Calling Conventions
-===================
-
-Each high-level language compiler generates subroutine entry and exit code
-based upon a set of rules known as the application binary interface (ABI)
-calling convention. These rules address the following issues:
-
-- register preservation and usage
-
-- parameter passing
-
-- call and return mechanism
-
-An ABI calling convention is of importance when interfacing to subroutines
-written in another language either assembly or high-level. It determines also
-the set of registers to be saved or restored during a context switch and
-interrupt processing.
-
-The ABI relevant for RTEMS on SPARC is defined by SYSTEM V APPLICATION BINARY
-INTERFACE, SPARC Processor Supplement, Third Edition.
-
-Programming Model
------------------
-
-This section discusses the programming model for the
-SPARC architecture.
-
-Non-Floating Point Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The SPARC architecture defines thirty-two
-non-floating point registers directly visible to the programmer.
-These are divided into four sets:
-
-- input registers
-
-- local registers
-
-- output registers
-
-- global registers
-
-Each register is referred to by either two or three
-names in the SPARC reference manuals. First, the registers are
-referred to as r0 through r31 or with the alternate notation
-r[0] through r[31]. Second, each register is a member of one of
-the four sets listed above. Finally, some registers have an
-architecturally defined role in the programming model which
-provides an alternate name. The following table describes the
-mapping between the 32 registers and the register sets:
-
-.. code:: c
-
- +-----------------+----------------+------------------+
- | Register Number | Register Names | Description |
- +-----------------+----------------+------------------+
- | 0 - 7 | g0 - g7 | Global Registers |
- +-----------------+----------------+------------------+
- | 8 - 15 | o0 - o7 | Output Registers |
- +-----------------+----------------+------------------+
- | 16 - 23 | l0 - l7 | Local Registers |
- +-----------------+----------------+------------------+
- | 24 - 31 | i0 - i7 | Input Registers |
- +-----------------+----------------+------------------+
-
-As mentioned above, some of the registers serve
-defined roles in the programming model. The following table
-describes the role of each of these registers:
-
-.. code:: c
-
- +---------------+----------------+----------------------+
- | Register Name | Alternate Name | Description |
- +---------------+----------------+----------------------+
- | g0 | na | reads return 0 |
- | | | writes are ignored |
- +---------------+----------------+----------------------+
- | o6 | sp | stack pointer |
- +---------------+----------------+----------------------+
- | i6 | fp | frame pointer |
- +---------------+----------------+----------------------+
- | i7 | na | return address |
- +---------------+----------------+----------------------+
-
-The registers g2 through g4 are reserved for applications. GCC uses them as
-volatile registers by default. So they are treated like volatile registers in
-RTEMS as well.
-
-The register g6 is reserved for the operating system and contains the address
-of the per-CPU control block of the current processor. This register is
-initialized during system start and then remains unchanged. It is not
-saved/restored by the context switch or interrupt processing code.
-
-The register g7 is reserved for the operating system and contains the thread
-pointer used for thread-local storage (TLS) as mandated by the SPARC ABI.
-
-Floating Point Registers
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The SPARC V7 architecture includes thirty-two,
-thirty-two bit registers. These registers may be viewed as
-follows:
-
-- 32 single precision floating point or integer registers
- (f0, f1, ... f31)
-
-- 16 double precision floating point registers (f0, f2,
- f4, ... f30)
-
-- 8 extended precision floating point registers (f0, f4,
- f8, ... f28)
-
-The floating point status register (FSR) specifies
-the behavior of the floating point unit for rounding, contains
-its condition codes, version specification, and trap information.
-
-According to the ABI all floating point registers and the floating point status
-register (FSR) are volatile. Thus the floating point context of a thread is the
-empty set. The rounding direction is a system global state and must not be
-modified by threads.
-
-A queue of the floating point instructions which have
-started execution but not yet completed is maintained. This
-queue is needed to support the multiple cycle nature of floating
-point operations and to aid floating point exception trap
-handlers. Once a floating point exception has been encountered,
-the queue is frozen until it is emptied by the trap handler.
-The floating point queue is loaded by launching instructions.
-It is emptied normally when the floating point completes all
-outstanding instructions and by floating point exception
-handlers with the store double floating point queue (stdfq)
-instruction.
-
-Special Registers
-~~~~~~~~~~~~~~~~~
-
-The SPARC architecture includes two special registers
-which are critical to the programming model: the Processor State
-Register (psr) and the Window Invalid Mask (wim). The psr
-contains the condition codes, processor interrupt level, trap
-enable bit, supervisor mode and previous supervisor mode bits,
-version information, floating point unit and coprocessor enable
-bits, and the current window pointer (cwp). The cwp field of
-the psr and wim register are used to manage the register windows
-in the SPARC architecture. The register windows are discussed
-in more detail below.
-
-Register Windows
-----------------
-
-The SPARC architecture includes the concept of
-register windows. An overly simplistic way to think of these
-windows is to imagine them as being an infinite supply of
-"fresh" register sets available for each subroutine to use. In
-reality, they are much more complicated.
-
-The save instruction is used to obtain a new register
-window. This instruction decrements the current window pointer,
-thus providing a new set of registers for use. This register
-set includes eight fresh local registers for use exclusively by
-this subroutine. When done with a register set, the restore
-instruction increments the current window pointer and the
-previous register set is once again available.
-
-The two primary issues complicating the use of
-register windows are that (1) the set of register windows is
-finite, and (2) some registers are shared between adjacent
-registers windows.
-
-Because the set of register windows is finite, it is
-possible to execute enough save instructions without
-corresponding restore’s to consume all of the register windows.
-This is easily accomplished in a high level language because
-each subroutine typically performs a save instruction upon
-entry. Thus having a subroutine call depth greater than the
-number of register windows will result in a window overflow
-condition. The window overflow condition generates a trap which
-must be handled in software. The window overflow trap handler
-is responsible for saving the contents of the oldest register
-window on the program stack.
-
-Similarly, the subroutines will eventually complete
-and begin to perform restore’s. If the restore results in the
-need for a register window which has previously been written to
-memory as part of an overflow, then a window underflow condition
-results. Just like the window overflow, the window underflow
-condition must be handled in software by a trap handler. The
-window underflow trap handler is responsible for reloading the
-contents of the register window requested by the restore
-instruction from the program stack.
-
-The Window Invalid Mask (wim) and the Current Window
-Pointer (cwp) field in the psr are used in conjunction to manage
-the finite set of register windows and detect the window
-overflow and underflow conditions. The cwp contains the index
-of the register window currently in use. The save instruction
-decrements the cwp modulo the number of register windows.
-Similarly, the restore instruction increments the cwp modulo the
-number of register windows. Each bit in the wim represents
-represents whether a register window contains valid information.
-The value of 0 indicates the register window is valid and 1
-indicates it is invalid. When a save instruction causes the cwp
-to point to a register window which is marked as invalid, a
-window overflow condition results. Conversely, the restore
-instruction may result in a window underflow condition.
-
-Other than the assumption that a register window is
-always available for trap (i.e. interrupt) handlers, the SPARC
-architecture places no limits on the number of register windows
-simultaneously marked as invalid (i.e. number of bits set in the
-wim). However, RTEMS assumes that only one register window is
-marked invalid at a time (i.e. only one bit set in the wim).
-This makes the maximum possible number of register windows
-available to the user while still meeting the requirement that
-window overflow and underflow conditions can be detected.
-
-The window overflow and window underflow trap
-handlers are a critical part of the run-time environment for a
-SPARC application. The SPARC architectural specification allows
-for the number of register windows to be any power of two less
-than or equal to 32. The most common choice for SPARC
-implementations appears to be 8 register windows. This results
-in the cwp ranging in value from 0 to 7 on most implementations.
-
-The second complicating factor is the sharing of
-registers between adjacent register windows. While each
-register window has its own set of local registers, the input
-and output registers are shared between adjacent windows. The
-output registers for register window N are the same as the input
-registers for register window ((N - 1) modulo RW) where RW is
-the number of register windows. An alternative way to think of
-this is to remember how parameters are passed to a subroutine on
-the SPARC. The caller loads values into what are its output
-registers. Then after the callee executes a save instruction,
-those parameters are available in its input registers. This is
-a very efficient way to pass parameters as no data is actually
-moved by the save or restore instructions.
-
-Call and Return Mechanism
--------------------------
-
-The SPARC architecture supports a simple yet
-effective call and return mechanism. A subroutine is invoked
-via the call (call) instruction. This instruction places the
-return address in the caller’s output register 7 (o7). After
-the callee executes a save instruction, this value is available
-in input register 7 (i7) until the corresponding restore
-instruction is executed.
-
-The callee returns to the caller via a jmp to the
-return address. There is a delay slot following this
-instruction which is commonly used to execute a restore
-instruction – if a register window was allocated by this
-subroutine.
-
-It is important to note that the SPARC subroutine
-call and return mechanism does not automatically save and
-restore any registers. This is accomplished via the save and
-restore instructions which manage the set of registers windows.
-
-In case a floating-point unit is supported, then floating-point return values
-appear in the floating-point registers. Single-precision values occupy %f0;
-double-precision values occupy %f0 and %f1. Otherwise, these are scratch
-registers. Due to this the hardware and software floating-point ABIs are
-incompatible.
-
-Calling Mechanism
------------------
-
-All RTEMS directives are invoked using the regular
-SPARC calling convention via the call instruction.
-
-Register Usage
---------------
-
-As discussed above, the call instruction does not
-automatically save any registers. The save and restore
-instructions are used to allocate and deallocate register
-windows. When a register window is allocated, the new set of
-local registers are available for the exclusive use of the
-subroutine which allocated this register set.
-
-Parameter Passing
------------------
-
-RTEMS assumes that arguments are placed in the
-caller’s output registers with the first argument in output
-register 0 (o0), the second argument in output register 1 (o1),
-and so forth. Until the callee executes a save instruction, the
-parameters are still visible in the output registers. After the
-callee executes a save instruction, the parameters are visible
-in the corresponding input registers. The following pseudo-code
-illustrates the typical sequence used to call a RTEMS directive
-with three (3) arguments:
-.. code:: c
-
- load third argument into o2
- load second argument into o1
- load first argument into o0
- invoke directive
-
-User-Provided Routines
-----------------------
-
-All user-provided routines invoked by RTEMS, such as
-user extensions, device drivers, and MPCI routines, must also
-adhere to these calling conventions.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Memory Model
-============
-
-A processor may support any combination of memory
-models ranging from pure physical addressing to complex demand
-paged virtual memory systems. RTEMS supports a flat memory
-model which ranges contiguously over the processor’s allowable
-address space. RTEMS does not support segmentation or virtual
-memory of any kind. The appropriate memory model for RTEMS
-provided by the targeted processor and related characteristics
-of that model are described in this chapter.
-
-Flat Memory Model
------------------
-
-The SPARC architecture supports a flat 32-bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes). Each address is represented by a 32-bit value and
-is byte addressable. The address may be used to reference a
-single byte, half-word (2-bytes), word (4 bytes), or doubleword
-(8 bytes). Memory accesses within this address space are
-performed in big endian fashion by the SPARC. Memory accesses
-which are not properly aligned generate a "memory address not
-aligned" trap (type number 7). The following table lists the
-alignment requirements for a variety of data accesses:
-
-.. code:: c
-
- +--------------+-----------------------+
- | Data Type | Alignment Requirement |
- +--------------+-----------------------+
- | byte | 1 |
- | half-word | 2 |
- | word | 4 |
- | doubleword | 8 |
- +--------------+-----------------------+
-
-Doubleword load and store operations must use a pair
-of registers as their source or destination. This pair of
-registers must be an adjacent pair of registers with the first
-of the pair being even numbered. For example, a valid
-destination for a doubleword load might be input registers 0 and
-1 (i0 and i1). The pair i1 and i2 would be invalid. \[NOTE:
-Some assemblers for the SPARC do not generate an error if an odd
-numbered register is specified as the beginning register of the
-pair. In this case, the assembler assumes that what the
-programmer meant was to use the even-odd pair which ends at the
-specified register. This may or may not have been a correct
-assumption.]
-
-RTEMS does not support any SPARC Memory Management
-Units, therefore, virtual memory or segmentation systems
-involving the SPARC are not supported.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Interrupt Processing
-====================
-
-Different types of processors respond to the
-occurrence of an interrupt in its own unique fashion. In
-addition, each processor type provides a control mechanism to
-allow for the proper handling of an interrupt. The processor
-dependent response to the interrupt modifies the current
-execution state and results in a change in the execution stream.
-Most processors require that an interrupt handler utilize some
-special control mechanisms to return to the normal processing
-stream. Although RTEMS hides many of the processor dependent
-details of interrupt processing, it is important to understand
-how the RTEMS interrupt manager is mapped onto the processor’s
-unique architecture. Discussed in this chapter are the SPARC’s
-interrupt response and control mechanisms as they pertain to
-RTEMS.
-
-RTEMS and associated documentation uses the terms
-interrupt and vector. In the SPARC architecture, these terms
-correspond to traps and trap type, respectively. The terms will
-be used interchangeably in this manual.
-
-Synchronous Versus Asynchronous Traps
--------------------------------------
-
-The SPARC architecture includes two classes of traps:
-synchronous and asynchronous. Asynchronous traps occur when an
-external event interrupts the processor. These traps are not
-associated with any instruction executed by the processor and
-logically occur between instructions. The instruction currently
-in the execute stage of the processor is allowed to complete
-although subsequent instructions are annulled. The return
-address reported by the processor for asynchronous traps is the
-pair of instructions following the current instruction.
-
-Synchronous traps are caused by the actions of an
-instruction. The trap stimulus in this case either occurs
-internally to the processor or is from an external signal that
-was provoked by the instruction. These traps are taken
-immediately and the instruction that caused the trap is aborted
-before any state changes occur in the processor itself. The
-return address reported by the processor for synchronous traps
-is the instruction which caused the trap and the following
-instruction.
-
-Vectoring of Interrupt Handler
-------------------------------
-
-Upon receipt of an interrupt the SPARC automatically
-performs the following actions:
-
-- disables traps (sets the ET bit of the psr to 0),
-
-- the S bit of the psr is copied into the Previous
- Supervisor Mode (PS) bit of the psr,
-
-- the cwp is decremented by one (modulo the number of
- register windows) to activate a trap window,
-
-- the PC and nPC are loaded into local register 1 and 2
- (l0 and l1),
-
-- the trap type (tt) field of the Trap Base Register (TBR)
- is set to the appropriate value, and
-
-- if the trap is not a reset, then the PC is written with
- the contents of the TBR and the nPC is written with TBR + 4. If
- the trap is a reset, then the PC is set to zero and the nPC is
- set to 4.
-
-Trap processing on the SPARC has two features which
-are noticeably different than interrupt processing on other
-architectures. First, the value of psr register in effect
-immediately before the trap occurred is not explicitly saved.
-Instead only reversible alterations are made to it. Second, the
-Processor Interrupt Level (pil) is not set to correspond to that
-of the interrupt being processed. When a trap occurs, ALL
-subsequent traps are disabled. In order to safely invoke a
-subroutine during trap handling, traps must be enabled to allow
-for the possibility of register window overflow and underflow
-traps.
-
-If the interrupt handler was installed as an RTEMS
-interrupt handler, then upon receipt of the interrupt, the
-processor passes control to the RTEMS interrupt handler which
-performs the following actions:
-
-- saves the state of the interrupted task on it’s stack,
-
-- insures that a register window is available for
- subsequent traps,
-
-- if this is the outermost (i.e. non-nested) interrupt,
- then the RTEMS interrupt handler switches from the current stack
- to the interrupt stack,
-
-- enables traps,
-
-- invokes the vectors to a user interrupt service routine (ISR).
-
-Asynchronous interrupts are ignored while traps are
-disabled. Synchronous traps which occur while traps are
-disabled result in the CPU being forced into an error mode.
-
-A nested interrupt is processed similarly with the
-exception that the current stack need not be switched to the
-interrupt stack.
-
-Traps and Register Windows
---------------------------
-
-One of the register windows must be reserved at all
-times for trap processing. This is critical to the proper
-operation of the trap mechanism in the SPARC architecture. It
-is the responsibility of the trap handler to insure that there
-is a register window available for a subsequent trap before
-re-enabling traps. It is likely that any high level language
-routines invoked by the trap handler (such as a user-provided
-RTEMS interrupt handler) will allocate a new register window.
-The save operation could result in a window overflow trap. This
-trap cannot be correctly processed unless (1) traps are enabled
-and (2) a register window is reserved for traps. Thus, the
-RTEMS interrupt handler insures that a register window is
-available for subsequent traps before enabling traps and
-invoking the user’s interrupt handler.
-
-Interrupt Levels
-----------------
-
-Sixteen levels (0-15) of interrupt priorities are
-supported by the SPARC architecture with level fifteen (15)
-being the highest priority. Level zero (0) indicates that
-interrupts are fully enabled. Interrupt requests for interrupts
-with priorities less than or equal to the current interrupt mask
-level are ignored. Level fifteen (15) is a non-maskable interrupt
-(NMI), which makes it unsuitable for standard usage since it can
-affect the real-time behaviour by interrupting critical sections
-and spinlocks. Disabling traps stops also the NMI interrupt from
-happening. It can however be used for power-down or other
-critical events.
-
-Although RTEMS supports 256 interrupt levels, the
-SPARC only supports sixteen. RTEMS interrupt levels 0 through
-15 directly correspond to SPARC processor interrupt levels. All
-other RTEMS interrupt levels are undefined and their behavior is
-unpredictable.
-
-Many LEON SPARC v7/v8 systems features an extended interrupt controller
-which adds an extra step of interrupt decoding to allow handling of
-interrupt 16-31. When such an extended interrupt is generated the CPU
-traps into a specific interrupt trap level 1-14 and software reads out from
-the interrupt controller which extended interrupt source actually caused the
-interrupt.
-
-Disabling of Interrupts by RTEMS
---------------------------------
-
-During the execution of directive calls, critical
-sections of code may be executed. When these sections are
-encountered, RTEMS disables interrupts to level fifteen (15)
-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 less than
-RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ
-Mhz ERC32 with zero wait states.
-These numbers will vary based the number of wait states and
-processor speed present on the target board.
-\[NOTE: The maximum period with interrupts disabled is hand calculated. This
-calculation was last performed for Release
-RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
-
-[NOTE: It is thought that the length of time at which
-the processor interrupt level is elevated to fifteen by RTEMS is
-not anywhere near as long as the length of time ALL traps are
-disabled as part of the "flush all register windows" operation.]
-
-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.
-
-Interrupts are disabled or enabled by performing a system call
-to the Operating System reserved software traps 9
-(SPARC_SWTRAP_IRQDIS) or 10 (SPARC_SWTRAP_IRQDIS). The trap is
-generated by the software trap (Ticc) instruction or indirectly
-by calling sparc_disable_interrupts() or sparc_enable_interrupts()
-functions. Disabling interrupts return the previous interrupt level
-(on trap entry) in register G1 and sets PSR.PIL to 15 to disable
-all maskable interrupts. The interrupt level can be restored by
-trapping into the enable interrupt handler with G1 containing the
-new interrupt level.
-
-Interrupt Stack
----------------
-
-The SPARC architecture does not provide for a
-dedicated interrupt stack. Thus by default, trap handlers would
-execute on the stack of the RTEMS task which they interrupted.
-This artificially inflates the stack requirements for each task
-since EVERY task stack would have to include enough space to
-account for the worst case interrupt stack requirements in
-addition to it’s own worst case usage. RTEMS addresses this
-problem on the SPARC by providing a dedicated interrupt stack
-managed by software.
-
-During system initialization, RTEMS allocates the
-interrupt stack from the Workspace Area. The amount of memory
-allocated for the interrupt stack is determined by the
-interrupt_stack_size field in the CPU Configuration Table. As
-part of processing a non-nested interrupt, RTEMS will switch to
-the interrupt stack before invoking the installed handler.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Default Fatal Error Processing
-==============================
-
-Upon detection of a fatal error by either the
-application or RTEMS the fatal error manager is invoked. The
-fatal error manager will invoke the user-supplied fatal error
-handlers. If no user-supplied handlers are configured, the
-RTEMS provided default fatal error handler is invoked. If the
-user-supplied fatal error handlers return to the executive the
-default fatal error handler is then invoked. This chapter
-describes the precise operations of the default fatal error
-handler.
-
-Default Fatal Error Handler Operations
---------------------------------------
-
-The default fatal error handler which is invoked by
-the fatal_error_occurred directive when there is no user handler
-configured or the user handler returns control to RTEMS.
-
-If the BSP has been configured with ``BSP_POWER_DOWN_AT_FATAL_HALT``
-set to true, the default handler will disable interrupts
-and enter power down mode. If power down mode is not available,
-it goes into an infinite loop to simulate a halt processor instruction.
-
-If ``BSP_POWER_DOWN_AT_FATAL_HALT`` is set to false, the default
-handler will place the value ``1`` in register ``g1``, the
-error source in register ``g2``, and the error code in register``g3``. It will then generate a system error which will
-hand over control to the debugger, simulator, etc.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is supported. Available platforms are the Cobham Gaisler GR712RC and
-GR740.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is supported.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Board Support Packages
-======================
-
-An RTEMS Board Support Package (BSP) must be designed
-to support a particular processor and target board combination.
-This chapter presents a discussion of SPARC specific BSP issues.
-For more information on developing a BSP, refer to the chapter
-titled Board Support Packages in the RTEMS
-Applications User’s Guide.
-
-System Reset
-------------
-
-An RTEMS based application is initiated or
-re-initiated when the SPARC processor is reset. When the SPARC
-is reset, the processor performs the following actions:
-
-- the enable trap (ET) of the psr is set to 0 to disable
- traps,
-
-- the supervisor bit (S) of the psr is set to 1 to enter
- supervisor mode, and
-
-- the PC is set 0 and the nPC is set to 4.
-
-The processor then begins to execute the code at
-location 0. It is important to note that all fields in the psr
-are not explicitly set by the above steps and all other
-registers retain their value from the previous execution mode.
-This is true even of the Trap Base Register (TBR) whose contents
-reflect the last trap which occurred before the reset.
-
-Processor Initialization
-------------------------
-
-It is the responsibility of the application’s
-initialization code to initialize the TBR and install trap
-handlers for at least the register window overflow and register
-window underflow conditions. Traps should be enabled before
-invoking any subroutines to allow for register window
-management. However, interrupts should be disabled by setting
-the Processor Interrupt Level (pil) field of the psr to 15.
-RTEMS installs it’s own Trap Table as part of initialization
-which is initialized with the contents of the Trap Table in
-place when the ``rtems_initialize_executive`` directive was invoked.
-Upon completion of executive initialization, interrupts are
-enabled.
-
-If this SPARC implementation supports on-chip caching
-and this is to be utilized, then it should be enabled during the
-reset application initialization code.
-
-In addition to the requirements described in the
-Board Support Packages chapter of the C
-Applications Users Manual for the reset code
-which is executed before the call to``rtems_initialize_executive``, the SPARC version has the following
-specific requirements:
-
-- Must leave the S bit of the status register set so that
- the SPARC remains in the supervisor state.
-
-- Must set stack pointer (sp) such that a minimum stack
- size of MINIMUM_STACK_SIZE bytes is provided for the``rtems_initialize_executive`` directive.
-
-- Must disable all external interrupts (i.e. set the pil
- to 15).
-
-- Must enable traps so window overflow and underflow
- conditions can be properly handled.
-
-- Must initialize the SPARC’s initial trap table with at
- least trap handlers for register window overflow and register
- window underflow.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-SPARC-64 Specific Information
-#############################
-
-This document discusses the SPARC Version 9 (aka SPARC-64, SPARC64 or SPARC V9)
-architecture dependencies in this port of RTEMS.
-
-The SPARC V9 architecture leaves a lot of undefined implemenation dependencies
-which are defined by the processor models. Consult the specific CPU model
-section in this document for additional documents covering the implementation
-dependent architectural features.
-
-**sun4u Specific Information**
-
-sun4u is the subset of the SPARC V9 implementations comprising the UltraSPARC I
-through UltraSPARC IV processors.
-
-The following documents were used in developing the SPARC-64 sun4u port:
-
-- UltraSPARC User’s Manual
- (http://www.sun.com/microelectronics/manuals/ultrasparc/802-7220-02.pdf)
-
-- UltraSPARC IIIi Processor (datasheets.chipdb.org/Sun/UltraSparc-IIIi.pdf)
-
-**sun4v Specific Information**
-
-sun4v is the subset of the SPARC V9 implementations comprising the
-UltraSPARC T1 or T2 processors.
-
-The following documents were used in developing the SPARC-64 sun4v port:
-
-- UltraSPARC Architecture 2005 Specification
- (http://opensparc-t1.sunsource.net/specs/UA2005-current-draft-P-EXT.pdf)
-
-- UltraSPARC T1 supplement to UltraSPARC Architecture 2005 Specification
- (http://opensparc-t1.sunsource.net/specs/UST1-UASuppl-current-draft-P-EXT.pdf)
-
-The defining feature that separates the sun4v architecture from its
-predecessor is the existence of a super-privileged hypervisor that
-is responsible for providing virtualized execution environments. The impact
-of the hypervisor on the real-time guarantees available with sun4v has not
-yet been determined.
-
-CPU Model Dependent Features
-============================
-
-CPU Model Feature Flags
------------------------
-
-This section presents the set of features which vary across
-SPARC-64 implementations and
-are of importance to RTEMS. The set of CPU model feature macros
-are defined in the file
-cpukit/score/cpu/sparc64/sparc64.h based upon the particular
-CPU model defined on the compilation command line.
-
-CPU Model Name
-~~~~~~~~~~~~~~
-
-The macro CPU MODEL NAME is a string which designates
-the name of this CPU model.
-For example, for the UltraSPARC T1 SPARC V9 model,
-this macro is set to the string "sun4v".
-
-Floating Point Unit
-~~~~~~~~~~~~~~~~~~~
-
-The macro SPARC_HAS_FPU is set to 1 to indicate that
-this CPU model has a hardware floating point unit and 0
-otherwise.
-
-Number of Register Windows
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to
-indicate the number of register window sets implemented by this
-CPU model. The SPARC architecture allows for a maximum of
-thirty-two register window sets although most implementations
-only include eight.
-
-CPU Model Implementation Notes
-------------------------------
-
-This section describes the implemenation dependencies of the
-CPU Models sun4u and sun4v of the SPARC V9 architecture.
-
-sun4u Notes
-~~~~~~~~~~~
-
-XXX
-
-sun4v Notes
------------
-
-XXX
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Calling Conventions
-===================
-
-Each high-level language compiler generates
-subroutine entry and exit code based upon a set of rules known
-as the compiler’s calling convention. These rules address the
-following issues:
-
-- register preservation and usage
-
-- parameter passing
-
-- call and return mechanism
-
-A compiler’s calling convention is of importance when
-interfacing to subroutines written in another language either
-assembly or high-level. Even when the high-level language and
-target processor are the same, different compilers may use
-different calling conventions. As a result, calling conventions
-are both processor and compiler dependent.
-
-The following document also provides some conventions on the
-global register usage in SPARC V9:
-http://developers.sun.com/solaris/articles/sparcv9abi.html
-
-Programming Model
------------------
-
-This section discusses the programming model for the
-SPARC architecture.
-
-Non-Floating Point Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The SPARC architecture defines thirty-two
-non-floating point registers directly visible to the programmer.
-These are divided into four sets:
-
-- input registers
-
-- local registers
-
-- output registers
-
-- global registers
-
-Each register is referred to by either two or three
-names in the SPARC reference manuals. First, the registers are
-referred to as r0 through r31 or with the alternate notation
-r[0] through r[31]. Second, each register is a member of one of
-the four sets listed above. Finally, some registers have an
-architecturally defined role in the programming model which
-provides an alternate name. The following table describes the
-mapping between the 32 registers and the register sets:
-
-.. code:: c
-
- +-----------------+----------------+------------------+
- | Register Number | Register Names | Description |
- +-----------------+----------------+------------------+
- | 0 - 7 | g0 - g7 | Global Registers |
- +-----------------+----------------+------------------+
- | 8 - 15 | o0 - o7 | Output Registers |
- +-----------------+----------------+------------------+
- | 16 - 23 | l0 - l7 | Local Registers |
- +-----------------+----------------+------------------+
- | 24 - 31 | i0 - i7 | Input Registers |
- +-----------------+----------------+------------------+
-
-As mentioned above, some of the registers serve
-defined roles in the programming model. The following table
-describes the role of each of these registers:
-
-.. code:: c
-
- +---------------+----------------+----------------------+
- | Register Name | Alternate Name | Description |
- +---------------+----------------+----------------------+
- | g0 | na | reads return 0 |
- | | | writes are ignored |
- +---------------+----------------+----------------------+
- | o6 | sp | stack pointer |
- +---------------+----------------+----------------------+
- | i6 | fp | frame pointer |
- +---------------+----------------+----------------------+
- | i7 | na | return address |
- +---------------+----------------+----------------------+
-
-Floating Point Registers
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The SPARC V9 architecture includes sixty-four,
-thirty-two bit registers. These registers may be viewed as
-follows:
-
-- 32 32-bit single precision floating point or integer registers
- (f0, f1, ... f31)
-
-- 32 64-bit double precision floating point registers (f0, f2,
- f4, ... f62)
-
-- 16 128-bit extended precision floating point registers (f0, f4,
- f8, ... f60)
-
-The floating point state register (fsr) specifies
-the behavior of the floating point unit for rounding, contains
-its condition codes, version specification, and trap information.
-
-Special Registers
-~~~~~~~~~~~~~~~~~
-
-The SPARC architecture includes a number of special registers:
-
-*``Ancillary State Registers (ASRs)``*
- The ancillary state registers (ASRs) are optional state registers that
- may be privileged or nonprivileged. ASRs 16-31 are implementation-
- dependent. The SPARC V9 ASRs include: y, ccr, asi, tick, pc, fprs.
- The sun4u ASRs include: pcr, pic, dcr, gsr, softint set, softint clr,
- softint, and tick cmpr. The sun4v ASRs include: pcr, pic, gsr, soft-
- int set, softint clr, softint, tick cmpr, stick, and stick cmpr.
-
-*``Processor State Register (pstate)``*
- The privileged pstate register contains control fields for the proces-
- sor’s current state. Its flag fields include the interrupt enable, privi-
- leged mode, and enable FPU.
-
-*``Processor Interrupt Level (pil)``*
- The PIL specifies the interrupt level above which interrupts will be
- accepted.
-
-*``Trap Registers``*
- The trap handling mechanism of the SPARC V9 includes a number of
- registers, including: trap program counter (tpc), trap next pc (tnpc),
- trap state (tstate), trap type (tt), trap base address (tba), and trap
- level (tl).
-
-*``Alternate Globals``*
- The AG bit of the pstate register provides access to an alternate set
- of global registers. On sun4v, the AG bit is replaced by the global
- level (gl) register, providing access to at least two and at most eight
- alternate sets of globals.
-
-*``Register Window registers``*
- A number of registers assist in register window management.
- These include the current window pointer (cwp), savable windows
- (cansave), restorable windows (canrestore), clean windows (clean-
- win), other windows (otherwin), and window state (wstate).
-
-Register Windows
-----------------
-
-The SPARC architecture includes the concept of
-register windows. An overly simplistic way to think of these
-windows is to imagine them as being an infinite supply of
-"fresh" register sets available for each subroutine to use. In
-reality, they are much more complicated.
-
-The save instruction is used to obtain a new register window.
-This instruction increments the current window pointer, thus
-providing a new set of registers for use. This register set
-includes eight fresh local registers for use exclusively by
-this subroutine. When done with a register set, the restore
-instruction decrements the current window pointer and the
-previous register set is once again available.
-
-The two primary issues complicating the use of register windows
-are that (1) the set of register windows is finite, and (2) some
-registers are shared between adjacent registers windows.
-
-Because the set of register windows is finite, it is
-possible to execute enough save instructions without
-corresponding restore’s to consume all of the register windows.
-This is easily accomplished in a high level language because
-each subroutine typically performs a save instruction upon
-entry. Thus having a subroutine call depth greater than the
-number of register windows will result in a window overflow
-condition. The window overflow condition generates a trap which
-must be handled in software. The window overflow trap handler
-is responsible for saving the contents of the oldest register
-window on the program stack.
-
-Similarly, the subroutines will eventually complete
-and begin to perform restore’s. If the restore results in the
-need for a register window which has previously been written to
-memory as part of an overflow, then a window underflow condition
-results. Just like the window overflow, the window underflow
-condition must be handled in software by a trap handler. The
-window underflow trap handler is responsible for reloading the
-contents of the register window requested by the restore
-instruction from the program stack.
-
-The cansave, canrestore, otherwin, and cwp are used in conjunction
-to manage the finite set of register windows and detect the window
-overflow and underflow conditions. The first three of these
-registers must satisfy the invariant cansave + canrestore + otherwin =
-nwindow - 2, where nwindow is the number of register windows.
-The cwp contains the index of the register window currently in use.
-RTEMS does not use the cleanwin and otherwin registers.
-
-The save instruction increments the cwp modulo the number of
-register windows, and if cansave is 0 then it also generates a
-window overflow. Similarly, the restore instruction decrements the
-cwp modulo the number of register windows, and if canrestore is 0 then it
-also generates a window underflow.
-
-Unlike with the SPARC model, the SPARC-64 port does not assume that
-a register window is available for a trap. The window overflow
-and underflow conditions are not detected without hardware generating
-the trap. (These conditions can be detected by reading the register window
-registers and doing some simple arithmetic.)
-
-The window overflow and window underflow trap
-handlers are a critical part of the run-time environment for a
-SPARC application. The SPARC architectural specification allows
-for the number of register windows to be any power of two less
-than or equal to 32. The most common choice for SPARC
-implementations appears to be 8 register windows. This results
-in the cwp ranging in value from 0 to 7 on most implementations.
-
-The second complicating factor is the sharing of
-registers between adjacent register windows. While each
-register window has its own set of local registers, the input
-and output registers are shared between adjacent windows. The
-output registers for register window N are the same as the input
-registers for register window ((N + 1) modulo RW) where RW is
-the number of register windows. An alternative way to think of
-this is to remember how parameters are passed to a subroutine on
-the SPARC. The caller loads values into what are its output
-registers. Then after the callee executes a save instruction,
-those parameters are available in its input registers. This is
-a very efficient way to pass parameters as no data is actually
-moved by the save or restore instructions.
-
-Call and Return Mechanism
--------------------------
-
-The SPARC architecture supports a simple yet
-effective call and return mechanism. A subroutine is invoked
-via the call (call) instruction. This instruction places the
-return address in the caller’s output register 7 (o7). After
-the callee executes a save instruction, this value is available
-in input register 7 (i7) until the corresponding restore
-instruction is executed.
-
-The callee returns to the caller via a jmp to the
-return address. There is a delay slot following this
-instruction which is commonly used to execute a restore
-instruction – if a register window was allocated by this
-subroutine.
-
-It is important to note that the SPARC subroutine
-call and return mechanism does not automatically save and
-restore any registers. This is accomplished via the save and
-restore instructions which manage the set of registers windows.
-This allows for the compiler to generate leaf-optimized functions
-that utilize the caller’s output registers without using save and restore.
-
-Calling Mechanism
------------------
-
-All RTEMS directives are invoked using the regular
-SPARC calling convention via the call instruction.
-
-Register Usage
---------------
-
-As discussed above, the call instruction does not
-automatically save any registers. The save and restore
-instructions are used to allocate and deallocate register
-windows. When a register window is allocated, the new set of
-local registers are available for the exclusive use of the
-subroutine which allocated this register set.
-
-Parameter Passing
------------------
-
-RTEMS assumes that arguments are placed in the
-caller’s output registers with the first argument in output
-register 0 (o0), the second argument in output register 1 (o1),
-and so forth. Until the callee executes a save instruction, the
-parameters are still visible in the output registers. After the
-callee executes a save instruction, the parameters are visible
-in the corresponding input registers. The following pseudo-code
-illustrates the typical sequence used to call a RTEMS directive
-with three (3) arguments:
-.. code:: c
-
- load third argument into o2
- load second argument into o1
- load first argument into o0
- invoke directive
-
-User-Provided Routines
-----------------------
-
-All user-provided routines invoked by RTEMS, such as
-user extensions, device drivers, and MPCI routines, must also
-adhere to these calling conventions.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Memory Model
-============
-
-A processor may support any combination of memory
-models ranging from pure physical addressing to complex demand
-paged virtual memory systems. RTEMS supports a flat memory
-model which ranges contiguously over the processor’s allowable
-address space. RTEMS does not support segmentation or virtual
-memory of any kind. The appropriate memory model for RTEMS
-provided by the targeted processor and related characteristics
-of that model are described in this chapter.
-
-Flat Memory Model
------------------
-
-The SPARC-64 architecture supports a flat 64-bit address space with
-addresses ranging from 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF.
-Each address is represented by a 64-bit value (and an 8-bit address
-space identifider or ASI) and is byte addressable. The address
-may be used to reference a single byte, half-word (2-bytes),
-word (4 bytes), doubleword (8 bytes), or quad-word (16 bytes).
-Memory accesses within this address space are performed
-in big endian fashion by the SPARC. Memory accesses which are not
-properly aligned generate a "memory address not aligned" trap
-(type number 0x34). The following table lists the alignment
-requirements for a variety of data accesses:
-
-.. code:: c
-
- +--------------+-----------------------+
- | Data Type | Alignment Requirement |
- +--------------+-----------------------+
- | byte | 1 |
- | half-word | 2 |
- | word | 4 |
- | doubleword | 8 |
- | quadword | 16 |
- +--------------+-----------------------+
-
-RTEMS currently does not support any SPARC Memory Management
-Units, therefore, virtual memory or segmentation systems
-involving the SPARC are not supported.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Interrupt Processing
-====================
-
-RTEMS and associated documentation uses the terms
-interrupt and vector. In the SPARC architecture, these terms
-correspond to traps and trap type, respectively. The terms will
-be used interchangeably in this manual. Note that in the SPARC manuals,
-interrupts are a subset of the traps that are delivered to software
-interrupt handlers.
-
-Synchronous Versus Asynchronous Traps
--------------------------------------
-
-The SPARC architecture includes two classes of traps:
-synchronous (precise) and asynchronous (deferred).
-Asynchronous traps occur when an
-external event interrupts the processor. These traps are not
-associated with any instruction executed by the processor and
-logically occur between instructions. The instruction currently
-in the execute stage of the processor is allowed to complete
-although subsequent instructions are annulled. The return
-address reported by the processor for asynchronous traps is the
-pair of instructions following the current instruction.
-
-Synchronous traps are caused by the actions of an
-instruction. The trap stimulus in this case either occurs
-internally to the processor or is from an external signal that
-was provoked by the instruction. These traps are taken
-immediately and the instruction that caused the trap is aborted
-before any state changes occur in the processor itself. The
-return address reported by the processor for synchronous traps
-is the instruction which caused the trap and the following
-instruction.
-
-Vectoring of Interrupt Handler
-------------------------------
-
-Upon receipt of an interrupt the SPARC automatically
-performs the following actions:
-
-- The trap level is set. This provides access to a fresh set of
- privileged trap-state registers used to save the current state,
- in effect, pushing a frame on the trap stack.
- TL <- TL + 1
-
-- Existing state is preserved
- - TSTATE[TL].CCR <- CCR
- - TSTATE[TL].ASI <- ASI
- - TSTATE[TL].PSTATE <- PSTATE
- - TSTATE[TL].CWP <- CWP
- - TPC[TL] <- PC
- - TNPC[TL] <- nPC
-
-- The trap type is preserved. TT[TL] <- the trap type
-
-- The PSTATE register is updated to a predefined state
- - PSTATE.MM is unchanged
- - PSTATE.RED <- 0
- - PSTATE.PEF <- 1 if FPU is present, 0 otherwise
- - PSTATE.AM <- 0 (address masking is turned off)
- - PSTATE.PRIV <- 1 (the processor enters privileged mode)
- - PSTATE.IE <- 0 (interrupts are disabled)
- - PSTATE.AG <- 1 (global regs are replaced with alternate globals)
- - PSTATE.CLE <- PSTATE.TLE (set endian mode for traps)
-
-- For a register-window trap only, CWP is set to point to the register
- window that must be accessed by the trap-handler software, that is:
-
- - If TT[TL] = 0x24 (a clean window trap), then CWP <- CWP + 1.
- - If (0x80 <= TT[TL] <= 0xBF) (window spill trap), then CWP <- CWP +
- CANSAVE + 2.
- - If (0xC0 <= TT[TL] <= 0xFF) (window fill trap), then CWP <- CWP1.
- - For non-register-window traps, CWP is not changed.
-
-- Control is transferred into the trap table:
-
- - PC <- TBA<63:15> (TL>0) TT[TL] 0 0000
- - nPC <- TBA<63:15> (TL>0) TT[TL] 0 0100
- - where (TL>0) is 0 if TL = 0, and 1 if TL > 0.
-
-In order to safely invoke a subroutine during trap handling, traps must be
-enabled to allow for the possibility of register window overflow and
-underflow traps.
-
-If the interrupt handler was installed as an RTEMS
-interrupt handler, then upon receipt of the interrupt, the
-processor passes control to the RTEMS interrupt handler which
-performs the following actions:
-
-- saves the state of the interrupted task on it’s stack,
-
-- switches the processor to trap level 0,
-
-- if this is the outermost (i.e. non-nested) interrupt,
- then the RTEMS interrupt handler switches from the current stack
- to the interrupt stack,
-
-- enables traps,
-
-- invokes the vectors to a user interrupt service routine (ISR).
-
-Asynchronous interrupts are ignored while traps are
-disabled. Synchronous traps which occur while traps are
-disabled may result in the CPU being forced into an error mode.
-
-A nested interrupt is processed similarly with the
-exception that the current stack need not be switched to the
-interrupt stack.
-
-Traps and Register Windows
---------------------------
-
-XXX
-
-Interrupt Levels
-----------------
-
-Sixteen levels (0-15) of interrupt priorities are
-supported by the SPARC architecture with level fifteen (15)
-being the highest priority. Level zero (0) indicates that
-interrupts are fully enabled. Interrupt requests for interrupts
-with priorities less than or equal to the current interrupt mask
-level are ignored.
-
-Although RTEMS supports 256 interrupt levels, the
-SPARC only supports sixteen. RTEMS interrupt levels 0 through
-15 directly correspond to SPARC processor interrupt levels. All
-other RTEMS interrupt levels are undefined and their behavior is
-unpredictable.
-
-Disabling of Interrupts by RTEMS
---------------------------------
-
-XXX
-
-Interrupt Stack
----------------
-
-The SPARC architecture does not provide for a
-dedicated interrupt stack. Thus by default, trap handlers would
-execute on the stack of the RTEMS task which they interrupted.
-This artificially inflates the stack requirements for each task
-since EVERY task stack would have to include enough space to
-account for the worst case interrupt stack requirements in
-addition to it’s own worst case usage. RTEMS addresses this
-problem on the SPARC by providing a dedicated interrupt stack
-managed by software.
-
-During system initialization, RTEMS allocates the
-interrupt stack from the Workspace Area. The amount of memory
-allocated for the interrupt stack is determined by the
-interrupt_stack_size field in the CPU Configuration Table. As
-part of processing a non-nested interrupt, RTEMS will switch to
-the interrupt stack before invoking the installed handler.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Default Fatal Error Processing
-==============================
-
-Upon detection of a fatal error by either the
-application or RTEMS the fatal error manager is invoked. The
-fatal error manager will invoke the user-supplied fatal error
-handlers. If no user-supplied handlers are configured, the
-RTEMS provided default fatal error handler is invoked. If the
-user-supplied fatal error handlers return to the executive the
-default fatal error handler is then invoked. This chapter
-describes the precise operations of the default fatal error
-handler.
-
-Default Fatal Error Handler Operations
---------------------------------------
-
-The default fatal error handler which is invoked by
-the fatal_error_occurred directive when there is no user handler
-configured or the user handler returns control to RTEMS. The
-default fatal error handler disables processor interrupts to
-level 15, places the error code in g1, and goes into an infinite
-loop to simulate a halt processor instruction.
-
-Symmetric Multiprocessing
-=========================
-
-SMP is not supported.
-
-Thread-Local Storage
-====================
-
-Thread-local storage is supported.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Board Support Packages
-======================
-
-An RTEMS Board Support Package (BSP) must be designed
-to support a particular processor and target board combination.
-This chapter presents a discussion of SPARC specific BSP issues.
-For more information on developing a BSP, refer to the chapter
-titled Board Support Packages in the RTEMS
-Applications User’s Guide.
-
-HelenOS and Open Firmware
--------------------------
-
-The provided BSPs make use of some bootstrap and low-level hardware code
-of the HelenOS operating system. These files can be found in the shared/helenos
-directory of the sparc64 bsp directory. Consult the sources for more
-detailed information.
-
-The shared BSP code also uses the Open Firmware interface to re-use firmware
-code, primarily for console support and default trap handlers.
-
-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/develenv/develenv_old_reference_only.rst b/develenv/develenv_old_reference_only.rst
deleted file mode 100644
index 2f1b2a5..0000000
--- a/develenv/develenv_old_reference_only.rst
+++ /dev/null
@@ -1,1393 +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
-
-.. 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: variable substitution info:
-
-.. COMMENT: @set LANGUAGE C
-
-.. 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 Development Environment Guide
-
-===================================
-RTEMS Development Environment 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 Development Environment Guide
-###################################
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Introduction
-############
-
-This document describes the RTEMS development
-environment. Discussions are provided for the following topics:
-
-- the directory structure used by RTEMS,
-
-- usage of the GNU Make utility within the RTEMS
- development environment,
-
-- sample applications, and
-
-- the RTEMS specific utilities.
-
-RTEMS was designed as a reusable software component.
-Highly reusable software such as RTEMS is typically distributed
-in the form of source code without providing any support tools.
-RTEMS is the foundation for a complex family of facilities
-including board support packages, device drivers, and support
-libraries. The RTEMS Development Environment is not a CASE
-tool. It is a collection of tools designed to reduce the
-complexity of using and enhancing the RTEMS family. Tools are
-provided which aid in the management of the development,
-maintenance, and usage of RTEMS, its run-time support
-facilities, and applications which utilize the executive.
-
-A key component of the RTEMS development environment
-is the GNU family of free tools. This is robust set of
-development and POSIX compatible tools for which source code is
-freely available. The primary compilers, assemblers, linkers,
-and make utility used by the RTEMS development team are the GNU
-tools. They are highly portable supporting a wide variety of
-host computers and, in the case of the development tools, a wide
-variety of target processors.
-
-It is recommended that the RTEMS developer become
-familiar with the RTEMS Development Environment before
-proceeding with any modifications to the executive source tree.
-The source code for the executive is very modular and source
-code is divided amongst directories based upon functionality as
-well as dependencies on CPU and target board. This organization
-is aimed at isolating and minimizing non-portable code. This
-has the immediate result that adding support for a new CPU or
-target board requires very little "wandering" around the source
-tree.
-
-.. COMMENT: COPYRIGHT (c) 1989-2010.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Directory Structure
-###################
-
-The RTEMS directory structure is designed to meet
-the following requirements:
-
-- encourage development of modular components.
-
-- isolate processor and target dependent code, while
- allowing as much common source code as possible to be shared
- across multiple processors and target boards.
-
-- allow multiple RTEMS users to perform simultaneous
- compilation of RTEMS and its support facilities for different
- processors and targets.
-
-The resulting directory structure has processor and
-board dependent source files isolated from generic files. When
-RTEMS is configured and built, object directories and
-an install point will be automatically created based upon
-the target CPU family and BSP selected.
-
-The placement of object files based upon the selected BSP name
-ensures that object files are not mixed across CPUs or targets.
-This in combination with the makefiles allows the specific
-compilation options to be tailored for a particular target
-board. For example, the efficiency of the memory subsystem for
-a particular target board may be sensitive to the alignment of
-data structures, while on another target board with the same
-processor memory may be very limited. For the first target, the
-options could specify very strict alignment requirements, while
-on the second the data structures could be *packed* to conserve
-memory. It is impossible to achieve this degree of flexibility
-without providing source code.
-
-The RTEMS source tree is organized based on the following variables:
-
-- functionality,
-
-- target processor family,
-
-- target processor model,
-
-- peripherals, and
-
-- target board.
-
-Each of the following sections will describe the
-contents of the directories in the RTEMS source
-tree. The top of the tree will be referenced
-as ``${RTEMS_ROOT}`` in this discussion.
-
-.. COMMENT: Top Level Tree
-
-.. COMMENT: @ifset use-ascii
-.. code:: c
-
- rtems-VERSION
- |
- +--------+----+----+----+--+-----+---+-------+--------+
- | | | | | | | | |
- aclocal automake c contrib cpukit doc make testsuites tools
-
-.. COMMENT: @end ifset
-
-``${RTEMS_ROOT}/aclocal/``
- This directory contains the custom M4 macros which are available to
- the various GNU autoconf ``configure.ac`` scripts throughout
- the RTEMS source tree. GNU autoconf interprets ``configure.ac``
- files to produce the ``configure`` files used to tailor
- RTEMS build for a particular host and target environment. The
- contents of this directory will not be discussed further in this
- document.
-
-``${RTEMS_ROOT}/automake/``
- This directory contains the custom GNU automake fragments
- which are used to support the various ``Makefile.am``
- files throughout the RTEMS source tree. The
- contents of this directory will not be discussed
- further in this document.
-
-``${RTEMS_ROOT}/c/``
- This directory is the root of the portions of the RTEMS source
- tree which must be built tailored for a particular CPU model
- or BSP. The contents of this directory will be discussed
- in the `c/ Directory`_ section.
-
-``${RTEMS_ROOT}/contrib/``
- This directory contains contributed support software. Currently
- this directory contains the RPM specifications for cross-compilers
- hosted on GNU/Linux that target various operating systems
- including MinGW, Cygwin, FreeBSD, and Solaris. The
- cross-compilers produced using these specifications are then
- used in a Canadian cross build procedure to produce the various
- RTEMS toolsets on a GNU/Linux host.
- This directory also contains RPM specifications for the
- prebuilt cross-compilation toolsets provided by the
- RTEMS project. There are separate subdirectories
- for each of the components in the RTEMS Cross Compilation
- Environment unde the ``contrib/crossrpms/`` directory.
- This directory is configured, built, and installed separately
- from the RTEMS executive and tests. This directory will not
- be discussed further in this document.
-
-``${RTEMS_ROOT}/cpukit/``
- This directory is the root for all of the "multilib’able"
- portions of RTEMS. This is a GNU way of saying the
- contents of this directory can be compiled like the
- C Library (``libc.a``) and the functionality is
- neither CPU model nor BSP specific. The source code
- for most RTEMS services reside under this directory.
- The contents of this directory will be discussed
- in the `CPU Kit Directory`_ section.
-
-``${RTEMS_ROOT}/doc/``
- This directory is the root for all RTEMS documentation.
- The source for RTEMS is written in GNU TeXinfo and
- used to produce HTML, PDF, and "info" files.
- The RTEMS documentation is configured, built,
- and installed separately from the RTEMS executive and tests.
- The contents of this directory will be discussed
- in the `Documentation Directory`_ section.
-
-``${RTEMS_ROOT}/make/``
- This directory contains files which support the
- RTEMS Makefile’s. From a user’s perspective, the
- most important parts are found in the ``custom/``
- subdirectory. Each ".cfg" file in this directory
- is associated with a specific BSP and describes
- the CPU model, compiler flags, and procedure to
- produce an executable for the target board.
- These files are described in detail in the*RTEMS BSP and Device Driver Development Guide*
- and will not be discussed further in this document.
-
-``${RTEMS_ROOT}/testsuites/``
- This directory contains the test suites for the
- various RTEMS APIs and support libraries. The
- contents of this directory are discussed in the `testsuites/ Test Suites`_ section.
-
-``${RTEMS_ROOT}/tools/``
- This directory contains RTEMS specific support utilities which
- execute on the development host. These utilities are divided
- into subdirectories based upon whether they are used in the process
- of building RTEMS and applications, are CPU specific, or are
- used to assist in updating the RTEMS source tree and applications.
- The support utilities used in the process of building RTEMS are
- described in `RTEMS Specific Utilities`_. These are the
- only components of this subtree that will be discussed in this
- document.
-
-.. COMMENT: c/ Directions
-
-c/ Directory
-============
-
-The ``${RTEMS_ROOT}/c/`` directory was formerly
-the root directory of all RTEMS source code. At this time, it contains
-the root directory for only those RTEMS components
-which must be compiled or linked in a way that is specific to a
-particular CPU model or board. This directory contains the
-following subdirectories:
-
-``${RTEMS_ROOT}/c/src/``
- This directory is logically the root for the RTEMS components
- which are CPU model or board dependent. Thus this directory
- is the root for the BSPs and the Ada Test Suites as well
- as CPU model and BSP dependent libraries. The contents of
- this directory are discussed in the `c/src/ Directory`_ section.
-
-.. COMMENT: c/src/ Directory
-
-c/src/ Directory
-----------------
-
-As mentioned previously, this directory is logically
-the root for the RTEMS components
-which are CPU model or board dependent. The
-following is a list of the subdirectories in this
-directory and a description of each.
-
-``${RTEMS_ROOT}/c/src/aclocal/``
- This directory contains the custom M4 macros which are available to
- the various GNU autoconf ``configure.ac`` scripts throughout
- this portion of the RTEMS source tree. GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used
- to tailor RTEMS build for a particular host and target environment. The
- contents of this directory will not be discussed further in this
- document.
-
-``${RTEMS_ROOT}/c/src/ada/``
- This directory contains the Ada95 language bindings to the
- RTEMS Classic API.
-
-``${RTEMS_ROOT}/c/src/ada-tests/``
- This directory contains the test suite for the Ada
- language bindings to the Classic API.
-
-``${RTEMS_ROOT}/c/src/automake/``
- This directory contains files which are "Makefile fragments."
- They are included as required by the various ``Makefile.am``
- files throughout this portion of the RTEMS source tree.
-
-``${RTEMS_ROOT}/c/src/lib/``
- This directory contains the directories ``libbsp/``
- and ``libcpu/`` which contain the source code for
- the Board Support Packages (BSPs) and CPU Model
- specific source code for RTEMS.
- The ``libbsp/`` is organized based upon the CPU
- family and boards BSPs. The contents of ``libbsp/``
- are discussed briefly in `c/src/lib/libbsp BSP Directory`_
- and presented in detail in the*RTEMS BSP and Device Driver Development Guide*.
- The ``libcpu/`` directory is also organized by
- CPU family with further divisions based upon CPU
- model and features that are shared across CPU models
- such as caching and DMA.
-
-``${RTEMS_ROOT}/c/src/libchip/``
- This directory contains device drivers for various
- peripheral chips which are designed to be CPU and
- board dependent. This directory contains a variety
- of drivers for serial devices, network interface
- controllers, shared memory and real-time clocks.
-
-``${RTEMS_ROOT}/c/src/librtems++/``
- This directory contains C++ classes which map to the RTEMS
- Classic API.
-
-``${RTEMS_ROOT}/c/src/make/``
- This directory is used to generate the bulk of the supporting
- rules files which are installed as part of the Application Makefiles.
- This file contains settings for various Makefile variables to
- tailor them to the particular CPU model and BSP configured.
-
-``${RTEMS_ROOT}/c/src/nfsclient/``
- This directory contains a Network File System (NFS) client
- for RTEMS. With this file system, a user’s application can
- access files on a remote computer.
-
-``${RTEMS_ROOT}/c/src/optman/``
- This directory contains stubs for the RTEMS Classic API
- Managers which are considered optional and whose use
- may be explicitly forbidden by an application. All of the
- directive implementations in this Optional Managers
- return ``E_NOTCONFIGURED``.
-
-``${RTEMS_ROOT}/c/src/support/``
- This directory exists solely to generate the RTEMS
- version string which includes the RTEMS version,
- CPU architecture, CPU model, and BSP name.
-
-``${RTEMS_ROOT}/c/src/wrapup/``
- This directory is responsible for taking the individual
- libraries and objects built in each of the components
- in the RTEMS source tree and bundling them together to form
- the single RTEMS library ``librtemsbsp.a``. This
- library contains all BSP and CPU model specific software.
-
-.. COMMENT: c/src/lib/libbsp BSP Directory
-
-c/src/lib/libbsp BSP Directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The "libbsp" directory contains a directory for each CPU family supported
-by RTEMS. Beneath each CPU directory is a directory for each BSP for that
-processor family.
-
-.. COMMENT: Tree 7 - C BSP Library
-
-The "libbsp" directory provides all the BSPs provided with this
-release of the RTEMS executive. The subdirectories are
-divided, as discussed previously, based on specific processor
-family, then further broken down into specific target board
-environments. The "no_cpu" subdirectory provides a starting point
-template BSP which can be used to develop a specific BSP for an
-unsupported target board. The files in this subdirectory may aid
-in preliminary testing of the RTEMS development environment that has
-been built for no particular target in mind.
-
-Below each CPU dependent directory is a directory for each target BSP
-supported in this release.
-
-Each BSP provides the modules which comprise an RTEMS BSP. The
-modules are separated into the subdirectories "clock", "console",
-"include", "shmsupp", "startup", and "timer" as shown in the following
-figure:
-
-.. COMMENT: Tree 8 - Each BSP
-
-.. COMMENT: @ifset use-ascii
-.. code:: c
-
- Each BSP
- |
- +-----------+----------+-----+-----+----------+----------+
- | | | | | |
- clock console include shmsupp startup timer
-
-.. COMMENT: @end ifset
-
-.. COMMENT: CPU Kit Directory
-
-CPU Kit Directory
-=================
-
-.. COMMENT: The @code{cpukit/} directory structure is as follows:
-
-.. COMMENT: CPU Kit Tree
-
-.. COMMENT: @ifset use-ascii
-
-.. COMMENT: @example
-
-.. COMMENT: @group
-
-.. COMMENT: cpukit
-
-.. COMMENT: |
-
-.. COMMENT: +-+-+-+-+
-
-.. COMMENT: | | | | |
-
-.. COMMENT: posix rtems sapi score wrapup
-
-.. COMMENT: @end group
-
-.. COMMENT: @end example
-
-.. COMMENT: @end ifset
-
-The ``cpukit/`` directory contains a set of subdirectories which
-contains the source files comprising the executive portion of
-the RTEMS development environment as well as portable support
-libraries such as support for the C Library and filesystems.
-The API specific and "SuperCore" (e.g. ``score/`` directory)
-source code files are separated into distinct directory trees.
-
-The following is a description of each of the subdirectories
-under ``cpukit/``:
-
-``${RTEMS_ROOT}/cpukit/aclocal/``
- This directory contains the custom M4 macros which are available to
- the various GNU autoconf ``configure.ac`` scripts throughout
- the CPU Kit portion of the RTEMS source tree.
- GNU autoconf interprets ``configure.ac``
- files to produce the ``configure`` files used to tailor
- RTEMS build for a particular host and target environment. The
- contents of this directory will not be discussed further in this
- document.
-
-``${RTEMS_ROOT}/cpukit/automake/``
- This directory contains files which are "Makefile fragments."
- They are included as required by the various ``Makefile.am``
- files throughout the CPU Kit portion of the RTEMS source tree.
-
-``${RTEMS_ROOT}/cpukit/ftpd/``
- This directory contains the RTEMS ftpd server.
-
-``${RTEMS_ROOT}/cpukit/httpd/``
- This directory contains the port of the GoAhead
- web server to RTEMS.
-
-``${RTEMS_ROOT}/cpukit/include/``
- This directory contains header files which are private to
- RTEMS and not considered to be owned by any other component
- in the CPU Kit.
-
-``${RTEMS_ROOT}/cpukit/libblock/``
- This directory contains support code for using
- Block Devices such as hard drives, floppies, and
- CD-ROMs. It includes the generic IO primitives
- for block device drivers, disk caching support,
- and a RAM disk block device driver.
-
-``${RTEMS_ROOT}/cpukit/libcsupport/``
- This directory contains the RTEMS specific support routines
- for the Newlib C Library. This includes what are referred
- to as system calls and found in section 2 of the traditional
- UNIX manual. In addition, it contains a thread-safe
- implementation of the Malloc family of routines as well
- as BSD and POSIX services not found in Newlib.
-
-``${RTEMS_ROOT}/cpukit/libfs/``
- This directory contains the various non-networked
- filesystem implementations for RTEMS. It includes
- the In-Memory FileSystem (IMFS), the mini-IMFS,
- and FAT filesystems.
-
-``${RTEMS_ROOT}/cpukit/libi2c/``
- This directory contains the RTEMS I2C framework.
-
-``${RTEMS_ROOT}/cpukit/libmd/``
- This directory contains a port of the standard MD5
- checksum code.
-
-``${RTEMS_ROOT}/c/src/libmisc/``
- This directory contains support facilities which
- are RTEMS specific but otherwise unclassified. In
- general, they do not adhere to a standard API.
- Among the support facilities in this directory are
- a ``/dev/null`` device driver, the Stack
- Overflow Checker, a mini-shell, the CPU and
- rate monotonic period usage monitoring libraries,
- and a utility to "dump a buffer" in a nicely
- formatted way similar to many ROM monitors.
-
-``${RTEMS_ROOT}/cpukit/libnetworking/``
- This directory contains the port of the FreeBSD
- TCP/IP stack to RTEMS.
-
-``${RTEMS_ROOT}/cpukit/librpc/``
- This directory contains the port of the FreeBSD
- RPC/XDR source to RTEMS.
-
-``${RTEMS_ROOT}/cpukit/libpci/``
- This directory contains RTEMS PCI Library.
-
-``${RTEMS_ROOT}/cpukit/posix/``
- This directory contains the RTEMS implementation
- of the threading portions of the POSIX API.
-
-``${RTEMS_ROOT}/cpukit/pppd/``
- This directory contains a port of the free implementation
- of the PPPD network protocol.
-
-``${RTEMS_ROOT}/cpukit/rtems/``
- This directory contains the implementation of the
- Classic API.
-
-``${RTEMS_ROOT}/cpukit/sapi/``
- This directory contains the implementation of RTEMS
- services which are required but beyond the realm
- of any standardization efforts. It includes
- initialization, shutdown, and IO services.
-
-``${RTEMS_ROOT}/cpukit/score/``
- This directory contains the "SuperCore" of RTEMS.
- All APIs are implemented in terms of SuperCore services.
- For example, Classic API tasks and POSIX threads
- are all implemented in terms of SuperCore threads.
- This provides a common infrastructure and a high degree
- of interoperability between the APIs. For example,
- services from all APIs may be used by any task/thread
- independent of the API used to create it.
- Within the ``score/`` directory the CPU dependent modules are found.
- The ``score/cpu/`` subdirectory contains a subdirectory for each
- target CPU supported by this release of the RTEMS
- executive. Each processor directory contains the CPU dependent
- code necessary to host RTEMS. The ``no_cpu`` directory provides a
- starting point for developing a new port to an unsupported
- processor. The files contained within the ``no_cpu`` directory
- may also be used as a reference for the other ports to specific
- processors.
-
-``${RTEMS_ROOT}/cpukit/shttpd/``
- This directory contains the port of the Simple HTTPD
- web server to RTEMS.
-
-``${RTEMS_ROOT}/cpukit/telnetd/``
- This directory contains the RTEMS telnetd server.
-
-``${RTEMS_ROOT}/cpukit/wrapup/``
- This directory is responsible for taking the individual
- libraries and objects built in each of the components
- in the RTEMS CPU Kit source tree and bundling them
- together to form the single RTEMS library ``librtemscpu.a``. This
- library contains all BSP and CPU model specific software.
-
-``${RTEMS_ROOT}/cpukit/zlib/``
- This directory contains a port of the GNU Zlib compression
- library to RTEMS.
-
-.. COMMENT: testsuites/ Test Suites
-
-testsuites/ Test Suites
-=======================
-
-This directory provides all of the RTEMS Test Suite
-except those for the Classic API Ada95 binding
-This includes the single processor tests, multiprocessor tests,
-timing tests, library tests, and sample tests. Additionally,
-subdirectories for support functions and test related header
-files are provided. The following table lists the test suites
-currently included with the RTEMS and the directory in which
-they may be located:
-
-``${RTEMS_ROOT}/testsuites/libtests/``
- This directory contains the test suite for the
- various RTEMS support components.
-
-``${RTEMS_ROOT}/testsuites/mptests/``
- This directory contains the test suite for the
- multiprocessor support in the Classic API.
- The tests provided address two node configurations
- and provide coverage for the multiprocessor code found
- in RTEMS.
-
-``${RTEMS_ROOT}/testsuites/psxtests/``
- This directory contains the test suite for the
- RTEMS POSIX API.
-
-``${RTEMS_ROOT}/testsuites/samples/``
- This directory provides sample application tests
- which aid in the testing a newly built RTEMS environment, a new
- BSP, or as starting points for the development of an application
- using the RTEMS executive. They are discussed in `Sample Applications`_.
-
-``${RTEMS_ROOT}/testsuites/sptests/``
- This directory contains the test suite for the RTEMS
- Classic API when executing on a single processor.
- The tests were originally designed to provide
- near complete test coverage for the entire
- executive code. With the addition of multiple APIs,
- this is no longer the case as some SuperCore functionality
- is not available through the Classic API. Thus
- some functionality in the SuperCore is only covered
- by tests in the POSIX API Test Suites.
-
-``${RTEMS_ROOT}/testsuites/support/``
- This directory contains support software and header files
- for the various test suites.
-
-``${RTEMS_ROOT}/testsuites/tmtests/``
- This directory contains the timing test suite for
- the RTEMS Classic API. This include tests that
- benchmark each directive in the Classic API
- as well as a set of critical SuperCore functions.
- These tests are important for helping to verify
- that RTEMS performs as expected on your target hardware.
- It is not uncommon to discover mistakes in board
- initialization such as caching being disabled as
- a side-effect of analyzing the results of these tests.
-
-``${RTEMS_ROOT}/testsuites/tools/``
- This directory contains tools which execute on
- the development host and aid in executing and
- evaluating the results of the test suite. The
- tools ``difftest`` compares the output of one
- or more tests with the expected output. If you
- place the output of all the ``tmtests/`` in
- a single file, then the utility ``sorttimes``
- will be able to produce a report organizing the
- execution times by manager.
-
-.. COMMENT: Documentation Directory
-
-Documentation Directory
-=======================
-
-This directory contains the source code for all RTEMS documentation
-in ``TexInfo`` format as well as utilities used in the generation
-of the RTEMS documentation set. This source code is used to produce
-the RTEMS documentation in various formats including PDF, HTML,
-and PostScript.
-
-``${RTEMS_ROOT}/doc/ada_user/``
- This directory contains the source code for the *RTEMS
- Applications Ada User’s Guide* which documents the Ada95
- binding to the Classic API. This manual is produced from
- from the same source base as the *RTEMS Application
- C User’s Guide*.
-
-``${RTEMS_ROOT}/doc/bsp_howto/``
- This directory contains the source code for the*RTEMS BSP and Device Driver Development Guide*.
-
-``${RTEMS_ROOT}/doc/common/``
- This directory contains the source code for the files which
- are shared across multiple manuals in the RTEMS Documentation Set.
- This includes the copyright page as well as the timing
- tables which can be filled in on a per BSP basis in the
- CPU supplements.
-
-``${RTEMS_ROOT}/doc/cpu_supplement/``
- This directory contains the source code for the
- RTEMS CPU Supplement.
-
-``${RTEMS_ROOT}/doc/develenv/``
- This directory contains the source code for the*RTEMS Development Environment Guide*. This is
- the document you are currently reading.
-
-``${RTEMS_ROOT}/doc/filesystem/``
- This directory contains the source code for the*RTEMS Filesystem Design Guide*. This manual
- is a continuous work in process as it attempts to
- capture the design of the interface between system
- calls and filesystem implementations as well as the
- information required by those implementing filesystems.
-
-``${RTEMS_ROOT}/doc/images/``
- This directory contains the source code for the graphics
- used in the HTML version of the RTEMS Documentation.
-
-``${RTEMS_ROOT}/doc/networking/``
- This directory contains the source code for the*RTEMS Network Supplement*.
-
-``${RTEMS_ROOT}/doc/new_chapters/``
- This directory contains the source code for the new documentation
- components which have not yet been collected into a new manual or
- merged into an existing document. Currently, this primarily
- contains draft documentation for some portions of
- the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``.
-
-``${RTEMS_ROOT}/doc/porting/``
- This directory contains the source code for the*RTEMS Porting Guide*.
-
-``${RTEMS_ROOT}/doc/posix1003.1/``
- This directory contains the source code for the*RTEMS POSIX 1003.1 Compliance Guide*.
-
-``${RTEMS_ROOT}/doc/posix_users/``
- This directory contains the source code for the*RTEMS POSIX API User’s Guide*. It is important to
- note that RTEMS’ support for POSIX is a combination of
- functionality provided by RTEMS and the Newlib C Library
- so some functionality is documented by Newlib.
-
-``${RTEMS_ROOT}/doc/relnotes/``
- This directory contains the source code for a formally
- release notes document. This has not been used for
- recent RTEMS releases.
-
-``${RTEMS_ROOT}/doc/started/``
- This directory contains the source code for the*Getting Started with RTEMS for C/C++ Users* manual.
-
-``${RTEMS_ROOT}/doc/tools/``
- This directory contains the source code for the tools
- used on the development host to assist in producing the
- RTEMS Documentation. The most important of these tools
- is ``bmenu`` which generates the hierarchical node
- linking commands based upon chapter, section, and
- subsection organization.
-
-``${RTEMS_ROOT}/doc/user/``
- This directory contains the source code for the *RTEMS
- Applications C User’s Guide* which documents the Classic API.
-
-.. COMMENT: COPYRIGHT (c) 1989-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-
-Sample Applications
-###################
-
-Introduction
-============
-
-The RTEMS source distribution includes a set of sample applications
-that are located in the ``${RTEMS_ROOT}/testsuites/samples/``
-directory. These applications are intended to illustrate the
-basic format of RTEMS single and multiple processor
-applications and the use of some features. In addition, these
-relatively simple applications can be used to test locally
-developed board support packages and device drivers as they
-exercise a critical subset of RTEMS functionality that is often
-broken in new BSPs.
-
-Some of the following sample applications will be covered in
-more detail in subsequent sections:
-
-*Hello World*
- The RTEMS Hello World test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``.
- This test is helpful when testing new RTEMS development environment.
-
-*Clock Tick*
- The ``${RTEMS_ROOT}/testsuites/samples/ticker/``
- subdirectory provides a test for verification of clock chip
- device drivers of BSPs.
-
-*Base Single Processor*
- A simple single processor test similar to those in the
- single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
-
-*Base Multiple Processor*
- A simple two node multiprocessor test capable of testing an newly
- developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
-
-*Capture*
- The RTEMS Capture test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``.
- This is an interactive test which demonstrates the capabilities
- of the RTEMS Capture Engine. It includes a few test threads
- which generate interesting execution patterns. Look at the
- file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
- for a sample session.
-
-*Constructor/Destructor C++ Test*
- The ``${RTEMS_ROOT}/testsuites/samples/cdtest/``
- subdirectory provides a simple C++ application using
- constructors and destructors. It is only built when
- C++ is enabled and its primary purpose is to demonstrate
- that global constructors and destructors work. Since this
- requires that the linker script for your BSP be correct, this is
- an important test.
-
-*File IO*
- The RTEMS File IO test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``.
- This is an interactive test which allows the user to interact with
- an ATA/IDE device. It will read the partition table and allow the
- user to dynamically mount one of the FAT32 partitions it finds.
- Commands are also provided to write and read files on the disk.
-
-*IO Stream*
- The RTEMS IO Stream test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``.
- This test is a simple C++ application which demonstrates that
- C++ iostreams are functional. This requires that the RTEMS C++
- run-time support is functioning properly. This test is only
- build when C++ is enabled.
-
-*Network Loopback Test*
- The ``${RTEMS_ROOT}/testsuites/samples/loopback/``
- directory contains a sample test that demonstrates the use of
- sockets and the loopback network device. It does not require
- the presence of network hardware in order to run.
- It is only built if RTEMS was configured with networking enabled.
-
-*Minimum Size Test*
- The directory``${RTEMS_ROOT}/testsuites/samples/minimum/``
- contains a simple RTEMS program that results in a non-functional
- executable. It is intended to show the size of a minimum footprint
- application based upon the current RTEMS configuration.
-
-*Nanoseconds*
- The RTEMS Nanoseconds test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``.
- This test demonstrates that the BSP has support for nanosecond
- timestamp granularity. It prints the time of day and uptime multiple
- times as quickly as possible. It should be possible from the output
- to determine if your BSP has nanosecond accurate clock support
- and it is functional.
-
-*Paranoia Floating Point Test*
- The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/``
- contains the public domain floating point and math library test.
-
-*Point-to-Point Protocol Daemon*
- The RTEMS Point-to-Point Protocol Daemon test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``.
- This test primarily serves as the baseline for a user application
- using the PPP protocol.
-
-*Unlimited Object Allocation*
- The ``${RTEMS_ROOT}/testsuites/samples/unlimited/``
- directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS.
-
-The sample tests are written using the Classic API so the reader
-should be familiar with the terms used and
-material presented in the *RTEMS Applications Users Guide*.
-
-Hello World
-===========
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/hello/
-
-It provides a rudimentary test of the BSP start up
-code and the console output routine. The C version of this
-sample application uses the printf function from the RTEMS
-Standard C Library to output messages. The Ada version of this
-sample uses the TEXT_IO package to output the hello messages.
-The following messages are printed:
-.. code:: c
-
- *** HELLO WORLD TEST \***
- Hello World
- \*** END OF HELLO WORLD TEST \***
-
-These messages are printed from the application’s
-single initialization task. If the above messages are not
-printed correctly, then either the BSP start up code or the
-console output routine is not operating properly.
-
-Clock Tick
-==========
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/ticker/
-
-This application is designed as a simple test of the
-clock tick device driver. In addition, this application also
-tests the printf function from the RTEMS Standard C Library by
-using it to output the following messages:
-.. code:: c
-
- *** CLOCK TICK TEST \***
- TA1 - tm_get - 09:00:00 12/31/1988
- TA2 - tm_get - 09:00:00 12/31/1988
- TA3 - tm_get - 09:00:00 12/31/1988
- TA1 - tm_get - 09:00:05 12/31/1988
- TA1 - tm_get - 09:00:10 12/31/1988
- TA2 - tm_get - 09:00:10 12/31/1988
- TA1 - tm_get - 09:00:15 12/31/1988
- TA3 - tm_get - 09:00:15 12/31/1988
- TA1 - tm_get - 09:00:20 12/31/1988
- TA2 - tm_get - 09:00:20 12/31/1988
- TA1 - tm_get - 09:00:25 12/31/1988
- TA1 - tm_get - 09:00:30 12/31/1988
- TA2 - tm_get - 09:00:30 12/31/1988
- TA3 - tm_get - 09:00:30 12/31/1988
- \*** END OF CLOCK TICK TEST \***
-
-The clock tick sample application utilizes a single
-initialization task and three copies of the single application
-task. The initialization task prints the test herald, sets the
-time and date, and creates and starts the three application
-tasks before deleting itself. The three application tasks
-generate the rest of the output. Every five seconds, one or
-more of the tasks will print the current time obtained via the
-tm_get directive. The first task, TA1, executes every five
-seconds, the second task, TA2, every ten seconds, and the third
-task, TA3, every fifteen seconds. If the time printed does not
-match the above output, then the clock device driver is not
-operating properly.
-
-Base Single Processor Application
-=================================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/base_sp/
-
-It provides a framework from which a single processor
-RTEMS application can be developed. The use of the task argument
-is illustrated. This sample application uses the printf
-function from the RTEMS Standard C Library or TEXT_IO functions
-when using the Ada version to output the following messages:
-.. code:: c
-
- *** SAMPLE SINGLE PROCESSOR APPLICATION \***
- Creating and starting an application task
- Application task was invoked with argument (0) and has id of 0x10002
- \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \***
-
-The first two messages are printed from the
-application’s single initialization task. The final messages
-are printed from the single application task.
-
-Base Multiple Processor Application
-===================================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/base_mp/
-
-It provides a framework from which a multiprocessor
-RTEMS application can be developed. This directory has a
-subdirectory for each node in the multiprocessor system. The
-task argument is used to distinguish the node on which the
-application task is executed. The first node will print the
-following messages:
-.. code:: c
-
- *** SAMPLE MULTIPROCESSOR APPLICATION \***
- Creating and starting an application task
- This task was invoked with the node argument (1)
- This task has the id of 0x10002
- \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
-
-The second node will print the following messages:
-.. code:: c
-
- *** SAMPLE MULTIPROCESSOR APPLICATION \***
- Creating and starting an application task
- This task was invoked with the node argument (2)
- This task has the id of 0x20002
- \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
-
-The herald is printed from the application’s single
-initialization task on each node. The final messages are
-printed from the single application task on each node.
-
-In this sample application, all source code is shared
-between the nodes except for the node dependent configuration
-files. These files contains the definition of the node number
-used in the initialization of the RTEMS Multiprocessor
-Configuration Table. This file is not shared because the node
-number field in the RTEMS Multiprocessor Configuration Table
-must be unique on each node.
-
-Constructor/Destructor C++ Application
-======================================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/cdtest/
-
-This sample application demonstrates that RTEMS is
-compatible with C++ applications. It uses constructors,
-destructor, and I/O stream output in testing these various
-capabilities. The board support package responsible for this
-application must support a C++ environment.
-
-This sample application uses the printf function from
-the RTEMS Standard C Library to output the following messages:
-.. code:: c
-
- Hey I'M in base class constructor number 1 for 0x400010cc.
- Hey I'M in base class constructor number 2 for 0x400010d4.
- Hey I'M in derived class constructor number 3 for 0x400010d4.
- \*** CONSTRUCTOR/DESTRUCTOR TEST \***
- Hey I'M in base class constructor number 4 for 0x4009ee08.
- Hey I'M in base class constructor number 5 for 0x4009ee10.
- Hey I'M in base class constructor number 6 for 0x4009ee18.
- Hey I'M in base class constructor number 7 for 0x4009ee20.
- Hey I'M in derived class constructor number 8 for 0x4009ee20.
- Testing a C++ I/O stream
- Hey I'M in derived class constructor number 8 for 0x4009ee20.
- Derived class - Instantiation order 8
- Hey I'M in base class constructor number 7 for 0x4009ee20.
- Instantiation order 8
- Hey I'M in base class constructor number 6 for 0x4009ee18.
- Instantiation order 6
- Hey I'M in base class constructor number 5 for 0x4009ee10.
- Instantiation order 5
- Hey I'M in base class constructor number 4 for 0x4009ee08.
- Instantiation order 5
- \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \***
- Hey I'M in base class constructor number 3 for 0x400010d4.
- Hey I'M in base class constructor number 2 for 0x400010d4.
- Hey I'M in base class constructor number 1 for 0x400010cc.
-
-Minimum Size Test
-=================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/minimum/
-
-This sample application is designed to produce the
-minimum code space required for any RTEMS application
-based upon the current RTEMS configuration and
-BSP. In many situations, the bulk of this executable
-consists of hardware and RTEMS initialization, basic
-infrastructure such as malloc(), and RTEMS and
-hardware shutdown support.
-
-Nanosecond Granularity Application
-==================================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/nsecs/
-
-This sample application exercises the Clock Driver
-for this BSP and demonstrates its ability to generate
-accurate timestamps. This application does this by
-exercising the time subsystem in three ways:
-
-- Obtain Time of Day Twice Back to Back
-
-- Obtain System Up Time Twice Back to Back
-
-- Use System Up Time to Measure Loops
-
-The following is an example of what the output of this
-test may appear like:
-.. code:: c
-
- *** NANOSECOND CLOCK TEST \***
- 10 iterations of getting TOD
- Start: Sat Mar 24 11:15:00 2007:540000
- Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:3974000
- Stop : Sat Mar 24 11:15:00 2007:3983000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:7510000
- Stop : Sat Mar 24 11:15:00 2007:7519000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:11054000
- Stop : Sat Mar 24 11:15:00 2007:11063000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:14638000
- Stop : Sat Mar 24 11:15:00 2007:14647000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:18301000
- Stop : Sat Mar 24 11:15:00 2007:18310000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:21901000
- Stop : Sat Mar 24 11:15:00 2007:21910000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:25526000
- Stop : Sat Mar 24 11:15:00 2007:25535000 --> 0:9000
- Start: Sat Mar 24 11:15:00 2007:29196000
- Stop : Sat Mar 24 11:15:00 2007:29206000 --> 0:10000
- Start: Sat Mar 24 11:15:00 2007:32826000
- Stop : Sat Mar 24 11:15:00 2007:32835000 --> 0:9000
- 10 iterations of getting Uptime
- 0:38977000 0:38986000 --> 0:9000
- 0:40324000 0:40332000 --> 0:8000
- 0:41636000 0:41645000 --> 0:9000
- 0:42949000 0:42958000 --> 0:9000
- 0:44295000 0:44304000 --> 0:9000
- 0:45608000 0:45617000 --> 0:9000
- 0:46921000 0:46930000 --> 0:9000
- 0:48282000 0:48291000 --> 0:9000
- 0:49595000 0:49603000 --> 0:8000
- 0:50908000 0:50917000 --> 0:9000
- 10 iterations of getting Uptime with different loop values
- loop of 10000 0:119488000 0:119704000 --> 0:216000
- loop of 20000 0:124028000 0:124463000 --> 0:435000
- loop of 30000 0:128567000 0:129220000 --> 0:653000
- loop of 40000 0:133097000 0:133964000 --> 0:867000
- loop of 50000 0:137643000 0:138728000 --> 0:1085000
- loop of 60000 0:142265000 0:143572000 --> 0:1307000
- loop of 70000 0:146894000 0:148416000 --> 0:1522000
- loop of 80000 0:151519000 0:153260000 --> 0:1741000
- loop of 90000 0:156145000 0:158099000 --> 0:1954000
- loop of 100000 0:160770000 0:162942000 --> 0:2172000
- \*** END OF NANOSECOND CLOCK TEST \***
-
-Paranoia Floating Point Application
-===================================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/paranoia/
-
-This sample application uses a public domain floating
-point and math library test to verify these capabilities of the
-RTEMS executive. Deviations between actual and expected results
-are reported to the screen. This is a very extensive test which
-tests all mathematical and number conversion functions.
-Paranoia is also very large and requires a long period of time
-to run. Problems which commonly prevent this test from
-executing to completion include stack overflow and FPU exception
-handlers not installed.
-
-Network Loopback Test
-=====================
-
-This sample application is in the following directory:
-.. code:: c
-
- ${RTEMS_ROOT}/testsuites/samples/loopback/
-
-This sample application uses the network loopback device to
-demonstrate the use of the RTEMS TCP/IP stack. This sample
-test illustrates the basic configuration and initialization
-of the TCP/IP stack as well as simple socket usage.
-
-.. COMMENT: COPYRIGHT (c) 1989-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-RTEMS Specific Utilities
-########################
-
-This section describes the additional commands
-available within the *RTEMS Development Environment*. Although
-some of these commands are of general use, most are included to
-provide some capability necessary to perform a required function
-in the development of the RTEMS executive, one of its support
-components, or an RTEMS based application.
-
-Some of the commands are implemented as C programs.
-However, most commands are implemented as Bourne shell scripts.
-Even if the current user has selected a different shell, the
-scripts will automatically invoke the Bourne shell during their
-execution lifetime.
-
-The commands are presented in UNIX manual page style
-for compatibility and convenience. A standard set of paragraph
-headers were used for all of the command descriptions. If a
-section contained no data, the paragraph header was omitted to
-conserve space. Each of the permissible paragraph headers and
-their contents are described below:
-
-``SYNOPSIS``
- describes the command syntax
-
-``DESCRIPTION``
- a full description of the command
-
-``OPTIONS``
- describes each of the permissible options for the command
-
-``NOTES``
- lists any special noteworthy comments about the command
-
-``ENVIRONMENT``
- describes all environment variables utilized by the command
-
-``EXAMPLES``
- illustrates the use of the command with specific examples
-
-``FILES``
- provides a list of major files that the command references
-
-``SEE ALSO``
- lists any relevant commands which can be consulted
-
-Most environment variables referenced by the commands
-are defined for the RTEMS Development Environment during the
-login procedure. During login, the user selects a default RTEMS
-environment through the use of the Modules package. This tool
-effectively sets the environment variables to provide a
-consistent development environment for a specific user.
-Additional environment variables within the RTEMS environment
-were set by the system administrator during installation. When
-specifying paths, a command description makes use of these
-environment variables.
-
-When referencing other commands in the SEE ALSO
-paragraph, the following notation is used: command(code).
-Where command is the name of a related command, and code is a
-section number. Valid section numbers are as follows:
-
-``1``
- Section 1 of the standard UNIX documentation
-
-``1G``
- Section 1 of the GNU documentation
-
-``1R``
- a manual page from this document, the RTEMS Development Environment Guide
-
-For example, ls(1) means see the standard ls command
-in section 1 of the UNIX documentation. gcc020(1G) means see
-the description of gcc020 in section 1 of the GNU documentation.
-
-.. COMMENT: packhex
-
-packhex - Compress Hexadecimal File
-===================================
-
-**SYNOPSIS**
-
-.. code:: c
-
- packhex <source >destination
-
-**DESCRIPTION**
-
-packhex accepts Intel Hexadecimal or Motorola Srecord
-on its standard input and attempts to pack as many contiguous
-bytes as possible into a single hexadecimal record. Many
-programs output hexadecimal records which are less than 80 bytes
-long (for human viewing). The overhead required by each
-unnecessary record is significant and packhex can often reduce
-the size of the download image by 20%. packhex attempts to
-output records which are as long as the hexadecimal format
-allows.
-
-**OPTIONS**
-
-This command has no options.
-
-**EXAMPLES**
-
-Assume the current directory contains the Motorola
-Srecord file download.sr. Then executing the command:
-.. code:: c
-
- packhex <download.sr >packed.sr
-
-will generate the file packed.sr which is usually
-smaller than download.sr.
-
-**CREDITS**
-
-The source for packhex first appeared in the May 1993
-issue of Embedded Systems magazine. The code was downloaded
-from their BBS. Unfortunately, the author’s name was not
-provided in the listing.
-
-unhex - Convert Hexadecimal File into Binary Equivalent
-=======================================================
-
-**SYNOPSIS**
-
-.. code:: shell
-
- unhex [-valF] [-o file] [file [file ...] ]
-
-**DESCRIPTION**
-
-unhex accepts Intel Hexadecimal, Motorola Srecord, or
-TI ’B’ records and converts them to their binary equivalent.
-The output may sent to standout or may be placed in a specified
-file with the -o option. The designated output file may not be
-an input file. Multiple input files may be specified with their
-outputs logically concatenated into the output file.
-
-**OPTIONS**
-
-This command has the following options:
-
-``v``
- Verbose
-
-``a base``
- First byte of output corresponds with base
- address
-
-``l``
- Linear Output
-
-``o file``
- Output File
-
-``F k_bits``
- Fill holes in input with 0xFFs up to k_bits * 1024 bits
-
-**EXAMPLES**
-
-The following command will create a binary equivalent
-file for the two Motorola S record files in the specified output
-file binary.bin:
-.. code:: c
-
- unhex -o binary.bin downloadA.sr downloadB.sr
-
-Command and Variable Index
-##########################
-
-There are currently no Command and Variable Index entries.
-
-Concept Index
-#############
-
-There are currently no Concept Index entries.
-
diff --git a/filesystem/filesystem_old_reference_only.rst b/filesystem/filesystem_old_reference_only.rst
deleted file mode 100644
index f8c1746..0000000
--- a/filesystem/filesystem_old_reference_only.rst
+++ /dev/null
@@ -1,4602 +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 Filesystem Design 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 RTEMS Filesystem Design Guide
-
-=============================
-RTEMS Filesystem Design 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 Filesystem Design Guide
-#############################
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Preface
-#######
-
-This document describes the implementation of the RTEMS filesystem
-infrastructure. This infrastructure supports the following
-capabilities:
-
-- Mountable file systems
-
-- Hierarchical file system directory structure
-
-- POSIX compliant set of routines for the manipulation of files and directories
-
-- Individual file and directory support for the following:
- # Permissions for read, write and execute
- # User ID
- # Group ID
- # Access time
- # Modification time
- # Creation time
-
-- Hard links to files and directories
-
-- Symbolic links to files and directories
-
-This has been implemented to provide the framework for a UNIX-like
-file system support. POSIX file and directory functions have been
-implemented that allow a standard method of accessing file, device and
-directory information within file systems. The file system concept that
-has been implemented allows for expansion and adaptation of the file
-system to a variety of existing and future data storage devices. To this
-end, file system mount and unmount capabilities have been included in this
-RTEMS framework.
-
-This framework slightly alters the manner in which devices are handled
-under RTEMS from that of public release 4.0.0 and earlier. Devices that
-are defined under a given RTEMS configuration will now be registered as
-files in a mounted file system. Access to these device drivers and their
-associated devices may now be performed through the traditional file system
-open(), read(), write(), lseek(), fstat() and ioctl() functions in addition
-to the interface provided by the IO Manager in the RTEMS Classic API.
-
-An In-Memory File System (IMFS) is included which provides full POSIX
-filesystem functionality yet is RAM based. The IMFS maintains a
-node structure for each file, device, and directory in each mounted
-instantiation of its file system. The node structure is used to
-manage ownership, access rights, access time, modification time,
-and creation time. A union of structures within the IMFS nodal
-structure provide for manipulation of file data, device selection,
-or directory content as required by the nodal type. Manipulation of
-these properties is accomplished through the POSIX set of file and
-directory functions. In addition to being useful in its own right,
-the IMFS serves as a full featured example filesystem.
-
-The intended audience for this document is those persons implementing
-their own filesystem. Users of the filesystem may find information
-on the implementation useful. But the user interface to the filesystem
-is through the ISO/ANSI C Library and POSIX 1003.1b file and directory
-APIs.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Pathname Evaluation
-###################
-
-This chapter describes the pathname evaluation process for the
-RTEMS Filesystem Infrastructure.
-.. code:: c
-
- XXX Include graphic of the path evaluation process
-
-Pathname Evaluation Handlers
-============================
-
-There are two pathname evaluation routines. The handler patheval()
-is called to find, verify privlages on and return information on a node
-that exists. The handler evalformake() is called to find, verify
-permissions, and return information on a node that is to become a parent.
-Additionally, evalformake() returns a pointer to the start of the name of
-the new node to be created.
-
-Pathname evaluation is specific to a filesystem.
-Each filesystem is required to provide both a patheval() and an evalformake()
-routine. Both of these routines gets a name to evaluate and a node indicating
-where to start the evaluation.
-
-Crossing a Mount Point During Path Evaluation
-=============================================
-
-If the filesystem supports the mount command, the evaluate routines
-must handle crossing the mountpoint. The evaluate routine should evaluate
-the name upto the first directory node where the new filesystem is mounted.
-The filesystem may process terminator characters prior to calling the
-evaluate routine for the new filesystem. A pointer to the portion of the
-name which has not been evaluated along with the root node of the new
-file system ( gotten from the mount table entry ) is passed to the correct
-mounted filesystem evaluate routine.
-
-The rtems_filesystem_location_info_t Structure
-==============================================
-
-The ``rtems_filesystem_location_info_t`` structure contains all information
-necessary for identification of a node.
-
-The generic rtems filesystem code defines two global
-rtems_filesystem_location_info_t structures, the``rtems_filesystem_root`` and the ``rtems_filesystem_current``.
-Both are initially defined to be the root node of the base filesystem.
-Once the chdir command is correctly used the ``rtems_filesystem_current``
-is set to the location specified by the command.
-
-The filesystem generic code peeks at the first character in the name to be
-evaluated. If this character is a valid seperator, the``rtems_filesystem_root`` is used as the node to start the evaluation
-with. Otherwise, the ``rtems_filesystem_current`` node is used as the
-node to start evaluating with. Therefore, a valid
-rtems_filesystem_location_info_t is given to the evaluate routine to start
-evaluation with. The evaluate routines are then responsible for making
-any changes necessary to this structure to correspond to the name being
-parsed.
-.. code:: c
-
- struct rtems_filesystem_location_info_tt {
- void \*node_access;
- rtems_filesystem_file_handlers_r \*handlers;
- rtems_filesystem_operations_table \*ops;
- rtems_filesystem_mount_table_entry_t \*mt_entry;
- };
-
-*node_access*
- This element is filesystem specific. A filesystem can define and store
- any information necessary to identify a node at this location. This element
- is normally filled in by the filesystem’s evaluate routine. For the
- filesystem’s root node, the filesystem’s initilization routine should
- fill this in, and it should remain valid until the instance of the
- filesystem is unmounted.
-
-*handlers*
- This element is defined as a set of routines that may change within a
- given filesystem based upon node type. For example a directory and a
- memory file may have to completely different read routines. This element
- is set to an initialization state defined by the mount table, and may
- be set to the desired state by the evaluation routines.
-
-*ops*
- This element is defined as a set of routines that remain static for the
- filesystem. This element identifies entry points into the filesystem
- to the generic code.
-
-*mt_entry*
- This element identifies the mount table entry for this instance of the
- filesystem.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-System Initialization
-#####################
-
-After the RTEMS initialization is performed, the application’s
-initialization will be performed. Part of initialization is a call to
-rtems_filesystem_initialize(). This routine will mount the ‘In Memory File
-System’ as the base filesystem. Mounting the base filesystem consists
-of the following:
-
-- Initialization of mount table chain control structure
-
-- Allocation of a ``jnode`` structure that will server as the root node
- of the ‘In Memory Filesystem’
-
-- Initialization of the allocated ``jnode`` with the appropriate OPS,
- directory handlers and pathconf limits and options.
-
-- Allocation of a memory region for filesystem specific global
- management variables
-
-- Creation of first mount table entry for the base filesystem
-
-- Initialization of the first mount table chain entry to indicate that
- the mount point is NULL and the mounted filesystem is the base file
- system
-
-After the base filesystem has been mounted, the following operations are
-performed under its directory structure:
-
-- Creation of the /dev directory
-
-- Registration of devices under /dev directory
-
-Base Filesystem
-===============
-
-RTEMS initially mounts a RAM based file system known as the base file system.
-The root directory of this file system tree serves as the logical root of the
-directory hierarchy (Figure 3). Under the root directory a ‘/dev’ directory
-is created under which all I/O device directories and files are registered as
-part of the file system hierarchy.
-.. code:: c
-
- Figure of the tree structure goes here.
-
-A RAM based file system draws its management resources from memory. File and
-directory nodes are simply allocated blocks of memory. Data associated with
-regular files is stored in collections of memory blocks. When the system is
-turned off or restarted all memory-based components of the file system are
-lost.
-
-The base file system serves as a starting point for the mounting of file
-systems that are resident on semi-permanent storage media. Examples of such
-media include non- volatile memory, flash memory and IDE hard disk drives
-(Figure 3). File systems of other types will be mounted onto mount points
-within the base file system or other file systems that are subordinate to the
-base file system. The framework set up under the base file system will allow
-for these new file system types and the unique data and functionality that is
-required to manage the future file systems.
-
-Base Filesystem Mounting
-------------------------
-
-At present, the first file system to be mounted is the ‘In Memory File
-System’. It is mounted using a standard MOUNT() command in which the mount
-point is NULL. This flags the mount as the first file system to be
-registered under the operating system and appropriate initialization of file
-system management information is performed (See figures 4 and 5). If a
-different file system type is desired as the base file system, alterations
-must be made to base_fs.c. This routine handles the mount of the base file
-system.
-
-.. code:: c
-
- Figure of the mount table chain goes here.
-
-Once the root of the base file system has been established and it has been
-recorded as the mount point of the base file system, devices are integrated
-into the base file system. For every device that is configured into the
-system (See ioman.c) a device registration process is performed. Device
-registration produces a unique dev_t handle that consists of a major and
-minor device number. In addition, the configuration information for each
-device contains a text string that represents the fully qualified pathname to
-that device’s place in the base file system’s hierarchy. A file system node
-is created for the device along the specified registration path.
-
-.. code:: c
-
- Figure of the Mount Table Processing goes here.
-
-Note: Other file systems can be mounted but they are mounted onto points
-(directory mount points) in the base file system.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Mounting and Unmounting Filesystems
-###################################
-
-Mount Points
-============
-
-The following is the list of the characteristics of a mount point:
-
-- The mount point must be a directory. It may have files and other
- directories under it. These files and directories will be hidden when the
- filesystem is mounted.
-
-- The task must have read/write/execute permissions to the mount point
- or the mount attempt will be rejected.
-
-- Only one filesystem can be mounted to a single mount point.
-
-- The Root of the mountable filesystem will be referenced by the name
- of the mount point after the mount is complete.
-
-Mount Table Chain
-=================
-
-The mount table chain is a dynamic list of structures that describe
-mounted filesystems a specific points in the filesystem hierarchy. It is
-initialized to an empty state during the base filesystem initialization.
-The mount operation will add entries to the mount table chain. The
-un-mount operation will remove entries from the mount table chain.
-
-Each entry in the mount table chain is of the following type:
-.. code:: c
-
- struct rtems_filesystem_mount_table_entry_tt
- {
- Chain_Node Node;
- rtems_filesystem_location_info_t mt_point_node;
- rtems_filesystem_location_info_t mt_fs_root;
- int options;
- void \*fs_info;
- rtems_filesystem_limits_and_options_t pathconf_limits_and_options;
- /*
- * When someone adds a mounted filesystem on a real device,
- * this will need to be used.
- *
- * The best option long term for this is probably an
- * open file descriptor.
- \*/
- char \*dev;
- };
-
-*Node*
- The Node is used to produce a linked list of mount table entry nodes.
-
-*mt_point_node*
- The mt_point_node contains all information necessary to access the
- directory where a filesystem is mounted onto. This element may contain
- memory that is allocated during a path evaluation of the filesystem
- containing the mountpoint directory. The generic code allows this
- memory to be returned by unmount when the filesystem identified by
- mt_fs_root is unmounted.
-
-*mt_fs_root*
- The mt_fs_root contains all information necessary to identify the root
- of the mounted filesystem. The user is never allowed access to this
- node by the generic code, but it is used to identify to the mounted
- filesystem where to start evaluation of pathnames at.
-
-*options*
- XXX
-
-*fs_info*
- The fs_info element is a location available for use by the mounted file
- system to identify unique things applicable to this instance of the file
- system. For example the IMFS uses this space to provide node
- identification that is unique for each instance (mounting) of the filesystem.
-
-*pathconf_limits_and_options*
- XXX
-
-*dev*
- This character string represents the device where the filesystem will reside.
-
-Adding entries to the chain during mount
-========================================
-
-When a filesystem is mounted, its presence and location in the file
-system hierarchy is recorded in a dynamic list structure known as a chain.
-A unique rtems_filesystem_mount_table_entry_tt structure is logged for
-each filesystem that is mounted. This includes the base filesystem.
-
-Removing entries from the chain during unmount
-==============================================
-
-When a filesystem is dismounted its entry in the mount table chain is
-extracted and the memory for this entry is freed.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-System Call Development Notes
-#############################
-
-This set of routines represents the application’s interface to files and directories
-under the RTEMS filesystem. All routines are compliant with POSIX standards if a
-specific interface has been established. The list below represents the routines that have
-been included as part of the application’s interface.
-
-# access()
-
-# chdir()
-
-# chmod()
-
-# chown()
-
-# close()
-
-# closedir()
-
-# dup()
-
-# dup2()
-
-# fchmod()
-
-# fcntl()
-
-# fdatasync()
-
-# fpathconf()
-
-# fstat()
-
-# ioctl()
-
-# link()
-
-# lseek()
-
-# mkdir()
-
-# mkfifo()
-
-# mknod()
-
-# mount()
-
-# open()
-
-# opendir()
-
-# pathconf()
-
-# read()
-
-# readdir()
-
-# unmount()
-
-The sections that follow provide developmental information concerning each
-of these functions.
-
-.. COMMENT: @page
-
-access
-======
-
-**File:**
-
-access.c
-
-**Processing:**
-
-This routine is layered on the stat() function. It acquires the current
-status information for the specified file and then determines if the
-caller has the ability to access the file for read, write or execute
-according to the mode argument to this function.
-
-**Development Comments:**
-
-This routine is layered on top of the stat() function. As long as the
-st_mode element in the returned structure follow the standard UNIX
-conventions, this function should support other filesystems without
-alteration.
-
-.. COMMENT: @page
-
-chdir
-=====
-
-**File:**
-
-chdir.c
-
-**Processing:**
-
-This routine will determine if the pathname that we are attempting to make
-that current directory exists and is in fact a directory. If these
-conditions are met the global indication of the current directory
-(rtems_filesystem_current) is set to the rtems_filesystem_location_info_t
-structure that is returned by the rtems_filesystem_evaluate_path()
-routine.
-
-**Development Comments:**
-
-This routine is layered on the rtems_filesystem_evaluate_path() routine
-and the filesystem specific OP table function node_type().
-
-The routine node_type() must be a routine provided for each filesystem
-since it must access the filesystems node information to determine which
-of the following types the node is:
-
-- RTEMS_FILESYSTEM_DIRECTORY
-
-- RTEMS_FILESYSTEM_DEVICE
-
-- RTEMS_FILESYSTEM_HARD_LINK
-
-- RTEMS_FILESYSTEM_MEMORY_FILE
-
-This acknowledges that the form of the node management information can
-vary from one filesystem implementation to another.
-
-RTEMS has a special global structure that maintains the current directory
-location. This global variable is of type rtems_filesystem_location_info_t
-and is called rtems_filesystem_current. This structure is not always
-valid. In order to determine if the structure is valid, you must first
-test the node_access element of this structure. If the pointer is NULL,
-then the structure does not contain a valid indication of what the current
-directory is.
-
-.. COMMENT: @page
-
-chmod
-=====
-
-**File:**
-
-chmod.c
-
-**Processing:**
-
-This routine is layered on the open(), fchmod() and close() functions. As
-long as the standard interpretation of the mode_t value is maintained,
-this routine should not need modification to support other filesystems.
-
-**Development Comments:**
-
-The routine first determines if the selected file can be open with
-read/write access. This is required to allow modification of the mode
-associated with the selected path.
-
-The fchmod() function is used to actually change the mode of the path
-using the integer file descriptor returned by the open() function.
-
-After mode modification, the open file descriptor is closed.
-
-.. COMMENT: @page
-
-chown
-=====
-
-**File:**
-
-chown.c
-
-**Processing:**
-
-This routine is layered on the rtems_filesystem_evaluate_path() and the
-file system specific chown() routine that is specified in the OPS table
-for the file system.
-
-**Development Comments:**
-
-rtems_filesystem_evaluate_path() is used to determine if the path
-specified actually exists. If it does a rtems_filesystem_location_info_t
-structure will be obtained that allows the shell function to locate the
-OPS table that is to be used for this filesystem.
-
-It is possible that the chown() function that should be in the OPS table
-is not defined. A test for a non-NULL OPS table chown() entry is performed
-before the function is called.
-
-If the chown() function is defined in the indicated OPS table, the
-function is called with the rtems_filesystem_location_info_t structure
-returned from the path evaluation routine, the desired owner, and group
-information.
-
-.. COMMENT: @page
-
-close
-=====
-
-**File:**
-
-close.c
-
-**Processing:**
-
-This routine will allow for the closing of both network connections and
-file system devices. If the file descriptor is associated with a network
-device, the appropriate network function handler will be selected from a
-table of previously registered network functions (rtems_libio_handlers)
-and that function will be invoked.
-
-If the file descriptor refers to an entry in the filesystem, the
-appropriate handler will be selected using information that has been
-placed in the file control block for the device (rtems_libio_t structure).
-
-**Development Comments:**
-
-rtems_file_descriptor_type examines some of the upper bits of the file
-descriptor index. If it finds that the upper bits are set in the file
-descriptor index, the device referenced is a network device.
-
-Network device handlers are obtained from a special registration table
-(rtems_libio_handlers) that is set up during network initialization. The
-network handler invoked and the status of the network handler will be
-returned to the calling process.
-
-If none of the upper bits are set in the file descriptor index, the file
-descriptor refers to an element of the RTEMS filesystem.
-
-The following sequence will be performed for any filesystem file
-descriptor:
-
-# Use the rtems_libio_iop() function to obtain the rtems_libio_t
- structure for the file descriptor
-
-# Range check the file descriptor using rtems_libio_check_fd()
-
-# Determine if there is actually a function in the selected handler
- table that processes the close() operation for the filesystem and node
- type selected. This is generally done to avoid execution attempts on
- functions that have not been implemented.
-
-# If the function has been defined it is invoked with the file control
- block pointer as its argument.
-
-# The file control block that was associated with the open file
- descriptor is marked as free using rtems_libio_free().
-
-# The return code from the close handler is then passed back to the
- calling program.
-
-.. COMMENT: @page
-
-closedir
-========
-
-**File:**
-
-closedir.c
-
-**Processing:**
-
-The code was obtained from the BSD group. This routine must clean up the
-memory resources that are required to track an open directory. The code is
-layered on the close() function and standard memory free() functions. It
-should not require alterations to support other filesystems.
-
-**Development Comments:**
-
-The routine alters the file descriptor and the index into the DIR
-structure to make it an invalid file descriptor. Apparently the memory
-that is about to be freed may still be referenced before it is
-reallocated.
-
-The dd_buf structure’s memory is reallocated before the control structure
-that contains the pointer to the dd_buf region.
-
-DIR control memory is reallocated.
-
-The close() function is used to free the file descriptor index.
-
-.. COMMENT: @page
-
-dup() Unimplemented
-========================
-
-**File:**
-
-dup.c
-
-**Processing:**
-
-**Development Comments:**
-
-.. COMMENT: @page
-
-dup2() Unimplemented
-=========================
-
-**File:**
-
-dup2.c
-
-**Processing:**
-
-**Development Comments:**
-
-.. COMMENT: @page
-
-fchmod
-======
-
-**File:**
-
-fchmod.c
-
-**Processing:**
-
-This routine will alter the permissions of a node in a filesystem. It is
-layered on the following functions and macros:
-
-- rtems_file_descriptor_type()
-
-- rtems_libio_iop()
-
-- rtems_libio_check_fd()
-
-- rtems_libio_check_permissions()
-
-- fchmod() function that is referenced by the handler table in the
- file control block associated with this file descriptor
-
-**Development Comments:**
-
-The routine will test to see if the file descriptor index is associated
-with a network connection. If it is, an error is returned from this
-routine.
-
-The file descriptor index is used to obtain the associated file control
-block.
-
-The file descriptor value is range checked.
-
-The file control block is examined to determine if it has write
-permissions to allow us to alter the mode of the file.
-
-A test is made to determine if the handler table that is referenced in the
-file control block contains an entry for the fchmod() handler function. If
-it does not, an error is returned to the calling routine.
-
-If the fchmod() handler function exists, it is called with the file
-control block and the desired mode as parameters.
-
-.. COMMENT: @page
-
-fcntl()
-=======
-
-**File:**
-
-fcntl.c
-
-**Processing:**
-
-This routine currently only interacts with the file control block. If the
-structure of the file control block and the associated meanings do not
-change, the partial implementation of fcntl() should remain unaltered for
-other filesystem implementations.
-
-**Development Comments:**
-
-The only commands that have been implemented are the F_GETFD and F_SETFD.
-The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the``flags`` element of the file control block associated with the file
-descriptor index.
-
-The current implementation of the function performs the sequence of
-operations below:
-
-# Test to see if we are trying to operate on a file descriptor
- associated with a network connection
-
-# Obtain the file control block that is associated with the file
- descriptor index
-
-# Perform a range check on the file descriptor index.
-
-.. COMMENT: @page
-
-fdatasync
-=========
-
-**File:**
-
-fdatasync.c
-
-**Processing:**
-
-This routine is a template in the in memory filesystem that will route us to the
-appropriate handler function to carry out the fdatasync() processing. In the in
-memory filesystem this function is not necessary. Its function in a disk based file
-system that employs a memory cache is to flush all memory based data buffers to
-disk. It is layered on the following functions and macros:
-
-- rtems_file_descriptor_type()
-
-- rtems_libio_iop()
-
-- rtems_libio_check_fd()
-
-- rtems_libio_check_permissions()
-
-- fdatasync() function that is referenced by the handler table in the
- file control block associated with this file descriptor
-
-**Development Comments:**
-
-The routine will test to see if the file descriptor index is associated
-with a network connection. If it is, an error is returned from this
-routine.
-
-The file descriptor index is used to obtain the associated file control
-block.
-
-The file descriptor value is range checked.
-
-The file control block is examined to determine if it has write
-permissions to the file.
-
-A test is made to determine if the handler table that is referenced in the
-file control block contains an entry for the fdatasync() handler function.
-If it does not an error is returned to the calling routine.
-
-If the fdatasync() handler function exists, it is called with the file
-control block as its parameter.
-
-.. COMMENT: @page
-
-fpathconf
-=========
-
-**File:**
-
-fpathconf.c
-
-**Processing:**
-
-This routine is layered on the following functions and macros:
-
-- rtems_file_descriptor_type()
-
-- rtems_libio_iop()
-
-- rtems_libio_check_fd()
-
-- rtems_libio_check_permissions()
-
-When a filesystem is mounted, a set of constants is specified for the
-filesystem. These constants are stored with the mount table entry for the
-filesystem. These constants appear in the POSIX standard and are listed
-below.
-
-- PCLINKMAX
-
-- PCMAXCANON
-
-- PCMAXINPUT
-
-- PCNAMEMAX
-
-- PCPATHMAX
-
-- PCPIPEBUF
-
-- PCCHOWNRESTRICTED
-
-- PCNOTRUNC
-
-- PCVDISABLE
-
-- PCASYNCIO
-
-- PCPRIOIO
-
-- PCSYNCIO
-
-This routine will find the mount table information associated the file
-control block for the specified file descriptor parameter. The mount table
-entry structure contains a set of filesystem specific constants that can
-be accessed by individual identifiers.
-
-**Development Comments:**
-
-The routine will test to see if the file descriptor index is associated
-with a network connection. If it is, an error is returned from this
-routine.
-
-The file descriptor index is used to obtain the associated file control
-block.
-
-The file descriptor value is range checked.
-
-The file control block is examined to determine if it has read permissions
-to the file.
-
-Pathinfo in the file control block is used to locate the mount table entry
-for the filesystem associated with the file descriptor.
-
-The mount table entry contains the pathconf_limits_and_options element.
-This element is a table of constants that is associated with the
-filesystem.
-
-The name argument is used to reference the desired constant from the
-pathconf_limits_and_options table.
-
-.. COMMENT: @page
-
-fstat
-=====
-
-**File:**
-
-fstat.c
-
-**Processing:**
-
-This routine will return information concerning a file or network
-connection. If the file descriptor is associated with a network
-connection, the current implementation of ``fstat()`` will return a
-mode set to ``S_IFSOCK``. In a later version, this routine will map the
-status of a network connection to an external handler routine.
-
-If the file descriptor is associated with a node under a filesystem, the
-fstat() routine will map to the fstat() function taken from the node
-handler table.
-
-**Development Comments:**
-
-This routine validates that the struct stat pointer is not NULL so that
-the return location is valid.
-
-The struct stat is then initialized to all zeros.
-
-rtems_file_descriptor_type() is then used to determine if the file
-descriptor is associated with a network connection. If it is, network
-status processing is performed. In the current implementation, the file
-descriptor type processing needs to be improved. It currently just drops
-into the normal processing for file system nodes.
-
-If the file descriptor is associated with a node under a filesystem, the
-following steps are performed:
-
-# Obtain the file control block that is associated with the file descriptor
- index.
-
-# Range check the file descriptor index.
-
-# Test to see if there is a non-NULL function pointer in the handler
- table for the fstat() function. If there is, invoke the function with the
- file control block and the pointer to the stat structure.
-
-.. COMMENT: @page
-
-ioctl
-=====
-
-**File:**
-
-ioctl.c
-
-**Processing:**
-
-Not defined in the POSIX 1003.1b standard but commonly supported in most
-UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine
-is layered on external network handlers and filesystem specific handlers.
-The development of new filesystems should not alter the basic processing
-performed by this routine.
-
-**Development Comments:**
-
-The file descriptor is examined to determine if it is associated with a
-network device. If it is processing is mapped to an external network
-handler. The value returned by this handler is then returned to the
-calling program.
-
-File descriptors that are associated with a filesystem undergo the
-following processing:
-
-# The file descriptor index is used to obtain the associated file
- control block.
-
-# The file descriptor value is range checked.
-
-# A test is made to determine if the handler table that is referenced
- in the file control block contains an entry for the ioctl() handler
- function. If it does not, an error is returned to the calling routine.
-
-# If the ioctl() handler function exists, it is called with the file
- control block, the command and buffer as its parameters.
-
-# The return code from this function is then sent to the calling
- routine.
-
-.. COMMENT: @page
-
-link
-====
-
-**File:**
-
-link.c
-
-**Processing:**
-
-This routine will establish a hard link to a file, directory or a device.
-The target of the hard link must be in the same filesystem as the new link
-being created. A link to an existing link is also permitted but the
-existing link is evaluated before the new link is made. This implies that
-links to links are reduced to links to files, directories or devices
-before they are made.
-
-**Development Comments:**
-
-Calling parameters:
-const char \*existing
-const char \*new
-
-link() will determine if the target of the link actually exists using
-rtems_filesystem_evaluate_path()
-
-rtems_filesystem_get_start_loc() is used to determine where to start the
-path evaluation of the new name. This macro examines the first characters
-of the name to see if the name of the new link starts with a
-rtems_filesystem_is_separator. If it does the search starts from the root
-of the RTEMS filesystem; otherwise the search will start from the current
-directory.
-
-The OPS table evalformake() function for the parent’s filesystem is used
-to locate the node that will be the parent of the new link. It will also
-locate the start of the new path’s name. This name will be used to define
-a child under the parent directory.
-
-If the parent is found, the routine will determine if the hard link that
-we are trying to create will cross a filesystem boundary. This is not
-permitted for hard-links.
-
-If the hard-link does not cross a filesystem boundary, a check is
-performed to determine if the OPS table contains an entry for the link()
-function.
-
-If a link() function is defined, the OPS table link() function will be
-called to establish the actual link within the filesystem.
-
-The return code from the OPS table link() function is returned to the
-calling program.
-
-.. COMMENT: @page
-
-lseek
-=====
-
-**File:**
-
-lseek.c
-
-**Processing:**
-
-This routine is layered on both external handlers and filesystem / node
-type specific handlers. This routine should allow for the support of new
-filesystems without modification.
-
-**Development Comments:**
-
-This routine will determine if the file descriptor is associated with a
-network device. If it is lseek will map to an external network handler.
-The handler will be called with the file descriptor, offset and whence as
-its calling parameters. The return code from the external handler will be
-returned to the calling routine.
-
-If the file descriptor is not associated with a network connection, it is
-associated with a node in a filesystem. The following steps will be
-performed for filesystem nodes:
-
-# The file descriptor is used to obtain the file control block for the
- node.
-
-# The file descriptor is range checked.
-
-# The offset element of the file control block is altered as indicated
- by the offset and whence calling parameters
-
-# The handler table in the file control block is examined to determine
- if it contains an entry for the lseek() function. If it does not an error
- is returned to the calling program.
-
-# The lseek() function from the designated handler table is called
- with the file control block, offset and whence as calling arguments
-
-# The return code from the lseek() handler function is returned to the
- calling program
-
-.. COMMENT: @page
-
-mkdir
-=====
-
-**File:**
-
-mkdir.c
-
-**Processing:**
-
-This routine attempts to create a directory node under the filesystem. The
-routine is layered the mknod() function.
-
-**Development Comments:**
-
-See mknod() for developmental comments.
-
-.. COMMENT: @page
-
-mkfifo
-======
-
-**File:**
-
-mkfifo.c
-
-**Processing:**
-
-This routine attempts to create a FIFO node under the filesystem. The
-routine is layered the mknod() function.
-
-**Development Comments:**
-
-See mknod() for developmental comments
-
-.. COMMENT: @page
-
-mknod
-=====
-
-**File:**
-
-mknod.c
-
-**Processing:**
-
-This function will allow for the creation of the following types of nodes
-under the filesystem:
-
-- directories
-
-- regular files
-
-- character devices
-
-- block devices
-
-- fifos
-
-At the present time, an attempt to create a FIFO will result in an ENOTSUP
-error to the calling function. This routine is layered the filesystem
-specific routines evalformake and mknod. The introduction of a new
-filesystem must include its own evalformake and mknod function to support
-the generic mknod() function. Under this condition the generic mknod()
-function should accommodate other filesystem types without alteration.
-
-**Development Comments:**
-
-Test for nodal types - I thought that this test should look like the
-following code:
-.. code:: c
-
- if ( (mode & S_IFDIR) = = S_IFDIR) \||
- (mode & S_IFREG) = = S_IFREG) \||
- (mode & S_IFCHR) = = S_IFCHR) \||
- (mode & S_IFBLK) = = S_IFBLK) \||
- (mode & S_IFIFO) = = S_IFIFO))
- Set_errno_and_return_minus_one (EINVAL);
-
-Where:
-
-- S_IFREG (0100000) - Creation of a regular file
-
-- S_IFCHR (0020000) - Creation of a character device
-
-- S_IFBLK (0060000) - Creation of a block device
-
-- S_IFIFO (0010000) - Creation of a FIFO
-
-Determine if the pathname that we are trying to create starts at the root
-directory or is relative to the current directory using the
-rtems_filesystem_get_start_loc() function.
-
-Determine if the pathname leads to a valid directory that can be accessed
-for the creation of a node.
-
-If the pathname is a valid location to create a node, verify that a
-filesystem specific mknod() function exists.
-
-If the mknod() function exists, call the filesystem specific mknod()
-function. Pass the name, mode, device type and the location information
-associated with the directory under which the node will be created.
-
-.. COMMENT: @page
-
-mount
-=====
-
-**File:**
-
-mount.c
-
-Arguments (Not a standard POSIX call):
-
-rtems_filesystem_mount_table_entry_t \**mt_entry,
-
-If the mount operation is successful, this pointer to a pointer will be
-set to reference the mount table chain entry that has been allocated for
-this file system mount.
-
-rtems_filesystem_operations_table \*fs_ops,
-
-This is a pointer to a table of functions that are associated with the
-file system that we are about to mount. This is the mechanism to selected
-file system type without keeping a dynamic database of all possible file
-system types that are valid for the mount operation. Using this method, it
-is only necessary to configure the filesystems that we wish to use into
-the RTEMS build. Unused filesystems types will not be drawn into the
-build.
-
-char \*fsoptions,
-
-This argument points to a string that selects mounting for read only
-access or read/write access. Valid states are "RO" and "RW"
-
-char \*device,
-
-This argument is reserved for the name of a device that will be used to
-access the filesystem information. Current filesystem implementations are
-memory based and do not require a device to access filesystem information.
-
-char \*mount_point
-
-This is a pathname to a directory in a currently mounted filesystem that
-allows read, write and execute permissions. If successful, the node found
-by evaluating this name, is stored in the mt_entry.
-
-**Processing:**
-
-This routine will handle the mounting of a filesystem on a mount point. If
-the operation is successful, a pointer to the mount table chain entry
-associated with the mounted filesystem will be returned to the calling
-function. The specifics about the processing required at the mount point
-and within the filesystem being mounted is isolated in the filesystem
-specific mount() and fsmount_me() functions. This allows the generic
-mount() function to remain unaltered even if new filesystem types are
-introduced.
-
-**Development Comments:**
-
-This routine will use get_file_system_options() to determine if the mount
-options are valid ("RO" or "RW").
-
-It confirms that a filesystem ops-table has been selected.
-
-Space is allocated for a mount table entry and selective elements of the
-temporary mount table entry are initialized.
-
-If a mount point is specified: The mount point is examined to determine
-that it is a directory and also has the appropriate permissions to allow a
-filesystem to be mounted.
-
-The current mount table chain is searched to determine that there is not
-another filesystem mounted at the mount point we are trying to mount onto.
-
-If a mount function is defined in the ops table for the filesystem
-containing the mount point, it is called at this time.
-
-If no mount point is specified: Processing if performed to set up the
-mount table chain entry as the base filesystem.
-
-If the fsmount_me() function is specified for ops-table of the filesystem
-being mounted, that function is called to initialize for the new
-filesystem.
-
-On successful completion, the temporary mount table entry will be placed
-on the mount table chain to record the presence of the mounted filesystem.
-
-.. COMMENT: @page
-
-open
-====
-
-**File:**
-
-open.c
-
-**Processing:**
-
-This routine is layered on both RTEMS calls and filesystem specific
-implementations of the open() function. These functional interfaces should
-not change for new filesystems and therefore this code should be stable as
-new file systems are introduced.
-
-**Development Comments:**
-
-This routine will allocate a file control block for the file or device
-that we are about to open.
-
-It will then test to see if the pathname exists. If it does a
-rtems_filesystem_location_info_t data structure will be filled out. This
-structure contains information that associates node information,
-filesystem specific functions and mount table chain information with the
-pathname.
-
-If the create option has been it will attempt to create a node for a
-regular file along the specified path. If a file already exists along this
-path, an error will be generated; otherwise, a node will be allocated for
-the file under the filesystem that contains the pathname. When a new node
-is created, it is also evaluated so that an appropriate
-rtems_filesystem_location_info_t data structure can be filled out for the
-newly created node.
-
-If the file exists or the new file was created successfully, the file
-control block structure will be initialized with handler table
-information, node information and the rtems_filesystem_location_info_t
-data structure that describes the node and filesystem data in detail.
-
-If an open() function exists in the filesystem specific handlers table for
-the node that we are trying to open, it will be called at this time.
-
-If any error is detected in the process, cleanup is performed. It consists
-of freeing the file control block structure that was allocated at the
-beginning of the generic open() routine.
-
-On a successful open(), the index into the file descriptor table will be
-calculated and returned to the calling routine.
-
-.. COMMENT: @page
-
-opendir
-=======
-
-**File:**
-
-opendir.c
-
-**Processing:**
-
-This routine will attempt to open a directory for read access. It will
-setup a DIR control structure that will be used to access directory
-information. This routine is layered on the generic open() routine and
-filesystem specific directory processing routines.
-
-**Development Comments:**
-
-The BSD group provided this routine.
-
-.. COMMENT: @page
-
-pathconf
-========
-
-**File:**
-
-pathconf.c
-
-**Processing:**
-
-This routine will obtain the value of one of the path configuration
-parameters and return it to the calling routine. It is layered on the
-generic open() and fpathconf() functions. These interfaces should not
-change with the addition of new filesystem types.
-
-**Development Comments:**
-
-This routine will try to open the file indicated by path.
-
-If successful, the file descriptor will be used to access the pathconf
-value specified by ``name`` using the fpathconf() function.
-
-The file that was accessed is then closed.
-
-.. COMMENT: @page
-
-read
-====
-
-**File:**
-
-deviceio.c
-
-**Processing:**
-
-This routine is layered on a set of RTEMS calls and filesystem specific
-read operations. The functions are layered in such a way as to isolate
-them from change as new filesystems are introduced.
-
-**Development Comments:**
-
-This routine will examine the type of file descriptor it is sent.
-
-If the file descriptor is associated with a network device, the read
-function will be mapped to a special network handler. The return code from
-the network handler will then be sent as the return code from generic
-read() function.
-
-For file descriptors that are associated with the filesystem the following
-sequence will be performed:
-
-# Obtain the file control block associated with the file descriptor
-
-# Range check the file descriptor
-
-# Determine that the buffer pointer is not invalid
-
-# Check that the count is not zero
-
-# Check the file control block to see if we have permissions to read
-
-# If there is a read function in the handler table, invoke the handler
- table read() function
-
-# Use the return code from the handler table read function(number of
- bytes read) to increment the offset element of the file control block
-
-# Return the number of bytes read to the calling program
-
-.. COMMENT: @page
-
-readdir
-=======
-
-**File:**
-
-readdir.c
-
-**Processing:**
-
-This routine was acquired from the BSD group. It has not been altered from
-its original form.
-
-**Development Comments:**
-
-The routine calls a customized getdents() function that is provided by the
-user. This routine provides the filesystem specific aspects of reading a
-directory.
-
-It is layered on the read() function in the directory handler table. This
-function has been mapped to the Imfs_dir_read() function.
-
-.. COMMENT: @page
-
-unmount
-=======
-
-**File:**
-
-unmount.c
-
-**Processing:**
-
-This routine will attempt to dismount a mounted filesystem and then free
-all resources that were allocated for the management of that filesystem.
-
-**Development Comments:**
-
-- This routine will determine if there are any filesystems currently
- mounted under the filesystem that we are trying to dismount. This would
- prevent the dismount of the filesystem.
-
-- It will test to see if the current directory is in the filesystem
- that we are attempting to dismount. This would prevent the dismount of the
- filesystem.
-
-- It will scan all the currently open file descriptors to determine is
- there is an open file descriptor to a file in the filesystem that we are
- attempting to unmount().
-
-If the above preconditions are met then the following sequence is
-performed:
-
-# Call the filesystem specific unmount() function for the filesystem
- that contains the mount point. This routine should indicate that the mount
- point no longer has a filesystem mounted below it.
-
-# Call the filesystem specific fsunmount_me() function for the mounted
- filesystem that we are trying to unmount(). This routine should clean up
- any resources that are no longer needed for the management of the file
- system being un-mounted.
-
-# Extract the mount table entry for the filesystem that was just
- dismounted from the mount table chain.
-
-# Free the memory associated with the extracted mount table entry.
-
-.. COMMENT: @page
-
-eval
-====
-
-**File:**
-
-XXX
-
-**Processing:**
-
-XXX
-
-**Development Comments:**
-
-XXX
-
-.. COMMENT: @page
-
-getdentsc
-=========
-
-**File:**
-
-XXX
-
-**Processing:**
-
-XXX
-
-**Development Comments:**
-
-XXX
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Filesystem Implementation Requirements
-######################################
-
-This chapter details the behavioral requirements that all filesystem
-implementations must adhere to.
-
-General
-=======
-
-The RTEMS filesystem framework was intended to be compliant with the
-POSIX Files and Directories interface standard. The following filesystem
-characteristics resulted in a functional switching layer.
-.. code:: c
-
- Figure of the Filesystem Functional Layering goes here.
- This figure includes networking and disk caching layering.
-
-# Application programs are presented with a standard set of POSIX
- compliant functions that allow them to interface with the files, devices
- and directories in the filesystem. The interfaces to these routines do
- not reflect the type of subordinate filesystem implementation in which
- the file will be found.
-
-# The filesystem framework developed under RTEMS allows for mounting
- filesystem of different types under the base filesystem.
-
-# The mechanics of locating file information may be quite different
- between filesystem types.
-
-# The process of locating a file may require crossing filesystem
- boundaries.
-
-# The transitions between filesystem and the processing required to
- access information in different filesystem is not visible at the level
- of the POSIX function call.
-
-# The POSIX interface standard provides file access by character
- pathname to the file in some functions and through an integer file
- descriptor in other functions.
-
-# The nature of the integer file descriptor and its associated
- processing is operating system and filesystem specific.
-
-# Directory and device information must be processed with some of the
- same routines that apply to files.
-
-# The form and content of directory and device information differs
- greatly from that of a regular file.
-
-# Files, directories and devices represent elements (nodes) of a tree
- hierarchy.
-
-# The rules for processing each of the node types that exist under the
- filesystem are node specific but are still not reflected in the POSIX
- interface routines.
-
-.. code:: c
-
- Figure of the Filesystem Functional Layering goes here.
- This figure focuses on the Base Filesystem and IMFS.
-
-.. code:: c
-
- Figure of the IMFS Memfile control blocks
-
-
-File and Directory Removal Constraints
-======================================
-
-The following POSIX constraints must be honored by all filesystems.
-
-- If a node is a directory with children it cannot be removed.
-
-- The root node of any filesystem, whether the base filesystem or a
- mounted filesystem, cannot be removed.
-
-- A node that is a directory that is acting as the mount point of a file
- system cannot be removed.
-
-- On filesystems supporting hard links, a link count is maintained.
- Prior to node removal, the node’s link count is decremented by one. The
- link count must be less than one to allow for removal of the node.
-
-API Layering
-============
-
-Mapping of Generic System Calls to Filesystem Specific Functions
-----------------------------------------------------------------
-
-The list of generic system calls includes the routines open(), read(),
-write(), close(), etc..
-
-The Files and Directories section of the POSIX Application Programs
-Interface specifies a set of functions with calling arguments that are
-used to gain access to the information in a filesystem. To the
-application program, these functions allow access to information in any
-mounted filesystem without explicit knowledge of the filesystem type or
-the filesystem mount configuration. The following are functions that are
-provided to the application:
-
-# access()
-
-# chdir()
-
-# chmod()
-
-# chown()
-
-# close()
-
-# closedir()
-
-# fchmod()
-
-# fcntl()
-
-# fdatasync()
-
-# fpathconf()
-
-# fstat()
-
-# fsync()
-
-# ftruncate()
-
-# link()
-
-# lseek()
-
-# mkdir()
-
-# mknod()
-
-# mount()
-
-# open()
-
-# opendir()
-
-# pathconf()
-
-# read()
-
-# readdir()
-
-# rewinddir()
-
-# rmdir()
-
-# rmnod()
-
-# scandir()
-
-# seekdir()
-
-# stat()
-
-# telldir()
-
-# umask()
-
-# unlink()
-
-# unmount()
-
-# utime()
-
-# write()
-
-The filesystem’s type as well as the node type within the filesystem
-determine the nature of the processing that must be performed for each of
-the functions above. The RTEMS filesystem provides a framework that
-allows new filesystem to be developed and integrated without alteration
-to the basic framework.
-
-To provide the functional switching that is required, each of the POSIX
-file and directory functions have been implemented as a shell function.
-The shell function adheres to the POSIX interface standard. Within this
-functional shell, filesystem and node type information is accessed which
-is then used to invoke the appropriate filesystem and node type specific
-routine to process the POSIX function call.
-
-File/Device/Directory function access via file control block - rtems_libio_t structure
---------------------------------------------------------------------------------------
-
-The POSIX open() function returns an integer file descriptor that is used
-as a reference to file control block information for a specific file. The
-file control block contains information that is used to locate node, file
-system, mount table and functional handler information. The diagram in
-Figure 8 depicts the relationship between and among the following
-components.
-
-# File Descriptor Table
- This is an internal RTEMS structure that tracks all currently defined file
- descriptors in the system. The index that is returned by the file open()
- operation references a slot in this table. The slot contains a pointer to
- the file descriptor table entry for this file. The rtems_libio_t structure
- represents the file control block.
-
-# Allocation of entry in the File Descriptor Table
- Access to the file descriptor table is controlled through a semaphore that
- is implemented using the rtems_libio_allocate() function. This routine
- will grab a semaphore and then scan the file control blocks to determine
- which slot is free for use. The first free slot is marked as used and the
- index to this slot is returned as the file descriptor for the open()
- request. After the alterations have been made to the file control block
- table, the semaphore is released to allow further operations on the table.
-
-# Maximum number of entries in the file descriptor table is
- configurable through the src/exec/sapi/headers/confdefs.h file. If the
- CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value
- will represent the maximum number of file descriptors that are allowed.
- If CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default
- value of 20 will be used as the maximum number of file descriptors
- allowed.
-
-# File control block - rtems_libio_t structure
-
- .. code:: c
-
- struct rtems_libio_tt {
- rtems_driver_name_t \*driver;
- off_t size;
- off_t offset;
- unsigned32 flags;
- rtems_filesystem_location_info_t pathinfo;
- Objects_Id sem;
- unsigned32 data0;
- void data1;
- void file_info;
- rtems_filesystem_file_handlers_r handlers;
- };
-
- A file control block can exist for regular files, devices and directories.
- The following fields are important for regular file and directory access:
-
- - Size - For a file this represents the number of bytes currently
- stored in a file. For a directory this field is not filled in.
-
- - Offset - For a file this is the byte file position index relative to
- the start of the file. For a directory this is the byte offset into a
- sequence of dirent structures.
-
- - Pathinfo - This is a structure that provides a pointer to node
- information, OPS table functions, Handler functions and the mount table
- entry associated with this node.
-
- - file_info - A pointer to node information that is used by Handler
- functions
-
- - handlers - A pointer to a table of handler functions that operate on
- a file, device or directory through a file descriptor index
-
-File/Directory function access via rtems_filesystem_location_info_t structure
------------------------------------------------------------------------------
-
-The rtems_filesystem_location_info_tt structure below provides sufficient
-information to process nodes under a mounted filesystem.
-
-.. code:: c
-
- struct rtems_filesystem_location_info_tt {
- void \*node_access;
- rtems_filesystem_file_handlers_r \*handlers;
- rtems_filesystem_operations_table \*ops;
- rtems_filesystem_mount_table_entry_t \*mt_entry;
- };
-
-It contains a void pointer to filesystem specific nodal structure,
-pointers to the OPS table for the filesystem that contains the node, the
-node type specific handlers for the node and a reference pointer to the
-mount table entry associated with the filesystem containing the node
-
-Operation Tables
-================
-
-Filesystem specific operations are invoked indirectly. The set of
-routines that implement the filesystem are configured into two tables.
-The Filesystem Handler Table has routines that are specific to a
-filesystem but remain constant regardless of the actual file type.
-The File Handler Table has routines that are both filesystem and file type
-specific.
-
-Filesystem Handler Table Functions
-----------------------------------
-
-OPS table functions are defined in a ``rtems_filesystem_operations_table``
-structure. It defines functions that are specific to a given filesystem.
-One table exists for each filesystem that is supported in the RTEMS
-configuration. The structure definition appears below and is followed by
-general developmental information on each of the functions contained in this
-function management structure.
-
-.. code:: c
-
- typedef struct {
- rtems_filesystem_evalpath_t evalpath;
- rtems_filesystem_evalmake_t evalformake;
- rtems_filesystem_link_t link;
- rtems_filesystem_unlink_t unlink;
- rtems_filesystem_node_type_t node_type;
- rtems_filesystem_mknod_t mknod;
- rtems_filesystem_rmnod_t rmnod;
- rtems_filesystem_chown_t chown;
- rtems_filesystem_freenode_t freenod;
- rtems_filesystem_mount_t mount;
- rtems_filesystem_fsmount_me_t fsmount_me;
- rtems_filesystem_unmount_t unmount;
- rtems_filesystem_fsunmount_me_t fsunmount_me;
- rtems_filesystem_utime_t utime;
- rtems_filesystem_evaluate_link_t eval_link;
- rtems_filesystem_symlink_t symlink;
- } rtems_filesystem_operations_table;
-
-.. COMMENT: @page
-
-evalpath Handler
-~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-evalpath
-
-**Arguments:**
-
-.. code:: c
-
- const char \*pathname, /* IN \*/
- int flags, /* IN \*/
- rtems_filesystem_location_info_t \*pathloc /* IN/OUT \*/
-
-**Description:**
-
-This routine is responsible for evaluating the pathname passed in
-based upon the flags and the valid ``rthems_filesystem_location_info_t``.
-Additionally, it must make any changes to pathloc necessary to identify
-the pathname node. This should include calling the evalpath for a mounted
-filesystem, if the given filesystem supports the mount command.
-
-This routine returns a 0 if the evaluation was successful.
-Otherwise, it returns a -1 and sets errno to the correct error.
-
-This routine is required and should NOT be set to NULL.
-
-.. COMMENT: @page
-
-evalformake Handler
-~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-evalformake
-
-**Arguments:**
-
-.. code:: c
-
- const char \*path, /* IN \*/
- rtems_filesystem_location_info_t \*pathloc, /* IN/OUT \*/
- const char \**name /* OUT \*/
-
-**Description:**
-
-This method is given a path to evaluate and a valid start location. It
-is responsible for finding the parent node for a requested make command,
-setting pathloc information to identify the parent node, and setting
-the name pointer to the first character of the name of the new node.
-Additionally, if the filesystem supports the mount command, this method
-should call the evalformake routine for the mounted filesystem.
-
-This routine returns a 0 if the evaluation was successful. Otherwise, it
-returns a -1 and sets errno to the correct error.
-
-This routine is required and should NOT be set to NULL. However, if
-the filesystem does not support user creation of a new node, it may
-set errno to ENOSYS and return -1.
-
-.. COMMENT: @page
-
-link Handler
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-link
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*to_loc, /* IN \*/
- rtems_filesystem_location_info_t \*parent_loc, /* IN \*/
- const char \*token /* IN \*/
-
-**Description:**
-
-This routine is used to create a hard-link.
-
-It will first examine the st_nlink count of the node that we are trying to.
-If the link count exceeds LINK_MAX an error will be returned.
-
-The name of the link will be normalized to remove extraneous separators from
-the end of the name.
-
-This routine is not required and may be set to NULL.
-
-.. COMMENT: @page
-
-unlink Handler
-~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-node_type Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-node_type()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-mknod Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-mknod()
-
-**Arguments:**
-
-.. code:: c
-
- const char \*token, /* IN \*/
- mode_t mode, /* IN \*/
- dev_t dev, /* IN \*/
- rtems_filesystem_location_info_t \*pathloc /* IN/OUT \*/
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-rmnod Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-chown Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-chown()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
- uid_t owner /* IN \*/
- gid_t group /* IN \*/
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-freenod Handler
-~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-freenod()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
-
-**Description:**
-
-This routine is used by the generic code to allow memory to be allocated
-during the evaluate routines, and set free when the generic code is finished
-accessing a node. If the evaluate routines allocate memory to identify
-a node this routine should be utilized to free that memory.
-
-This routine is not required and may be set to NULL.
-
-.. COMMENT: @page
-
-mount Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-mount()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-fsmount_me Handler
-~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**Description:**
-
-This function is provided with a filesystem to take care of the internal
-filesystem management details associated with mounting that filesystem
-under the RTEMS environment.
-
-It is not responsible for the mounting details associated the filesystem
-containing the mount point.
-
-The rtems_filesystem_mount_table_entry_t structure contains the key elements
-below:
-
-rtems_filesystem_location_info_t \*mt_point_node,
-
-This structure contains information about the mount point. This
-allows us to find the ops-table and the handling functions
-associated with the filesystem containing the mount point.
-
-rtems_filesystem_location_info_t \*fs_root_node,
-
-This structure contains information about the root node in the file
-system to be mounted. It allows us to find the ops-table and the
-handling functions associated with the filesystem to be mounted.
-
-rtems_filesystem_options_t options,
-
-Read only or read/write access
-
-void \*fs_info,
-
-This points to an allocated block of memory the will be used to
-hold any filesystem specific information of a global nature. This
-allocated region if important because it allows us to mount the
-same filesystem type more than once under the RTEMS system.
-Each instance of the mounted filesystem has its own set of global
-management information that is separate from the global
-management information associated with the other instances of the
-mounted filesystem type.
-
-rtems_filesystem_limits_and_options_t pathconf_info,
-
-The table contains the following set of values associated with the
-mounted filesystem:
-
-- link_max
-
-- max_canon
-
-- max_input
-
-- name_max
-
-- path_max
-
-- pipe_buf
-
-- posix_async_io
-
-- posix_chown_restrictions
-
-- posix_no_trunc
-
-- posix_prio_io
-
-- posix_sync_io
-
-- posix_vdisable
-
-These values are accessed with the pathconf() and the fpathconf ()
-functions.
-
-const char \*dev
-
-The is intended to contain a string that identifies the device that contains
-the filesystem information. The filesystems that are currently implemented
-are memory based and don’t require a device specification.
-
-If the mt_point_node.node_access is NULL then we are mounting the base file
-system.
-
-The routine will create a directory node for the root of the IMFS file
-system.
-
-The node will have read, write and execute permissions for owner, group and
-others.
-
-The node’s name will be a null string.
-
-A filesystem information structure(fs_info) will be allocated and
-initialized for the IMFS filesystem. The fs_info pointer in the mount table
-entry will be set to point the filesystem information structure.
-
-The pathconf_info element of the mount table will be set to the appropriate
-table of path configuration constants (LIMITS_AND_OPTIONS).
-
-The fs_root_node structure will be filled in with the following:
-
-- pointer to the allocated root node of the filesystem
-
-- directory handlers for a directory node under the IMFS filesystem
-
-- OPS table functions for the IMFS
-
-A 0 will be returned to the calling routine if the process succeeded,
-otherwise a 1 will be returned.
-
-.. COMMENT: @page
-
-unmount Handler
-~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-fsunmount_me Handler
-~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_fsunmount_me()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-utime Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-eval_link Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-symlink Handler
-~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-File Handler Table Functions
-----------------------------
-
-Handler table functions are defined in a ``rtems_filesystem_file_handlers_r``
-structure. It defines functions that are specific to a node type in a given
-filesystem. One table exists for each of the filesystem’s node types. The
-structure definition appears below. It is followed by general developmental
-information on each of the functions associated with regular files contained
-in this function management structure.
-.. code:: c
-
- typedef struct {
- rtems_filesystem_open_t open;
- rtems_filesystem_close_t close;
- rtems_filesystem_read_t read;
- rtems_filesystem_write_t write;
- rtems_filesystem_ioctl_t ioctl;
- rtems_filesystem_lseek_t lseek;
- rtems_filesystem_fstat_t fstat;
- rtems_filesystem_fchmod_t fchmod;
- rtems_filesystem_ftruncate_t ftruncate;
- rtems_filesystem_fpathconf_t fpathconf;
- rtems_filesystem_fsync_t fsync;
- rtems_filesystem_fdatasync_t fdatasync;
- rtems_filesystem_fcntl_t fcntl;
- } rtems_filesystem_file_handlers_r;
-
-.. COMMENT: @page
-
-open Handler
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-open()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- const char \*pathname,
- unsigned32 flag,
- unsigned32 mode
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-close Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-close()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-read Handler
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-read()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- void \*buffer,
- unsigned32 count
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-write Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-ioctl Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- unsigned32 command,
- void \*buffer
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-lseek Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-lseek()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- off_t offset,
- int whence
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-fstat Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-fstat()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*loc,
- struct stat \*buf
-
-**Description:**
-
-The following information is extracted from the filesystem
-specific node and placed in the ``stat`` structure:
-
-- st_mode
-
-- st_nlink
-
-- st_ino
-
-- st_uid
-
-- st_gid
-
-- st_atime
-
-- st_mtime
-
-- st_ctime
-
-**NOTES:**
-
-Both the ``stat()`` and ``lstat()`` services are
-implemented directly using the ``fstat()`` handler. The
-difference in behavior is determined by how the path is evaluated
-prior to this handler being called on a particular
-file entity.
-
-The ``fstat()`` system call is implemented directly
-on top of this filesystem handler.
-
-.. COMMENT: @page
-
-fchmod Handler
-~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-fchmod()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
- mode_t mode
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-ftruncate Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-fpathconf Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-fsync Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-fdatasync Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: @page
-
-fcntl Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-In-Memory Filesystem
-####################
-
-This chapter describes the In-Memory FileSystem (IMFS). The IMFS is a
-full featured POSIX filesystem that keeps all information in memory.
-
-IMFS Per Node Data Structure
-============================
-
-Each regular file, device, hard link, and directory is represented by a data
-structure called a ``jnode``. The ``jnode`` is formally represented by the
-structure:
-.. code:: c
-
- struct IMFS_jnode_tt {
- Chain_Node Node; /* for chaining them together \*/
- IMFS_jnode_t \*Parent; /* Parent node \*/
- char name[NAME_MAX+1]; /* "basename" \*/
- mode_t st_mode; /* File mode \*/
- nlink_t st_nlink; /* Link count \*/
- ino_t st_ino; /* inode \*/
- uid_t st_uid; /* User ID of owner \*/
- gid_t st_gid; /* Group ID of owner \*/
- time_t st_atime; /* Time of last access \*/
- time_t st_mtime; /* Time of last modification \*/
- time_t st_ctime; /* Time of last status change \*/
- IMFS_jnode_types_t type; /* Type of this entry \*/
- IMFS_typs_union info;
- };
-
-The key elements of this structure are listed below together with a brief
-explanation of their role in the filesystem.
-
-*Node*
- exists to allow the entire ``jnode`` structure to be included in a chain.
-
-*Parent*
- is a pointer to another ``jnode`` structure that is the logical parent of the
- node in which it appears. This field may be NULL if the file associated with
- this node is deleted but there are open file descriptors on this file or
- there are still hard links to this node.
-
-*name*
- is the name of this node within the filesystem hierarchical tree. Example: If
- the fully qualified pathname to the ``jnode`` was ``/a/b/c``, the``jnode`` name field would contain the null terminated string ``"c"``.
-
-*st_mode*
- is the standard Unix access permissions for the file or directory.
-
-*st_nlink*
- is the number of hard links to this file. When a ``jnode`` is first created
- its link count is set to 1. A ``jnode`` and its associated resources
- cannot be deleted unless its link count is less than 1.
-
-*st_ino*
- is a unique node identification number
-
-*st_uid*
- is the user ID of the file’s owner
-
-*st_gid*
- is the group ID of the file’s owner
-
-*st_atime*
- is the time of the last access to this file
-
-*st_mtime*
- is the time of the last modification of this file
-
-*st_ctime*
- is the time of the last status change to the file
-
-*type*
- is the indication of node type must be one of the following states:
- - IMFS_DIRECTORY
- - IMFS_MEMORY_FILE
- - IMFS_HARD_LINK
- - IMFS_SYM_LINK
- - IMFS_DEVICE
-
-*info*
- is this contains a structure that is unique to file type (See IMFS_typs_union
- in imfs.h).
-
- - IMFS_DIRECTORY
-
- An IMFS directory contains a dynamic chain structure that
- records all files and directories that are subordinate to the directory node.
-
- - IMFS_MEMORY_FILE
-
- Under the in memory filesystem regular files hold data. Data is dynamically
- allocated to the file in 128 byte chunks of memory. The individual chunks of
- memory are tracked by arrays of pointers that record the address of the
- allocated chunk of memory. Single, double, and triple indirection pointers
- are used to record the locations of all segments of the file. The
- memory organization of an IMFS file are discussed elsewhere in this manual.
-
- - IMFS_HARD_LINK
-
- The IMFS filesystem supports the concept of hard links to other nodes in the
- IMFS filesystem. These hard links are actual pointers to other nodes in the
- same filesystem. This type of link cannot cross-filesystem boundaries.
-
- - IMFS_SYM_LINK
-
- The IMFS filesystem supports the concept of symbolic links to other nodes in
- any filesystem. A symbolic link consists of a pointer to a character string
- that represents the pathname to the target node. This type of link can
- cross-filesystem boundaries. Just as with most versions of UNIX supporting
- symbolic links, a symbolic link can point to a non-existent file.
-
- - IMFS_DEVICE
-
- All RTEMS devices now appear as files under the in memory filesystem. On
- system initialization, all devices are registered as nodes under the file
- system.
-
-Miscellaneous IMFS Information
-==============================
-
-Memory associated with the IMFS
-===============================
-
-A memory based filesystem draws its resources for files and directories
-from the memory resources of the system. When it is time to un-mount the
-filesystem, the memory resources that supported filesystem are set free.
-In order to free these resources, a recursive walk of the filesystems
-tree structure will be performed. As the leaf nodes under the filesystem
-are encountered their resources are freed. When directories are made empty
-by this process, their resources are freed.
-
-Node removal constraints for the IMFS
--------------------------------------
-
-The IMFS conforms to the general filesystem requirements for node
-removal. See `File and Directory Removal Constraints`_.
-
-IMFS General Housekeeping Notes
--------------------------------
-
-The following is a list of odd housekeeping notes for the IMFS.
-
-- If the global variable rtems_filesystem_current refers to the node that
- we are trying to remove, the node_access element of this structure must be
- set to NULL to invalidate it.
-
-- If the node was of IMFS_MEMORY_FILE type, free the memory associated
- with the memory file before freeing the node. Use the IMFS_memfile_remove()
- function.
-
-IMFS Operation Tables
-=====================
-
-IMFS Filesystem Handler Table Functions
----------------------------------------
-
-OPS table functions are defined in a rtems_filesystem_operations_table
-structure. It defines functions that are specific to a given filesystem.
-One table exists for each filesystem that is supported in the RTEMS
-configuration. The structure definition appears below and is followed by
-general developmental information on each of the functions contained in this
-function management structure.
-.. code:: c
-
- rtems_filesystem_operations_table IMFS_ops = {
- IMFS_eval_path,
- IMFS_evaluate_for_make,
- IMFS_link,
- IMFS_unlink,
- IMFS_node_type,
- IMFS_mknod,
- IMFS_rmnod,
- IMFS_chown,
- IMFS_freenodinfo,
- IMFS_mount,
- IMFS_initialize,
- IMFS_unmount,
- IMFS_fsunmount,
- IMFS_utime,
- IMFS_evaluate_link,
- IMFS_symlink,
- IMFS_readlink
- };
-
-.. COMMENT: @page
-
-IMFS_evalpath()
-~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_evalformake()
-~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_link()
-~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-link
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*to_loc, /* IN \*/
- rtems_filesystem_location_info_t \*parent_loc, /* IN \*/
- const char \*token /* IN \*/
-
-**File:**
-
-imfs_link.c
-
-**Description:**
-
-This routine is used in the IMFS filesystem to create a hard-link.
-
-It will first examine the st_nlink count of the node that we are trying to.
-If the link count exceeds LINK_MAX an error will be returned.
-
-The name of the link will be normalized to remove extraneous separators from
-the end of the name.
-
-IMFS_create_node will be used to create a filesystem node that will have the
-following characteristics:
-
-- parent that was determined in the link() function in file link.c
-
-- Type will be set to IMFS_HARD_LINK
-
-- name will be set to the normalized name
-
-- mode of the hard-link will be set to the mode of the target node
-
-If there was trouble allocating memory for the new node an error will be
-returned.
-
-The st_nlink count of the target node will be incremented to reflect the new
-link.
-
-The time fields of the link will be set to reflect the creation time of the
-hard-link.
-
-.. COMMENT: @page
-
-IMFS_unlink()
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_node_type()
-~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_node_type()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
-
-**File:**
-
-imfs_ntype.c
-
-**Description:**
-
-This routine will locate the IMFS_jnode_t structure that holds ownership
-information for the selected node in the filesystem.
-
-This structure is pointed to by pathloc->node_access.
-
-The IMFS_jnode_t type element indicates one of the node types listed below:
-
-- RTEMS_FILESYSTEM_DIRECTORY
-
-- RTEMS_FILESYSTEM_DEVICE
-
-- RTEMS_FILESYSTEM_HARD_LINK
-
-- RTEMS_FILESYSTEM_MEMORY_FILE
-
-.. COMMENT: @page
-
-IMFS_mknod()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_mknod()
-
-**Arguments:**
-
-.. code:: c
-
- const char \*token, /* IN \*/
- mode_t mode, /* IN \*/
- dev_t dev, /* IN \*/
- rtems_filesystem_location_info_t \*pathloc /* IN/OUT \*/
-
-**File:**
-
-imfs_mknod.c
-
-**Description:**
-
-This routine will examine the mode argument to determine is we are trying to
-create a directory, regular file and a device node. The creation of other
-node types is not permitted and will cause an assert.
-
-Memory space will be allocated for a ``jnode`` and the node will be set up
-according to the nodal type that was specified. The IMFS_create_node()
-function performs the allocation and setup of the node.
-
-The only problem that is currently reported is the lack of memory when we
-attempt to allocate space for the ``jnode`` (ENOMEN).
-
-.. COMMENT: @page
-
-IMFS_rmnod()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_chown()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_chown()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
- uid_t owner /* IN \*/
- gid_t group /* IN \*/
-
-**File:**
-
-imfs_chown.c
-
-**Description:**
-
-This routine will locate the IMFS_jnode_t structure that holds ownership
-information for the selected node in the filesystem.
-
-This structure is pointed to by pathloc->node_access.
-
-The st_uid and st_gid fields of the node are then modified. Since this is a
-memory based filesystem, no further action is required to alter the
-ownership of the IMFS_jnode_t structure.
-
-.. COMMENT: @page
-
-IMFS_freenod()
-~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_freenod()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
-
-**File:**
-
-imfs_free.c
-
-**Description:**
-
-This method is a private function to the IMFS. It is called by IMFS routines
-to free nodes that have been allocated. Examples of where this routine
-may be called from are unlink and rmnod.
-
-Note: This routine should not be confused with the filesystem callback
-freenod. The IMFS allocates memory until the node no longer exists.
-
-.. COMMENT: @page
-
-IMFS_freenodinfo()
-~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_freenodinfo()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*pathloc /* IN \*/
-
-**File:**
-
-imfs_free.c
-
-**Description:**
-
-The In-Memory File System does not need to allocate memory during the
-evaluate routines. Therefore, this routine simply routines PASS.
-
-.. COMMENT: @page
-
-IMFS_mount()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_mount()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**File:**
-
-imfs_mount.c
-
-**Description:**
-
-This routine provides the filesystem specific processing required to mount a
-filesystem for the system that contains the mount point. It will determine
-if the point that we are trying to mount onto is a node of IMFS_DIRECTORY
-type.
-
-If it is the node’s info element is altered so that the info.directory.mt_fs
-element points to the mount table chain entry that is associated with the
-mounted filesystem at this point. The info.directory.mt_fs element can be
-examined to determine if a filesystem is mounted at a directory. If it is
-NULL, the directory does not serve as a mount point. A non-NULL entry
-indicates that the directory does serve as a mount point and the value of
-info.directory.mt_fs can be used to locate the mount table chain entry that
-describes the filesystem mounted at this point.
-
-.. COMMENT: @page
-
-IMFS_fsmount_me()
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_initialize()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**File:**
-
-imfs_init.c
-
-**Description:**
-
-This function is provided with a filesystem to take care of the internal
-filesystem management details associated with mounting that filesystem
-under the RTEMS environment.
-
-It is not responsible for the mounting details associated the filesystem
-containing the mount point.
-
-The rtems_filesystem_mount_table_entry_t structure contains the key elements
-below:
-
-rtems_filesystem_location_info_t \*mt_point_node,
-
-This structure contains information about the mount point. This
-allows us to find the ops-table and the handling functions
-associated with the filesystem containing the mount point.
-
-rtems_filesystem_location_info_t \*fs_root_node,
-
-This structure contains information about the root node in the file
-system to be mounted. It allows us to find the ops-table and the
-handling functions associated with the filesystem to be mounted.
-
-rtems_filesystem_options_t options,
-
-Read only or read/write access
-
-void \*fs_info,
-
-This points to an allocated block of memory the will be used to
-hold any filesystem specific information of a global nature. This
-allocated region if important because it allows us to mount the
-same filesystem type more than once under the RTEMS system.
-Each instance of the mounted filesystem has its own set of global
-management information that is separate from the global
-management information associated with the other instances of the
-mounted filesystem type.
-
-rtems_filesystem_limits_and_options_t pathconf_info,
-
-The table contains the following set of values associated with the
-mounted filesystem:
-
-- link_max
-
-- max_canon
-
-- max_input
-
-- name_max
-
-- path_max
-
-- pipe_buf
-
-- posix_async_io
-
-- posix_chown_restrictions
-
-- posix_no_trunc
-
-- posix_prio_io
-
-- posix_sync_io
-
-- posix_vdisable
-
-These values are accessed with the pathconf() and the fpathconf ()
-functions.
-
-const char \*dev
-
-The is intended to contain a string that identifies the device that contains
-the filesystem information. The filesystems that are currently implemented
-are memory based and don’t require a device specification.
-
-If the mt_point_node.node_access is NULL then we are mounting the base file
-system.
-
-The routine will create a directory node for the root of the IMFS file
-system.
-
-The node will have read, write and execute permissions for owner, group and
-others.
-
-The node’s name will be a null string.
-
-A filesystem information structure(fs_info) will be allocated and
-initialized for the IMFS filesystem. The fs_info pointer in the mount table
-entry will be set to point the filesystem information structure.
-
-The pathconf_info element of the mount table will be set to the appropriate
-table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
-
-The fs_root_node structure will be filled in with the following:
-
-- pointer to the allocated root node of the filesystem
-
-- directory handlers for a directory node under the IMFS filesystem
-
-- OPS table functions for the IMFS
-
-A 0 will be returned to the calling routine if the process succeeded,
-otherwise a 1 will be returned.
-
-.. COMMENT: @page
-
-IMFS_unmount()
-~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_unmount()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**File:**
-
-imfs_unmount.c
-
-**Description:**
-
-This routine allows the IMFS to unmount a filesystem that has been
-mounted onto a IMFS directory.
-
-The mount entry mount point node access is verified to be a mounted
-directory. It’s mt_fs is set to NULL. This identifies to future
-calles into the IMFS that this directory node is no longer a mount
-point. Additionally, it will allow any directories that were hidden
-by the mounted system to again become visible.
-
-.. COMMENT: @page
-
-IMFS_fsunmount()
-~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_fsunmount()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_mount_table_entry_t \*mt_entry
-
-**File:**
-
-imfs_init.c
-
-**Description:**
-
-This method unmounts this instance of the IMFS file system. It is the
-counterpart to the IMFS_initialize routine. It is called by the generic
-code under the fsunmount_me callback.
-
-All method loops finding the first encountered node with no children and
-removing the node from the tree, thus returning allocated resources. This
-is done until all allocated nodes are returned.
-
-.. COMMENT: @page
-
-IMFS_utime()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_eval_link()
-~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-Regular File Handler Table Functions
-------------------------------------
-
-Handler table functions are defined in a rtems_filesystem_file_handlers_r
-structure. It defines functions that are specific to a node type in a given
-filesystem. One table exists for each of the filesystem’s node types. The
-structure definition appears below. It is followed by general developmental
-information on each of the functions associated with regular files contained
-in this function management structure.
-.. code:: c
-
- rtems_filesystem_file_handlers_r IMFS_memfile_handlers = {
- memfile_open,
- memfile_close,
- memfile_read,
- memfile_write,
- memfile_ioctl,
- memfile_lseek,
- IMFS_stat,
- IMFS_fchmod,
- memfile_ftruncate,
- NULL, /* fpathconf \*/
- NULL, /* fsync \*/
- IMFS_fdatasync,
- IMFS_fcntl
- };
-
-.. COMMENT: @page
-
-memfile_open() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-memfile_open()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- const char \*pathname,
- unsigned32 flag,
- unsigned32 mode
-
-**File:**
-
-memfile.c
-
-**Description:**
-
-Currently this function is a shell. No meaningful processing is performed and
-a success code is always returned.
-
-.. COMMENT: @page
-
-memfile_close() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-memfile_close()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
-
-**File:**
-
-memfile.c
-
-**Description:**
-
-This routine is a dummy for regular files under the base filesystem. It
-performs a capture of the IMFS_jnode_t pointer from the file control block
-and then immediately returns a success status.
-
-.. COMMENT: @page
-
-memfile_read() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-memfile_read()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- void \*buffer,
- unsigned32 count
-
-**File:**
-
-memfile.c
-
-**Description:**
-
-This routine will determine the ``jnode`` that is associated with this file.
-
-It will then call IMFS_memfile_read() with the ``jnode``, file position index,
-buffer and transfer count as arguments.
-
-IMFS_memfile_read() will do the following:
-
-- Verify that the ``jnode`` is associated with a memory file
-
-- Verify that the destination of the read is valid
-
-- Adjust the length of the read if it is too long
-
-- Acquire data from the memory blocks associated with the file
-
-- Update the access time for the data in the file
-
-.. COMMENT: @page
-
-memfile_write() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-memfile_ioctl() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- unsigned32 command,
- void \*buffer
-
-**File:**
-
-memfile.c
-
-**Description:**
-
-The current code is a placeholder for future development. The routine returns
-a successful completion status.
-
-.. COMMENT: @page
-
-memfile_lseek() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-Memfile_lseek()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- off_t offset,
- int whence
-
-**File:**
-
-memfile.c
-
-**Description:**
-
-This routine make sure that the memory based file is sufficiently large to
-allow for the new file position index.
-
-The IMFS_memfile_extend() function is used to evaluate the current size of
-the memory file and allocate additional memory blocks if required by the new
-file position index. A success code is always returned from this routine.
-
-.. COMMENT: @page
-
-IMFS_stat() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_stat()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*loc,
- struct stat \*buf
-
-**File:**
-
-imfs_stat.c
-
-**Description:**
-
-This routine actually performs status processing for both devices and regular
-files.
-
-The IMFS_jnode_t structure is referenced to determine the type of node under
-the filesystem.
-
-If the node is associated with a device, node information is extracted and
-transformed to set the st_dev element of the stat structure.
-
-If the node is a regular file, the size of the regular file is extracted from
-the node.
-
-This routine rejects other node types.
-
-The following information is extracted from the node and placed in the stat
-structure:
-
-- st_mode
-
-- st_nlink
-
-- st_ino
-
-- st_uid
-
-- st_gid
-
-- st_atime
-
-- st_mtime
-
-- st_ctime
-
-.. COMMENT: @page
-
-IMFS_fchmod() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_fchmod()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
- mode_t mode
-
-**File:**
-
-imfs_fchmod.c
-
-**Description:**
-
-This routine will obtain the pointer to the IMFS_jnode_t structure from the
-information currently in the file control block.
-
-Based on configuration the routine will acquire the user ID from a call to
-getuid() or from the IMFS_jnode_t structure.
-
-It then checks to see if we have the ownership rights to alter the mode of
-the file. If the caller does not, an error code is returned.
-
-An additional test is performed to verify that the caller is not trying to
-alter the nature of the node. If the caller is attempting to alter more than
-the permissions associated with user group and other, an error is returned.
-
-If all the preconditions are met, the user, group and other fields are set
-based on the mode calling parameter.
-
-.. COMMENT: @page
-
-memfile_ftruncate() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-No pathconf() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-NULL
-
-**Arguments:**
-
-Not Implemented
-
-**File:**
-
-Not Implemented
-
-**Description:**
-
-Not Implemented
-
-.. COMMENT: @page
-
-No fsync() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_fdatasync() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-Directory Handler Table Functions
----------------------------------
-
-Handler table functions are defined in a rtems_filesystem_file_handlers_r
-structure. It defines functions that are specific to a node type in a given
-filesystem. One table exists for each of the filesystem’s node types. The
-structure definition appears below. It is followed by general developmental
-information on each of the functions associated with directories contained in
-this function management structure.
-.. code:: c
-
- rtems_filesystem_file_handlers_r IMFS_directory_handlers = {
- IMFS_dir_open,
- IMFS_dir_close,
- IMFS_dir_read,
- NULL, /* write \*/
- NULL, /* ioctl \*/
- IMFS_dir_lseek,
- IMFS_dir_fstat,
- IMFS_fchmod,
- NULL, /* ftruncate \*/
- NULL, /* fpathconf \*/
- NULL, /* fsync \*/
- IMFS_fdatasync,
- IMFS_fcntl
- };
-
-.. COMMENT: @page
-
-IMFS_dir_open() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_open()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- const char \*pathname,
- unsigned32 flag,
- unsigned32 mode
-
-**File:**
-
-imfs_directory.c
-
-**Description:**
-
-This routine will look into the file control block to find the ``jnode`` that
-is associated with the directory.
-
-The routine will verify that the node is a directory. If its not a directory
-an error code will be returned.
-
-If it is a directory, the offset in the file control block will be set to 0.
-This allows us to start reading at the beginning of the directory.
-
-.. COMMENT: @page
-
-IMFS_dir_close() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_close()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
-
-**File:**
-
-imfs_directory.c
-
-**Description:**
-
-This routine is a dummy for directories under the base filesystem. It
-immediately returns a success status.
-
-.. COMMENT: @page
-
-IMFS_dir_read() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_read
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- void \*buffer,
- unsigned32 count
-
-**File:**
-
-imfs_directory.c
-
-**Description:**
-
-This routine will read a fixed number of directory entries from the current
-directory offset. The number of directory bytes read will be returned from
-this routine.
-
-.. COMMENT: @page
-
-No write() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-No ioctl() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-ioctl
-
-**Arguments:**
-
-**File:**
-
-Not supported
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_dir_lseek() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_lseek()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- off_t offset,
- int whence
-
-**File:**
-
-imfs_directory.c
-
-**Description:**
-
-This routine alters the offset in the file control block.
-
-No test is performed on the number of children under the current open
-directory. The imfs_dir_read() function protects against reads beyond the
-current size to the directory by returning a 0 bytes transfered to the
-calling programs whenever the file position index exceeds the last entry in
-the open directory.
-
-.. COMMENT: @page
-
-IMFS_dir_fstat() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_fstat()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*loc,
- struct stat \*buf
-
-**File:**
-
-imfs_directory.c
-
-**Description:**
-
-The node access information in the rtems_filesystem_location_info_t structure
-is used to locate the appropriate IMFS_jnode_t structure. The following
-information is taken from the IMFS_jnode_t structure and placed in the stat
-structure:
-
-- st_ino
-
-- st_mode
-
-- st_nlink
-
-- st_uid
-
-- st_gid
-
-- st_atime
-
-- st_mtime
-
-- st_ctime
-
-The st_size field is obtained by running through the chain of directory
-entries and summing the sizes of the dirent structures associated with each
-of the children of the directory.
-
-.. COMMENT: @page
-
-IMFS_fchmod() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_fchmod()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
- mode_t mode
-
-**File:**
-
-imfs_fchmod.c
-
-**Description:**
-
-This routine will obtain the pointer to the IMFS_jnode_t structure from the
-information currently in the file control block.
-
-Based on configuration the routine will acquire the user ID from a call to
-getuid() or from the IMFS_jnode_t structure.
-
-It then checks to see if we have the ownership rights to alter the mode of
-the file. If the caller does not, an error code is returned.
-
-An additional test is performed to verify that the caller is not trying to
-alter the nature of the node. If the caller is attempting to alter more than
-the permissions associated with user group and other, an error is returned.
-
-If all the preconditions are met, the user, group and other fields are set
-based on the mode calling parameter.
-
-.. COMMENT: @page
-
-No ftruncate() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-No fpathconf() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-fpathconf
-
-**Arguments:**
-
-Not Implemented
-
-**File:**
-
-Not Implemented
-
-**Description:**
-
-Not Implemented
-
-.. COMMENT: @page
-
-No fsync() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-IMFS_fdatasync() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-Device Handler Table Functions
-------------------------------
-
-Handler table functions are defined in a rtems_filesystem_file_handlers_r
-structure. It defines functions that are specific to a node type in a given
-filesystem. One table exists for each of the filesystem’s node types. The
-structure definition appears below. It is followed by general developmental
-information on each of the functions associated with devices contained in
-this function management structure.
-.. code:: c
-
- typedef struct {
- rtems_filesystem_open_t open;
- rtems_filesystem_close_t close;
- rtems_filesystem_read_t read;
- rtems_filesystem_write_t write;
- rtems_filesystem_ioctl_t ioctl;
- rtems_filesystem_lseek_t lseek;
- rtems_filesystem_fstat_t fstat;
- rtems_filesystem_fchmod_t fchmod;
- rtems_filesystem_ftruncate_t ftruncate;
- rtems_filesystem_fpathconf_t fpathconf;
- rtems_filesystem_fsync_t fsync;
- rtems_filesystem_fdatasync_t fdatasync;
- } rtems_filesystem_file_handlers_r;
-
-.. COMMENT: @page
-
-device_open() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-device_open()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- const char \*pathname,
- unsigned32 flag,
- unsigned32 mode
-
-**File:**
-
-deviceio.c
-
-**Description:**
-
-This routine will use the file control block to locate the node structure for
-the device.
-
-It will extract the major and minor device numbers from the ``jnode``.
-
-The major and minor device numbers will be used to make a rtems_io_open()
-function call to open the device driver. An argument list is sent to the
-driver that contains the file control block, flags and mode information.
-
-.. COMMENT: @page
-
-device_close() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-device_close()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
-
-**File:**
-
-deviceio.c
-
-**Description:**
-
-This routine extracts the major and minor device driver numbers from the
-IMFS_jnode_t that is referenced in the file control block.
-
-It also forms an argument list that contains the file control block.
-
-A rtems_io_close() function call is made to close the device specified by the
-major and minor device numbers.
-
-.. COMMENT: @page
-
-device_read() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-device_read()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- void \*buffer,
- unsigned32 count
-
-**File:**
-
-deviceio.c
-
-**Description:**
-
-This routine will extract the major and minor numbers for the device from the -
-jnode- associated with the file descriptor.
-
-A rtems_io_read() call will be made to the device driver associated with the file
-descriptor. The major and minor device number will be sent as arguments as well
-as an argument list consisting of:
-
-- file control block
-
-- file position index
-
-- buffer pointer where the data read is to be placed
-
-- count indicating the number of bytes that the program wishes to read
- from the device
-
-- flags from the file control block
-
-On return from the rtems_io_read() the number of bytes that were actually
-read will be returned to the calling program.
-
-.. COMMENT: @page
-
-device_write() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-device_ioctl() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-ioctl
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- unsigned32 command,
- void \*buffer
-
-**File:**
-
-deviceio.c
-
-**Description:**
-
-This handler will obtain status information about a device.
-
-The form of status is device dependent.
-
-The rtems_io_control() function uses the major and minor number of the device
-to obtain the status information.
-
-rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
-contains the file control block, device specific command and a buffer pointer
-to return the device status information.
-
-The device specific command should indicate the nature of the information
-that is desired from the device.
-
-After the rtems_io_control() is processed, the buffer should contain the
-requested device information.
-
-If the device information is not obtained properly a -1 will be returned to
-the calling program, otherwise the ioctl_return value is returned.
-
-.. COMMENT: @page
-
-device_lseek() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-device_lseek()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop,
- off_t offset,
- int whence
-
-**File:**
-
-deviceio.c
-
-**Description:**
-
-At the present time this is a placeholder function. It always returns a
-successful status.
-
-.. COMMENT: @page
-
-IMFS_stat() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_stat()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_filesystem_location_info_t \*loc,
- struct stat \*buf
-
-**File:**
-
-imfs_stat.c
-
-**Description:**
-
-This routine actually performs status processing for both devices and regular files.
-
-The IMFS_jnode_t structure is referenced to determine the type of node under the
-filesystem.
-
-If the node is associated with a device, node information is extracted and
-transformed to set the st_dev element of the stat structure.
-
-If the node is a regular file, the size of the regular file is extracted from the node.
-
-This routine rejects other node types.
-
-The following information is extracted from the node and placed in the stat
-structure:
-
-- st_mode
-
-- st_nlink
-
-- st_ino
-
-- st_uid
-
-- st_gid
-
-- st_atime
-
-- st_mtime
-
-- st_ctime
-
-.. COMMENT: @page
-
-IMFS_fchmod() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_fchmod()
-
-**Arguments:**
-
-.. code:: c
-
- rtems_libio_t \*iop
- mode_t mode
-
-**File:**
-
-imfs_fchmod.c
-
-**Description:**
-
-This routine will obtain the pointer to the IMFS_jnode_t structure from the
-information currently in the file control block.
-
-Based on configuration the routine will acquire the user ID from a call to
-getuid() or from the IMFS_jnode_t structure.
-
-It then checks to see if we have the ownership rights to alter the mode of
-the file. If the caller does not, an error code is returned.
-
-An additional test is performed to verify that the caller is not trying to
-alter the nature of the node. If the caller is attempting to alter more than
-the permissions associated with user group and other, an error is returned.
-
-If all the preconditions are met, the user, group and other fields are set
-based on the mode calling parameter.
-
-.. COMMENT: @page
-
-No ftruncate() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-No fpathconf() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-fpathconf
-
-**Arguments:**
-
-Not Implemented
-
-**File:**
-
-Not Implemented
-
-**Description:**
-
-Not Implemented
-
-.. COMMENT: @page
-
-No fsync() for Devices
-~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
-
-No fdatasync() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Not Implemented
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Miniature In-Memory Filesystem
-##############################
-
-This chapter describes the Miniature In-Memory FileSystem (miniIMFS).
-The miniIMFS is a reduced feature version of the IMFS designed to
-provide minimal functionality and have a low memory footprint.
-
-This chapter should be written after the IMFS chapter is completed
-and describe the implementation of the mini-IMFS.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Trivial FTP Client Filesystem
-#############################
-
-This chapter describes the Trivial FTP (TFTP) Client Filesystem.
-
-This chapter should be written after the IMFS chapter is completed
-and describe the implementation of the TFTP.
-
-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/networking/networking_old_reference_only.rst b/networking/networking_old_reference_only.rst
deleted file mode 100644
index ad8f9c0..0000000
--- a/networking/networking_old_reference_only.rst
+++ /dev/null
@@ -1,2044 +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 network Supplement
-
-.. 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 RTEMS Network Supplement
-
-========================
-RTEMS Network Supplement
-========================
-
-.. 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 TCP/IP Networking Supplement
-##################################
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Preface
-#######
-
-This document describes the RTEMS specific parts of the FreeBSD TCP/IP
-stack. Much of this documentation was written by Eric Norum
-(eric@skatter.usask.ca)
-of the Saskatchewan Accelerator Laboratory
-who also ported the FreeBSD TCP/IP stack to RTEMS.
-
-The following is a list of resources which should be useful in trying
-to understand Ethernet:
-
-- *Charles Spurgeon’s Ethernet Web Site*
- "This site provides extensive information about Ethernet
- (IEEE 802.3) local area network (LAN) technology. Including
- the original 10 Megabit per second (Mbps) system, the 100 Mbps
- Fast Ethernet system (802.3u), and the Gigabit Ethernet system (802.3z)."
- The URL is:
- (http://www.ethermanage.com/ethernet/ethernet.html)
-
-- *TCP/IP Illustrated, Volume 1 : The Protocols* by
- by W. Richard Stevens (ISBN: 0201633469)
- This book provides detailed introduction to TCP/IP and includes diagnostic
- programs which are publicly available.
-
-- *TCP/IP Illustrated, Volume 2 : The Implementation* by W. Richard
- Stevens and Gary Wright (ISBN: 020163354X)
- This book focuses on implementation issues regarding TCP/IP. The
- treat for RTEMS users is that the implementation covered is the BSD
- stack with most of the source code described in detail.
-
-- *UNIX Network Programming, Volume 1 : 2nd Edition* by W. Richard
- Stevens (ISBN: 0-13-490012-X)
- This book describes how to write basic TCP/IP applications, again with primary
- focus on the BSD stack.
-
-.. COMMENT: Written by Eric Norum
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Network Task Structure and Data Flow
-####################################
-
-A schematic diagram of the tasks and message *mbuf* queues in a
-simple RTEMS networking application is shown in the following
-figure:
-
-.. image:: images/networkflow.jpg
-
-
-The transmit task for each network interface is normally blocked waiting
-for a packet to arrive in the transmit queue. Once a packet arrives, the
-transmit task may block waiting for an event from the transmit interrupt
-handler. The transmit interrupt handler sends an RTEMS event to the transmit
-task to indicate that transmit hardware resources have become available.
-
-The receive task for each network interface is normally blocked waiting
-for an event from the receive interrupt handler. When this event is received
-the receive task reads the packet and forwards it to the network stack
-for subsequent processing by the network task.
-
-The network task processes incoming packets and takes care of
-timed operations such as handling TCP timeouts and
-aging and removing routing table entries.
-
-The ‘Network code’ contains routines which may run in the context of
-the user application tasks, the interface receive task or the network task.
-A network semaphore ensures that
-the data structures manipulated by the network code remain consistent.
-
-.. 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: Written by Eric Norum
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Using Networking in an RTEMS Application
-########################################
-
-Makefile changes
-================
-
-Including the required managers
--------------------------------
-
-The FreeBSD networking code requires several RTEMS managers
-in the application:
-.. code:: c
-
- MANAGERS = io event semaphore
-
-Increasing the size of the heap
--------------------------------
-
-The networking tasks allocate a lot of memory. For most applications
-the heap should be at least 256 kbytes.
-The amount of memory set aside for the heap can be adjusted by setting
-the ``CFLAGS_LD`` definition as shown below:
-.. code:: c
-
- CFLAGS_LD += -Wl,--defsym -Wl,HeapSize=0x80000
-
-This sets aside 512 kbytes of memory for the heap.
-
-System Configuration
-====================
-
-The networking tasks allocate some RTEMS objects. These
-must be accounted for in the application configuration table. The following
-lists the requirements.
-
-*TASKS*
- One network task plus a receive and transmit task for each device.
-
-*SEMAPHORES*
- One network semaphore plus one syslog mutex semaphore if the application uses
- openlog/syslog.
-
-*EVENTS*
- The network stack uses ``RTEMS_EVENT_24`` and ``RTEMS_EVENT_25``.
- This has no effect on the application configuration, but
- application tasks which call the network functions should not
- use these events for other purposes.
-
-Initialization
-==============
-
-Additional include files
-------------------------
-
-The source file which declares the network configuration
-structures and calls the network initialization function must include
-.. code:: c
-
- #include <rtems/rtems_bsdnet.h>
-
-Network Configuration
----------------------
-
-The network configuration is specified by declaring
-and initializing the ``rtems_bsdnet_config``
-structure.
-.. code:: c
-
- struct rtems_bsdnet_config {
- /*
- * This entry points to the head of the ifconfig chain.
- \*/
- struct rtems_bsdnet_ifconfig \*ifconfig;
- /*
- * This entry should be rtems_bsdnet_do_bootp if BOOTP
- * is being used to configure the network, and NULL
- * if BOOTP is not being used.
- \*/
- void (\*bootp)(void);
- /*
- * The remaining items can be initialized to 0, in
- * which case the default value will be used.
- \*/
- rtems_task_priority network_task_priority; /* 100 \*/
- unsigned long mbuf_bytecount; /* 64 kbytes \*/
- unsigned long mbuf_cluster_bytecount; /* 128 kbytes \*/
- char \*hostname; /* BOOTP \*/
- char \*domainname; /* BOOTP \*/
- char \*gateway; /* BOOTP \*/
- char \*log_host; /* BOOTP \*/
- char \*name_server[3]; /* BOOTP \*/
- char \*ntp_server[3]; /* BOOTP \*/
- unsigned long sb_efficiency; /* 2 \*/
- /* UDP TX: 9216 bytes \*/
- unsigned long udp_tx_buf_size;
- /* UDP RX: 40 * (1024 + sizeof(struct sockaddr_in)) \*/
- unsigned long udp_rx_buf_size;
- /* TCP TX: 16 * 1024 bytes \*/
- unsigned long tcp_tx_buf_size;
- /* TCP TX: 16 * 1024 bytes \*/
- unsigned long tcp_rx_buf_size;
- /* Default Network Tasks CPU Affinity \*/
- #ifdef RTEMS_SMP
- const cpu_set_t \*network_task_cpuset;
- size_t network_task_cpuset_size;
- #endif
- };
-
-The structure entries are described in the following table.
-If your application uses BOOTP/DHCP to obtain network configuration
-information and if you are happy with the default values described
-below, you need to provide only the first two entries in this structure.
-
-``struct rtems_bsdnet_ifconfig \*ifconfig``
-
- A pointer to the first configuration structure of the first network
- device. This structure is described in the following section.
- You must provide a value for this entry since there is no default value for it.
-
-``void (\*bootp)(void)``
-
- This entry should be set to ``rtems_bsdnet_do_bootp`` if your
- application by default uses the BOOTP/DHCP client protocol to obtain
- network configuration information. It should be set to ``NULL`` if
- your application does not use BOOTP/DHCP.
- You can also use ``rtems_bsdnet_do_bootp_rootfs`` to have a set of
- standard files created with the information return by the BOOTP/DHCP
- protocol. The IP address is added to :file:`/etc/hosts` with the host
- name and domain returned. If no host name or domain is returned``me.mydomain`` is used. The BOOTP/DHCP server’s address is also
- added to :file:`/etc/hosts`. The domain name server listed in the
- BOOTP/DHCP information are added to :file:`/etc/resolv.conf`. A``search`` record is also added if a domain is returned. The files
- are created if they do not exist.
- The default ``rtems_bsdnet_do_bootp`` and``rtems_bsdnet_do_bootp_rootfs`` handlers will loop for-ever
- waiting for a BOOTP/DHCP server to respond. If an error is detected
- such as not valid interface or valid hardware address the target will
- reboot allowing any hardware reset to correct itself.
- You can provide your own custom handler which allows you to perform
- an initialization that meets your specific system requirements. For
- example you could try BOOTP/DHCP then enter a configuration tool if no
- server is found allowing the user to switch to a static configuration.
-
-``int network_task_priority``
- The priority at which the network task and network device
- receive and transmit tasks will run.
- If a value of 0 is specified the tasks will run at priority 100.
-
-``unsigned long mbuf_bytecount``
- The number of bytes to allocate from the heap for use as mbufs.
- If a value of 0 is specified, 64 kbytes will be allocated.
-
-``unsigned long mbuf_cluster_bytecount``
- The number of bytes to allocate from the heap for use as mbuf clusters.
- If a value of 0 is specified, 128 kbytes will be allocated.
-
-``char \*hostname``
- The host name of the system.
- If this, or any of the following, entries are ``NULL`` the value
- may be obtained from a BOOTP/DHCP server.
-
-``char \*domainname``
- The name of the Internet domain to which the system belongs.
-
-``char \*gateway``
- The Internet host number of the network gateway machine,
- specified in ’dotted decimal’ (``129.128.4.1``) form.
-
-``char \*log_host``
- The Internet host number of the machine to which ``syslog`` messages
- will be sent.
-
-``char \*name_server[3]``
- The Internet host numbers of up to three machines to be used as
- Internet Domain Name Servers.
-
-``char \*ntp_server[3]``
- The Internet host numbers of up to three machines to be used as
- Network Time Protocol (NTP) Servers.
-
-``unsigned long sb_efficiency``
- This is the first of five configuration parameters related to
- the amount of memory each socket may consume for buffers. The
- TCP/IP stack reserves buffers (e.g. mbufs) for each open socket. The
- TCP/IP stack has different limits for the transmit and receive
- buffers associated with each TCP and UDP socket. By tuning these
- parameters, the application developer can make trade-offs between
- memory consumption and performance. The default parameters favor
- performance over memory consumption. Seehttp://www.rtems.org/ml/rtems-users/2004/february/msg00200.html
- for more details but note that after the RTEMS 4.8 release series,
- the sb_efficiency default was changed from ``8`` to ``2``.
- The user should also be aware of the ``SO_SNDBUF`` and ``SO_RCVBUF``
- IO control operations. These can be used to specify the
- send and receive buffer sizes for a specific socket. There
- is no standard IO control to change the ``sb_efficiency`` factor.
- The ``sb_efficiency`` parameter is a buffering factor used
- in the implementation of the TCP/IP stack. The default is ``2``
- which indicates double buffering. When allocating memory for each
- socket, this number is multiplied by the buffer sizes for that socket.
-
-``unsigned long udp_tx_buf_size``
-
- This configuration parameter specifies the maximum amount of
- buffer memory which may be used for UDP sockets to transmit
- with. The default size is 9216 bytes which corresponds to
- the maximum datagram size.
-
-``unsigned long udp_rx_buf_size``
-
- This configuration parameter specifies the maximum amount of
- buffer memory which may be used for UDP sockets to receive
- into. The default size is the following length in bytes:
-
- .. code:: c
-
- 40 * (1024 + sizeof(struct sockaddr_in)
-
-``unsigned long tcp_tx_buf_size``
-
- This configuration parameter specifies the maximum amount of
- buffer memory which may be used for TCP sockets to transmit
- with. The default size is sixteen kilobytes.
-
-``unsigned long tcp_rx_buf_size``
-
- This configuration parameter specifies the maximum amount of
- buffer memory which may be used for TCP sockets to receive
- into. The default size is sixteen kilobytes.
-
-``const cpu_set_t \*network_task_cpuset``
-
- This configuration parameter specifies the CPU affinity of the
- network task. If set to ``0`` the network task can be scheduled on
- any CPU. Only available in SMP configurations.
-
-``size_t network_task_cpuset_size``
-
- This configuration parameter specifies the size of the``network_task_cpuset`` used. Only available in SMP configurations.
-
-In addition, the following fields in the ``rtems_bsdnet_ifconfig``
-are of interest.
-
-*int port*
- The I/O port number (ex: 0x240) on which the external Ethernet
- can be accessed.
-
-*int irno*
- The interrupt number of the external Ethernet controller.
-
-*int bpar*
- The address of the shared memory on the external Ethernet controller.
-
-Network device configuration
-----------------------------
-
-Network devices are specified and configured by declaring and initializing a``struct rtems_bsdnet_ifconfig`` structure for each network device.
-
-The structure entries are described in the following table. An application
-which uses a single network interface, gets network configuration information
-from a BOOTP/DHCP server, and uses the default values for all driver
-parameters needs to initialize only the first two entries in the
-structure.
-
-``char \*name``
- The full name of the network device. This name consists of the
- driver name and the unit number (e.g. ``"scc1"``).
- The ``bsp.h`` include file usually defines RTEMS_BSP_NETWORK_DRIVER_NAME as
- the name of the primary (or only) network driver.
-
-``int (\*attach)(struct rtems_bsdnet_ifconfig \*conf)``
- The address of the driver ``attach`` function. The network
- initialization function calls this function to configure the driver and
- attach it to the network stack.
- The ``bsp.h`` include file usually defines RTEMS_BSP_NETWORK_DRIVER_ATTACH as
- the name of the attach function of the primary (or only) network driver.
-
-``struct rtems_bsdnet_ifconfig \*next``
- A pointer to the network device configuration structure for the next network
- interface, or ``NULL`` if this is the configuration structure of the
- last network interface.
-
-``char \*ip_address``
- The Internet address of the device,
- specified in ‘dotted decimal’ (``129.128.4.2``) form, or ``NULL``
- if the device configuration information is being obtained from a
- BOOTP/DHCP server.
-
-``char \*ip_netmask``
- The Internet inetwork mask of the device,
- specified in ‘dotted decimal’ (``255.255.255.0``) form, or ``NULL``
- if the device configuration information is being obtained from a
- BOOTP/DHCP server.
-
-``void \*hardware_address``
- The hardware address of the device, or ``NULL`` if the driver is
- to obtain the hardware address in some other way (usually by reading
- it from the device or from the bootstrap ROM).
-
-``int ignore_broadcast``
- Zero if the device is to accept broadcast packets, non-zero if the device
- is to ignore broadcast packets.
-
-``int mtu``
- The maximum transmission unit of the device, or zero if the driver
- is to choose a default value (typically 1500 for Ethernet devices).
-
-``int rbuf_count``
- The number of receive buffers to use, or zero if the driver is to
- choose a default value
-
-``int xbuf_count``
- The number of transmit buffers to use, or zero if the driver is to
- choose a default value
- Keep in mind that some network devices may use 4 or more
- transmit descriptors for a single transmit buffer.
-
-A complete network configuration specification can be as simple as the one
-shown in the following example.
-This configuration uses a single network interface, gets
-network configuration information
-from a BOOTP/DHCP server, and uses the default values for all driver
-parameters.
-.. code:: c
-
- static struct rtems_bsdnet_ifconfig netdriver_config = {
- RTEMS_BSP_NETWORK_DRIVER_NAME,
- RTEMS_BSP_NETWORK_DRIVER_ATTACH
- };
- struct rtems_bsdnet_config rtems_bsdnet_config = {
- &netdriver_config,
- rtems_bsdnet_do_bootp,
- };
-
-Network initialization
-----------------------
-
-The networking tasks must be started before any network I/O operations
-can be performed. This is done by calling:
-
-.. code:: c
-
- rtems_bsdnet_initialize_network ();
-
-This function is declared in ``rtems/rtems_bsdnet.h``.
-t returns 0 on success and -1 on failure with an error code
-in ``errno``. It is not possible to undo the effects of
-a partial initialization, though, so the function can be
-called only once irregardless of the return code. Consequently,
-if the condition for the failure can be corrected, the
-system must be reset to permit another network initialization
-attempt.
-
-Application Programming Interface
-=================================
-
-The RTEMS network package provides almost a complete set of BSD network
-services. The network functions work like their BSD counterparts
-with the following exceptions:
-
-- A given socket can be read or written by only one task at a time.
-
-- The ``select`` function only works for file descriptors associated
- with sockets.
-
-- You must call ``openlog`` before calling any of the ``syslog`` functions.
-
-- *Some of the network functions are not thread-safe.*
- For example the following functions return a pointer to a static
- buffer which remains valid only until the next call:
-
- ``gethostbyaddr``
-
- ``gethostbyname``
-
- ``inet_ntoa``
-
- (``inet_ntop`` is thread-safe, though).
-
-- The RTEMS network package gathers statistics.
-
-- Addition of a mechanism to "tap onto" an interface
- and monitor every packet received and transmitted.
-
-- Addition of ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP`` socket options.
-
-Some of the new features are discussed in more detail in the following
-sections.
-
-Network Statistics
-------------------
-
-There are a number of functions to print statistics gathered by
-the network stack.
-These function are declared in ``rtems/rtems_bsdnet.h``.
-
-``rtems_bsdnet_show_if_stats``
- Display statistics gathered by network interfaces.
-
-``rtems_bsdnet_show_ip_stats``
- Display IP packet statistics.
-
-``rtems_bsdnet_show_icmp_stats``
- Display ICMP packet statistics.
-
-``rtems_bsdnet_show_tcp_stats``
- Display TCP packet statistics.
-
-``rtems_bsdnet_show_udp_stats``
- Display UDP packet statistics.
-
-``rtems_bsdnet_show_mbuf_stats``
- Display mbuf statistics.
-
-``rtems_bsdnet_show_inet_routes``
- Display the routing table.
-
-Tapping Into an Interface
--------------------------
-
-RTEMS add two new ioctls to the BSD networking code:
-SIOCSIFTAP and SIOCGIFTAP. These may be used to set and get a*tap function*. The tap function will be called for every
-Ethernet packet received by the interface.
-
-These are called like other interface ioctls, such as SIOCSIFADDR.
-When setting the tap function with SIOCSIFTAP, set the ifr_tap field
-of the ifreq struct to the tap function. When retrieving the tap
-function with SIOCGIFTAP, the current tap function will be returned in
-the ifr_tap field. To stop tapping packets, call SIOCSIFTAP with a
-ifr_tap field of 0.
-
-The tap function is called like this:
-.. code:: c
-
- int tap (struct ifnet \*, struct ether_header \*, struct mbuf \*)
-
-The tap function should return 1 if the packet was fully handled, in
-which case the caller will simply discard the mbuf. The tap function
-should return 0 if the packet should be passed up to the higher
-networking layers.
-
-The tap function is called with the network semaphore locked. It must
-not make any calls on the application levels of the networking level
-itself. It is safe to call other non-networking RTEMS functions.
-
-Socket Options
---------------
-
-RTEMS adds two new ``SOL_SOCKET`` level options for ``setsockopt`` and``getsockopt``: ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP``. For both, the
-option value should point to a sockwakeup structure. The sockwakeup
-structure has the following fields:
-.. code:: c
-
- void (\*sw_pfn) (struct socket \*, caddr_t);
- caddr_t sw_arg;
-
-These options are used to set a callback function to be called when, for
-example, there is
-data available from the socket (``SO_RCVWAKEUP``) and when there is space
-available to accept data written to the socket (``SO_SNDWAKEUP``).
-
-If ``setsockopt`` is called with the ``SO_RCVWAKEUP`` option, and the``sw_pfn`` field is not zero, then when there is data
-available to be read from
-the socket, the function pointed to by the ``sw_pfn`` field will be
-called. A pointer to the socket structure will be passed as the first
-argument to the function. The ``sw_arg`` field set by the``SO_RCVWAKEUP`` call will be passed as the second argument to the function.
-
-If ``setsockopt`` is called with the ``SO_SNDWAKEUP``
-function, and the ``sw_pfn`` field is not zero, then when
-there is space available to accept data written to the socket,
-the function pointed to by the ``sw_pfn`` field
-will be called. The arguments passed to the function will be as with``SO_SNDWAKEUP``.
-
-When the function is called, the network semaphore will be locked and
-the callback function runs in the context of the networking task.
-The function must be careful not to call any networking functions. It
-is OK to call an RTEMS function; for example, it is OK to send an
-RTEMS event.
-
-The purpose of these callback functions is to permit a more efficient
-alternative to the select call when dealing with a large number of
-sockets.
-
-The callbacks are called by the same criteria that the select
-function uses for indicating "ready" sockets. In Stevens *Unix
-Network Programming* on page 153-154 in the section "Under what Conditions
-Is a Descriptor Ready?" you will find the definitive list of conditions
-for readable and writable that also determine when the functions are
-called.
-
-When the number of received bytes equals or exceeds the socket receive
-buffer "low water mark" (default 1 byte) you get a readable callback. If
-there are 100 bytes in the receive buffer and you only read 1, you will
-not immediately get another callback. However, you will get another
-callback after you read the remaining 99 bytes and at least 1 more byte
-arrives. Using a non-blocking socket you should probably read until it
-produces error EWOULDBLOCK and then allow the readable callback to tell
-you when more data has arrived. (Condition 1.a.)
-
-For sending, when the socket is connected and the free space becomes at
-or above the "low water mark" for the send buffer (default 4096 bytes)
-you will receive a writable callback. You don’t get continuous callbacks
-if you don’t write anything. Using a non-blocking write socket, you can
-then call write until it returns a value less than the amount of data
-requested to be sent or it produces error EWOULDBLOCK (indicating buffer
-full and no longer writable). When this happens you can
-try the write again, but it is often better to go do other things and
-let the writable callback tell you when space is available to send
-again. You only get a writable callback when the free space transitions
-to above the "low water mark" and not every time you
-write to a non-full send buffer. (Condition 2.a.)
-
-The remaining conditions enumerated by Stevens handle the fact that
-sockets become readable and/or writable when connects, disconnects and
-errors occur, not just when data is received or sent. For example, when
-a server "listening" socket becomes readable it indicates that a client
-has connected and accept can be called without blocking, not that
-network data was received (Condition 1.c).
-
-Adding an IP Alias
-------------------
-
-The following code snippet adds an IP alias:
-.. code:: c
-
- void addAlias(const char \*pName, const char \*pAddr, const char \*pMask)
- {
- struct ifaliasreq aliasreq;
- struct sockaddr_in \*in;
- /* initialize alias request \*/
- memset(&aliasreq, 0, sizeof(aliasreq));
- sprintf(aliasreq.ifra_name, pName);
- /* initialize alias address \*/
- in = (struct sockaddr_in \*)&aliasreq.ifra_addr;
- in->sin_family = AF_INET;
- in->sin_len = sizeof(aliasreq.ifra_addr);
- in->sin_addr.s_addr = inet_addr(pAddr);
- /* initialize alias mask \*/
- in = (struct sockaddr_in \*)&aliasreq.ifra_mask;
- in->sin_family = AF_INET;
- in->sin_len = sizeof(aliasreq.ifra_mask);
- in->sin_addr.s_addr = inet_addr(pMask);
- /* call to setup the alias \*/
- rtems_bsdnet_ifconfig(pName, SIOCAIFADDR, &aliasreq);
- }
-
-Thanks to `Mike Seirs <mailto:mikes@poliac.com>`_ for this example
-code.
-
-Adding a Default Route
-----------------------
-
-The function provided in this section is functionally equivalent to
-the command ``route add default gw yyy.yyy.yyy.yyy``:
-.. code:: c
-
- void mon_ifconfig(int argc, char \*argv[], unsigned32 command_arg,
- bool verbose)
- {
- struct sockaddr_in ipaddr;
- struct sockaddr_in dstaddr;
- struct sockaddr_in netmask;
- struct sockaddr_in broadcast;
- char \*iface;
- int f_ip = 0;
- int f_ptp = 0;
- int f_netmask = 0;
- int f_up = 0;
- int f_down = 0;
- int f_bcast = 0;
- int cur_idx;
- int rc;
- int flags;
- bzero((void*) &ipaddr, sizeof(ipaddr));
- bzero((void*) &dstaddr, sizeof(dstaddr));
- bzero((void*) &netmask, sizeof(netmask));
- bzero((void*) &broadcast, sizeof(broadcast));
- ipaddr.sin_len = sizeof(ipaddr);
- ipaddr.sin_family = AF_INET;
- dstaddr.sin_len = sizeof(dstaddr);
- dstaddr.sin_family = AF_INET;
- netmask.sin_len = sizeof(netmask);
- netmask.sin_family = AF_INET;
- broadcast.sin_len = sizeof(broadcast);
- broadcast.sin_family = AF_INET;
- cur_idx = 0;
- if (argc <= 1) {
- /* display all interfaces \*/
- iface = NULL;
- cur_idx += 1;
- } else {
- iface = argv[1];
- if (isdigit(\*argv[2])) {
- if (inet_pton(AF_INET, argv[2], &ipaddr.sin_addr) < 0) {
- printf("bad ip address: %s\\n", argv[2]);
- return;
- }
- f_ip = 1;
- cur_idx += 3;
- } else {
- cur_idx += 2;
- }
- }
- if ((f_down !=0) && (f_ip != 0)) {
- f_up = 1;
- }
- while(argc > cur_idx) {
- if (strcmp(argv[cur_idx], "up") == 0) {
- f_up = 1;
- if (f_down != 0) {
- printf("Can't make interface up and down\\n");
- }
- } else if(strcmp(argv[cur_idx], "down") == 0) {
- f_down = 1;
- if (f_up != 0) {
- printf("Can't make interface up and down\\n");
- }
- } else if(strcmp(argv[cur_idx], "netmask") == 0) {
- if ((cur_idx + 1) >= argc) {
- printf("No netmask address\\n");
- return;
- }
- if (inet_pton(AF_INET, argv[cur_idx+1], &netmask.sin_addr) < 0) {
- printf("bad netmask: %s\\n", argv[cur_idx]);
- return;
- }
- f_netmask = 1;
- cur_idx += 1;
- } else if(strcmp(argv[cur_idx], "broadcast") == 0) {
- if ((cur_idx + 1) >= argc) {
- printf("No broadcast address\\n");
- return;
- }
- if (inet_pton(AF_INET, argv[cur_idx+1], &broadcast.sin_addr) < 0) {
- printf("bad broadcast: %s\\n", argv[cur_idx]);
- return;
- }
- f_bcast = 1;
- cur_idx += 1;
- } else if(strcmp(argv[cur_idx], "pointopoint") == 0) {
- if ((cur_idx + 1) >= argc) {
- printf("No pointopoint address\\n");
- return;
- }
- if (inet_pton(AF_INET, argv[cur_idx+1], &dstaddr.sin_addr) < 0) {
- printf("bad pointopoint: %s\\n", argv[cur_idx]);
- return;
- }
- f_ptp = 1;
- cur_idx += 1;
- } else {
- printf("Bad parameter: %s\\n", argv[cur_idx]);
- return;
- }
- cur_idx += 1;
- }
- printf("ifconfig ");
- if (iface != NULL) {
- printf("%s ", iface);
- if (f_ip != 0) {
- char str[256];
- inet_ntop(AF_INET, &ipaddr.sin_addr, str, 256);
- printf("%s ", str);
- }
- if (f_netmask != 0) {
- char str[256];
- inet_ntop(AF_INET, &netmask.sin_addr, str, 256);
- printf("netmask %s ", str);
- }
- if (f_bcast != 0) {
- char str[256];
- inet_ntop(AF_INET, &broadcast.sin_addr, str, 256);
- printf("broadcast %s ", str);
- }
- if (f_ptp != 0) {
- char str[256];
- inet_ntop(AF_INET, &dstaddr.sin_addr, str, 256);
- printf("pointopoint %s ", str);
- }
- if (f_up != 0) {
- printf("up\\n");
- } else if (f_down != 0) {
- printf("down\\n");
- } else {
- printf("\\n");
- }
- }
- if ((iface == NULL) \|| ((f_ip == 0) && (f_down == 0) && (f_up == 0))) {
- rtems_bsdnet_show_if_stats();
- return;
- }
- flags = 0;
- if (f_netmask) {
- rc = rtems_bsdnet_ifconfig(iface, SIOCSIFNETMASK, &netmask);
- if (rc < 0) {
- printf("Could not set netmask: %s\\n", strerror(errno));
- return;
- }
- }
- if (f_bcast) {
- rc = rtems_bsdnet_ifconfig(iface, SIOCSIFBRDADDR, &broadcast);
- if (rc < 0) {
- printf("Could not set broadcast: %s\\n", strerror(errno));
- return;
- }
- }
- if (f_ptp) {
- rc = rtems_bsdnet_ifconfig(iface, SIOCSIFDSTADDR, &dstaddr);
- if (rc < 0) {
- printf("Could not set destination address: %s\\n", strerror(errno));
- return;
- }
- flags \|= IFF_POINTOPOINT;
- }
- /* This must come _after_ setting the netmask, broadcast addresses \*/
- if (f_ip) {
- rc = rtems_bsdnet_ifconfig(iface, SIOCSIFADDR, &ipaddr);
- if (rc < 0) {
- printf("Could not set IP address: %s\\n", strerror(errno));
- return;
- }
- }
- if (f_up != 0) {
- flags \|= IFF_UP;
- }
- if (f_down != 0) {
- printf("Warning: taking interfaces down is not supported\\n");
- }
- rc = rtems_bsdnet_ifconfig(iface, SIOCSIFFLAGS, &flags);
- if (rc < 0) {
- printf("Could not set interface flags: %s\\n", strerror(errno));
- return;
- }
- }
- void mon_route(int argc, char \*argv[], unsigned32 command_arg,
- bool verbose)
- {
- int cmd;
- struct sockaddr_in dst;
- struct sockaddr_in gw;
- struct sockaddr_in netmask;
- int f_host;
- int f_gw = 0;
- int cur_idx;
- int flags;
- int rc;
- memset(&dst, 0, sizeof(dst));
- memset(&gw, 0, sizeof(gw));
- memset(&netmask, 0, sizeof(netmask));
- dst.sin_len = sizeof(dst);
- dst.sin_family = AF_INET;
- dst.sin_addr.s_addr = inet_addr("0.0.0.0");
- gw.sin_len = sizeof(gw);
- gw.sin_family = AF_INET;
- gw.sin_addr.s_addr = inet_addr("0.0.0.0");
- netmask.sin_len = sizeof(netmask);
- netmask.sin_family = AF_INET;
- netmask.sin_addr.s_addr = inet_addr("255.255.255.0");
- if (argc < 2) {
- rtems_bsdnet_show_inet_routes();
- return;
- }
- if (strcmp(argv[1], "add") == 0) {
- cmd = RTM_ADD;
- } else if (strcmp(argv[1], "del") == 0) {
- cmd = RTM_DELETE;
- } else {
- printf("invalid command: %s\\n", argv[1]);
- printf("\\tit should be 'add' or 'del'\\n");
- return;
- }
- if (argc < 3) {
- printf("not enough arguments\\n");
- return;
- }
- if (strcmp(argv[2], "-host") == 0) {
- f_host = 1;
- } else if (strcmp(argv[2], "-net") == 0) {
- f_host = 0;
- } else {
- printf("Invalid type: %s\\n", argv[1]);
- printf("\\tit should be '-host' or '-net'\\n");
- return;
- }
- if (argc < 4) {
- printf("not enough arguments\\n");
- return;
- }
- inet_pton(AF_INET, argv[3], &dst.sin_addr);
- cur_idx = 4;
- while(cur_idx < argc) {
- if (strcmp(argv[cur_idx], "gw") == 0) {
- if ((cur_idx +1) >= argc) {
- printf("no gateway address\\n");
- return;
- }
- f_gw = 1;
- inet_pton(AF_INET, argv[cur_idx + 1], &gw.sin_addr);
- cur_idx += 1;
- } else if(strcmp(argv[cur_idx], "netmask") == 0) {
- if ((cur_idx +1) >= argc) {
- printf("no netmask address\\n");
- return;
- }
- f_gw = 1;
- inet_pton(AF_INET, argv[cur_idx + 1], &netmask.sin_addr);
- cur_idx += 1;
- } else {
- printf("Unknown argument\\n");
- return;
- }
- cur_idx += 1;
- }
- flags = RTF_STATIC;
- if (f_gw != 0) {
- flags \|= RTF_GATEWAY;
- }
- if (f_host != 0) {
- flags \|= RTF_HOST;
- }
- rc = rtems_bsdnet_rtrequest(cmd, &dst, &gw, &netmask, flags, NULL);
- if (rc < 0) {
- printf("Error adding route\\n");
- }
- }
-
-Thanks to `Jay Monkman <mailto:jtm@smoothmsmoothie.com>`_ for this example
-code.
-
-Time Synchronization Using NTP
-------------------------------
-
-.. code:: c
-
- int rtems_bsdnet_synchronize_ntp (int interval, rtems_task_priority priority);
-
-If the interval argument is 0 the routine synchronizes the RTEMS time-of-day
-clock with the first NTP server in the rtems_bsdnet_ntpserve array and
-returns. The priority argument is ignored.
-
-If the interval argument is greater than 0, the routine also starts an
-RTEMS task at the specified priority and polls the NTP server every
-‘interval’ seconds. NOTE: This mode of operation has not yet been
-implemented.
-
-On successful synchronization of the RTEMS time-of-day clock the routine
-returns 0. If an error occurs a message is printed and the routine returns -1
-with an error code in errno.
-There is no timeout – if there is no response from an NTP server the
-routine will wait forever.
-
-.. COMMENT: Written by Eric Norum
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Testing the Driver
-##################
-
-Preliminary Setup
-=================
-
-The network used to test the driver should include at least:
-
-- The hardware on which the driver is to run.
- It makes testing much easier if you can run a debugger to control
- the operation of the target machine.
-
-- An Ethernet network analyzer or a workstation with an
- ‘Ethernet snoop’ program such as ``ethersnoop`` or``tcpdump``.
-
-- A workstation.
-
-During early debug, you should consider putting the target, workstation,
-and snooper on a small network by themselves. This offers a few
-advantages:
-
-- There is less traffic to look at on the snooper and for the target
- to process while bringing the driver up.
-
-- Any serious errors will impact only your small network not a building
- or campus network. You want to avoid causing any unnecessary problems.
-
-- Test traffic is easier to repeatably generate.
-
-- Performance measurements are not impacted by other systems on
- the network.
-
-Debug Output
-============
-
-There are a number of sources of debug output that can be enabled
-to aid in tracing the behavior of the network stack. The following
-is a list of them:
-
-- mbuf activity
- There are commented out calls to ``printf`` in the file``sys/mbuf.h`` in the network stack code. Uncommenting
- these lines results in output when mbuf’s are allocated
- and freed. This is very useful for finding memory leaks.
-
-- TX and RX queuing
- There are commented out calls to ``printf`` in the file``net/if.h`` in the network stack code. Uncommenting
- these lines results in output when packets are placed
- on or removed from one of the transmit or receive packet
- queues. These queues can be viewed as the boundary line
- between a device driver and the network stack. If the
- network stack is enqueuing packets to be transmitted that
- the device driver is not dequeuing, then that is indicative
- of a problem in the transmit side of the device driver.
- Conversely, if the device driver is enqueueing packets
- as it receives them (via a call to ``ether_input``) and
- they are not being dequeued by the network stack,
- then there is a problem. This situation would likely indicate
- that the network server task is not running.
-
-- TCP state transitions
- In the unlikely event that one would actually want to see
- TCP state transitions, the ``TCPDEBUG`` macro can be defined
- in the file ``opt_tcpdebug.h``. This results in the routine``tcp_trace()`` being called by the network stack and
- the state transitions logged into the ``tcp_debug`` data
- structure. If the variable ``tcpconsdebug`` in the file``netinet/tcp_debug.c`` is set to 1, then the state transitions
- will also be printed to the console.
-
-Monitor Commands
-================
-
-There are a number of command available in the shell / monitor
-to aid in tracing the behavior of the network stack. The following
-is a list of them:
-
-- ``inet``
- This command shows the current routing information for the TCP/IP stack. Following is an
- example showing the output of this command.
-
- .. code:: c
-
- Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
- 10.0.0.0 255.0.0.0 U 0 0 17 smc1
- 127.0.0.1 127.0.0.1 UH 0 0 0 lo0
-
- In this example, there is only one network interface with an IP address of 10.8.1.1. This
- link is currently not up.
- Two routes that are shown are the default routes for the Ethernet interface (10.0.0.0) and the
- loopback interface (127.0.0.1).
- Since the stack comes from BSD, this command is very similar to the netstat command. For more
- details on the network routing please look the following
- URL: (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html)
- For a quick reference to the flags, see the table below:
-
- ‘``U``’
- Up: The route is active.
-
- ‘``H``’
- Host: The route destination is a single host.
-
- ‘``G``’
- Gateway: Send anything for this destination on to this remote system, which
- will figure out from there where to send it.
-
- ‘``S``’
- Static: This route was configured manually, not automatically generated by the
- system.
-
- ‘``C``’
- Clone: Generates a new route based upon this route for machines we connect
- to. This type of route is normally used for local networks.
-
- ‘``W``’
- WasCloned: Indicated a route that was auto-configured based upon a local area
- network (Clone) route.
-
- ‘``L``’
- Link: Route involves references to Ethernet hardware.
-
-- ``mbuf``
-
- This command shows the current MBUF statistics. An example of the command is shown below:
-
- .. code:: c
-
- ************ MBUF STATISTICS \************
- mbufs:4096 clusters: 256 free: 241
- drops: 0 waits: 0 drains: 0
- free:4080 data:16 header:0 socket:0
- pcb:0 rtable:0 htable:0 atable:0
- soname:0 soopts:0 ftable:0 rights:0
- ifaddr:0 control:0 oobdata:0
-
-- ``if``
-
- This command shows the current statistics for your Ethernet driver as long as the ioctl hook``SIO_RTEMS_SHOW_STATS`` has been implemented. Below is an example:
-
- .. code:: c
-
- ************ INTERFACE STATISTICS \************
- \***** smc1 \*****
- Ethernet Address: 00:12:76:43:34:25
- Address:10.8.1.1 Broadcast Address:10.255.255.255 Net mask:255.0.0.0
- Flags: Up Broadcast Running Simplex
- Send queue limit:50 length:0 Dropped:0
- SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au)
- Rx Interrupts:0 Not First:0 Not Last:0
- Giant:0 Runt:0 Non-octet:0
- Bad CRC:0 Overrun:0 Collision:0
- Tx Interrupts:2 Deferred:0 Missed Hearbeat:0
- No Carrier:0 Retransmit Limit:0 Late Collision:0
- Underrun:0 Raw output wait:0 Coalesced:0
- Coalesce failed:0 Retries:0
- \***** lo0 \*****
- Address:127.0.0.1 Net mask:255.0.0.0
- Flags: Up Loopback Running Multicast
- Send queue limit:50 length:0 Dropped:0
-
-- ``ip``
- This command show the IP statistics for the currently configured interfaces.
-
-- ``icmp``
- This command show the ICMP statistics for the currently configured interfaces.
-
-- ``tcp``
- This command show the TCP statistics for the currently configured interfaces.
-
-- ``udp``
- This command show the UDP statistics for the currently configured interfaces.
-
-Driver basic operation
-======================
-
-The network demonstration program ``netdemo`` may be used for these tests.
-
-- Edit ``networkconfig.h`` to reflect the values for your network.
-
-- Start with ``RTEMS_USE_BOOTP`` not defined.
-
-- Edit ``networkconfig.h`` to configure the driver
- with an
- explicit Ethernet and Internet address and with reception of
- broadcast packets disabled:
- Verify that the program continues to run once the driver has been attached.
-
-- Issue a ‘``u``’ command to send UDP
- packets to the ‘discard’ port.
- Verify that the packets appear on the network.
-
-- Issue a ‘``s``’ command to print the network and driver statistics.
-
-- On a workstation, add a static route to the target system.
-
-- On that same workstation try to ‘ping’ the target system.
- Verify that the ICMP echo request and reply packets appear on the net.
-
-- Remove the static route to the target system.
- Modify ``networkconfig.h`` to attach the driver
- with reception of broadcast packets enabled.
- Try to ‘ping’ the target system again.
- Verify that ARP request/reply and ICMP echo request/reply packets appear
- on the net.
-
-- Issue a ‘``t``’ command to send TCP
- packets to the ‘discard’ port.
- Verify that the packets appear on the network.
-
-- Issue a ‘``s``’ command to print the network and driver statistics.
-
-- Verify that you can telnet to ports 24742
- and 24743 on the target system from one or more
- workstations on your network.
-
-BOOTP/DHCP operation
-====================
-
-Set up a BOOTP/DHCP server on the network.
-Set define ``RTEMS USE_BOOT`` in ``networkconfig.h``.
-Run the ``netdemo`` test program.
-Verify that the target system configures itself from the BOOTP/DHCP server and
-that all the above tests succeed.
-
-Stress Tests
-============
-
-Once the driver passes the tests described in the previous section it should
-be subjected to conditions which exercise it more
-thoroughly and which test its error handling routines.
-
-Giant packets
--------------
-
-- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to
- a smaller value, say 514.
-
-- ‘Ping’ the driver from another workstation and verify
- that frames larger than 514 bytes are correctly rejected.
-
-- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored to 1518.
-
-Resource Exhaustion
--------------------
-
-- Edit ``networkconfig.h``
- so that the driver is configured with just two receive and transmit descriptors.
-
-- Compile and run the ``netdemo`` program.
-
-- Verify that the program operates properly and that you can
- still telnet to both the ports.
-
-- Display the driver statistics (Console ‘``s``’ command or telnet
- ‘control-G’ character) and verify that:
-
- # The number of transmit interrupts is non-zero.
- This indicates that all transmit descriptors have been in use at some time.
-
- # The number of missed packets is non-zero.
- This indicates that all receive descriptors have been in use at some time.
-
-Cable Faults
-------------
-
-- Run the ``netdemo`` program.
-
-- Issue a ‘``u``’ console command to make the target machine transmit
- a bunch of UDP packets.
-
-- While the packets are being transmitted, disconnect and reconnect the
- network cable.
-
-- Display the network statistics and verify that the driver has
- detected the loss of carrier.
-
-- Verify that you can still telnet to both ports on the target machine.
-
-Throughput
-----------
-
-Run the ``ttcp`` network benchmark program.
-Transfer large amounts of data (100’s of megabytes) to and from the target
-system.
-
-The procedure for testing throughput from a host to an RTEMS target
-is as follows:
-
-# Download and start the ttcp program on the Target.
-
-# In response to the ``ttcp`` prompt, enter ``-s -r``. The
- meaning of these flags is described in the ``ttcp.1`` manual page
- found in the ``ttcp_orig`` subdirectory.
-
-# On the host run ``ttcp -s -t <<insert the hostname or IP address of the Target here>>``
-
-The procedure for testing throughput from an RTEMS target
-to a Host is as follows:
-
-# On the host run ``ttcp -s -r``.
-
-# Download and start the ttcp program on the Target.
-
-# In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or IP address of the Target here>>``. You need to type the
- IP address of the host unless your Target is talking to your Domain Name
- Server.
-
-To change the number of buffers, the buffer size, etc. you just add the
-extra flags to the ``-t`` machine as specified in the ``ttcp.1``
-manual page found in the ``ttcp_orig`` subdirectory.
-
-.. COMMENT: Text Written by Jake Janovetz
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Network Servers
-###############
-
-RTEMS FTP Daemon
-================
-
-The RTEMS FTPD is a complete file transfer protocol (FTP) daemon
-which can store, retrieve, and manipulate files on the local
-filesystem. In addition, the RTEMS FTPD provides “hooks”
-which are actions performed on received data. Hooks are useful
-in situations where a destination file is not necessarily
-appropriate or in cases when a formal device driver has not yet
-been implemented.
-
-This server was implemented and documented by Jake Janovetz
-(janovetz@tempest.ece.uiuc.edu).
-
-Configuration Parameters
-------------------------
-
-The configuration structure for FTPD is as follows:
-.. code:: c
-
- struct rtems_ftpd_configuration
- {
- rtems_task_priority priority; /* FTPD task priority \*/
- unsigned long max_hook_filesize; /* Maximum buffersize \*/
- /* for hooks \*/
- int port; /* Well-known port \*/
- struct rtems_ftpd_hook \*hooks; /* List of hooks \*/
- };
-
-The FTPD task priority is specified with ``priority``. Because
-hooks are not saved as files, the received data is placed in an
-allocated buffer. ``max_hook_filesize`` specifies the maximum
-size of this buffer. Finally, ``hooks`` is a pointer to the
-configured hooks structure.
-
-Initializing FTPD (Starting the daemon)
----------------------------------------
-
-Starting FTPD is done with a call to ``rtems_initialize_ftpd()``.
-The configuration structure must be provided in the application
-source code. Example hooks structure and configuration structure
-folllow.
-.. code:: c
-
- struct rtems_ftpd_hook ftp_hooks[] =
- {
- {"untar", Untar_FromMemory},
- {NULL, NULL}
- };
- struct rtems_ftpd_configuration rtems_ftpd_configuration =
- {
- 40, /* FTPD task priority \*/
- 512*1024, /* Maximum hook 'file' size \*/
- 0, /* Use default port \*/
- ftp_hooks /* Local ftp hooks \*/
- };
-
-Specifying 0 for the well-known port causes FTPD to use the
-UNIX standard FTPD port (21).
-
-Using Hooks
------------
-
-In the example above, one hook was installed. The hook causes
-FTPD to call the function ``Untar_FromMemory`` when the
-user sends data to the file ``untar``. The prototype for
-the ``untar`` hook (and hooks, in general) is:
-.. code:: c
-
- int Untar_FromMemory(unsigned char \*tar_buf, unsigned long size);
-
-An example FTP transcript which exercises this hook is:
-.. code:: c
-
- 220 RTEMS FTP server (Version 1.0-JWJ) ready.
- Name (dcomm0:janovetz): John Galt
- 230 User logged in.
- Remote system type is RTEMS.
- ftp> bin
- 200 Type set to I.
- ftp> dir
- 200 PORT command successful.
- 150 ASCII data connection for LIST.
- drwxrwx--x 0 0 268 dev
- drwxrwx--x 0 0 0 TFTP
- 226 Transfer complete.
- ftp> put html.tar untar
- local: html.tar remote: untar
- 200 PORT command successful.
- 150 BINARY data connection.
- 210 File transferred successfully.
- 471040 bytes sent in 0.48 secs (9.6e+02 Kbytes/sec)
- ftp> dir
- 200 PORT command successful.
- 150 ASCII data connection for LIST.
- drwxrwx--x 0 0 268 dev
- drwxrwx--x 0 0 0 TFTP
- drwxrwx--x 0 0 3484 public_html
- 226 Transfer complete.
- ftp> quit
- 221 Goodbye.
-
-.. COMMENT: RTEMS Remote Debugger Server Specifications
-
-.. COMMENT: Written by: Emmanuel Raguet <raguet@crf.canon.fr>
-
-DEC 21140 Driver
-################
-
-DEC 21240 Driver Introduction
-=============================
-
-.. COMMENT: XXX add back in cross reference to list of boards.
-
-One aim of our project is to port RTEMS on a standard PowerPC platform.
-To achieve it, we have chosen a Motorola MCP750 board. This board includes
-an Ethernet controller based on a DEC21140 chip. Because RTEMS has a
-TCP/IP stack, we will
-have to develop the DEC21140 related ethernet driver for the PowerPC port of
-RTEMS. As this controller is able to support 100Mbps network and as there is
-a lot of PCI card using this DEC chip, we have decided to first
-implement this driver on an Intel PC386 target to provide a solution for using
-RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in
-a second phase.
-
-The aim of this document is to give some PCI board generalities and
-to explain the software architecture of the RTEMS driver. Finally, we will see
-what will be done for ChorusOs and Netboot environment .
-
-Document Revision History
-=========================
-
-*Current release*:
-
-- Current applicable release is 1.0.
-
-*Existing releases*:
-
-- 1.0 : Released the 10/02/98. First version of this document.
-
-- 0.1 : First draft of this document
-
-*Planned releases*:
-
-- None planned today.
-
-DEC21140 PCI Board Generalities
-===============================
-
-.. COMMENT: XXX add crossreference to PCI Register Figure
-
-This chapter describes rapidely the PCI interface of this Ethernet controller.
-The board we have chosen for our PC386 implementation is a D-Link DFE-500TX.
-This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.
-Like other PCI devices, this board has a PCI device’s header containing some
-required configuration registers, as shown in the PCI Register Figure.
-By reading
-or writing these registers, a driver can obtain information about the type of
-the board, the interrupt it uses, the mapping of the chip specific registers, ...
-
-On Intel target, the chip specific registers can be accessed via 2
-methods : I/O port access or PCI address mapped access. We have chosen to implement
-the PCI address access to obtain compatible source code to the port the driver
-on a PowerPC target.
-
-.. COMMENT: PCI Device's Configuration Header Space Format
-
-
-.. image:: images/PCIreg.jpg
-
-
-.. COMMENT: XXX add crossreference to PCI Register Figure
-
-On RTEMS, a PCI API exists. We have used it to configure the board. After initializing
-this PCI module via the ``pci_initialize()`` function, we try to detect
-the DEC21140 based ethernet board. This board is characterized by its Vendor
-ID (0x1011) and its Device ID (0x0009). We give these arguments to the``pcib_find_by_deviceid``
-function which returns , if the device is present, a pointer to the configuration
-header space (see PCI Registers Fgure). Once this operation performed,
-the driver
-is able to extract the information it needs to configure the board internal
-registers, like the interrupt line, the base address,... The board internal
-registers will not be detailled here. You can find them in *DIGITAL
-Semiconductor 21140A PCI Fast Ethernet LAN Controller
-- Hardware Reference Manual*.
-
-.. COMMENT: fix citation
-
-RTEMS Driver Software Architecture
-==================================
-
-In this chapter will see the initialization phase, how the controller uses the
-host memory and the 2 threads launched at the initialization time.
-
-Initialization phase
---------------------
-
-The DEC21140 Ethernet driver keeps the same software architecture than the other
-RTEMS ethernet drivers. The only API the programmer can use is the ``rtems_dec21140_driver_attach````(struct rtems_bsdnet_ifconfig \*config)`` function which
-detects the board and initializes the associated data structure (with registers
-base address, entry points to low-level initialization function,...), if the
-board is found.
-
-Once the attach function executed, the driver initializes the DEC
-chip. Then the driver connects an interrupt handler to the interrupt line driven
-by the Ethernet controller (the only interrupt which will be treated is the
-receive interrupt) and launches 2 threads : a receiver thread and a transmitter
-thread. Then the driver waits for incoming frame to give to the protocol stack
-or outcoming frame to send on the physical link.
-
-Memory Buffer
--------------
-
-.. COMMENT: XXX add cross reference to Problem
-
-This DEC chip uses the host memory to store the incoming Ethernet frames and
-the descriptor of these frames. We have chosen to use 7 receive buffers and
-1 transmit buffer to optimize memory allocation due to cache and paging problem
-that will be explained in the section *Encountered Problems*.
-
-To reference these buffers to the DEC chip we use a buffer descriptors
-ring. The descriptor structure is defined in the Buffer Descriptor Figure.
-Each descriptor
-can reference one or two memory buffers. We choose to use only one buffer of
-1520 bytes per descriptor.
-
-The difference between a receive and a transmit buffer descriptor
-is located in the status and control bits fields. We do not give details here,
-please refer to the \[DEC21140 Hardware Manual].
-
-.. COMMENT: Buffer Descriptor
-
-
-.. image:: images/recvbd.jpg
-
-
-Receiver Thread
----------------
-
-This thread is event driven. Each time a DEC PCI board interrupt occurs, the
-handler checks if this is a receive interrupt and send an event “reception”
-to the receiver thread which looks into the entire buffer descriptors ring the
-ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs
-to host processor). Each valid incoming ethernet frame is sent to the protocol
-stack and the buffer descriptor is given back to the DEC board (the host processor
-reset bit OWN, which means descriptor belongs to 21140).
-
-Transmitter Thread
-------------------
-
-This thread is also event driven. Each time an Ethernet frame is put in the
-transmit queue, an event is sent to the transmit thread, which empty the queue
-by sending each outcoming frame. Because we use only one transmit buffer, we
-are sure that the frame is well-sent before sending the next.
-
-Encountered Problems
-====================
-
-On Intel PC386 target, we were faced with a problem of memory cache management.
-Because the DEC chip uses the host memory to store the incoming frame and because
-the DEC21140 configuration registers are mapped into the PCI address space,
-we must ensure that the data read (or written) by the host processor are the
-ones written (or read) by the DEC21140 device in the host memory and not old
-data stored in the cache memory. Therefore, we had to provide a way to manage
-the cache. This module is described in the document *RTEMS
-Cache Management For Intel*. On Intel, the
-memory region cache management is available only if the paging unit is enabled.
-We have used this paging mechanism, with 4Kb page. All the buffers allocated
-to store the incoming or outcoming frames, buffer descriptor and also the PCI
-address space of the DEC board are located in a memory space with cache disable.
-
-Concerning the buffers and their descriptors, we have tried to optimize
-the memory space in term of allocated page. One buffer has 1520 bytes, one descriptor
-has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and for each,
-1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire pages. This
-allows not to lose too much memory or not to disable cache memory for a page
-which contains other data than buffer, which could decrease performance.
-
-ChorusOs DEC Driver
-===================
-
-Because ChorusOs is used in several Canon CRF projects, we must provide such
-a driver on this OS to ensure compatibility between the RTEMS and ChorusOs developments.
-On ChorusOs, a DEC driver source code already exists but only for a PowerPC
-target. We plan to port this code (which uses ChorusOs API) on Intel target.
-This will allow us to have homogeneous developments. Moreover, the port of the
-development performed with ChorusOs environment to RTEMS environment will be
-easier for the developers.
-
-Netboot DEC driver
-==================
-
-We use Netboot tool to load our development from a server to the target via
-an ethernet network. Currently, this tool does not support the DEC board. We
-plan to port the DEC driver for the Netboot tool.
-
-But concerning the port of the DEC driver into Netboot, we are faced
-with a problem : in RTEMS environment, the DEC driver is interrupt or event
-driven, in Netboot environment, it must be used in polling mode. It means that
-we will have to re-write some mechanisms of this driver.
-
-List of Ethernet cards using the DEC chip
-=========================================
-
-Many Ethernet adapter cards use the Tulip chip. Here is a non exhaustive list
-of adapters which support this driver :
-
-- Accton EtherDuo PCI.
-
-- Accton EN1207 All three media types supported.
-
-- Adaptec ANA6911/TX 21140-AC.
-
-- Cogent EM110 21140-A with DP83840 N-Way MII transceiver.
-
-- Cogent EM400 EM100 with 4 21140 100mbps-only ports + PCI Bridge.
-
-- Danpex EN-9400P3.
-
-- D-Link DFE500-Tx 21140-A with DP83840 transceiver.
-
-- Kingston EtherX KNE100TX 21140AE.
-
-- Netgear FX310 TX 10/100 21140AE.
-
-- SMC EtherPower10/100 With DEC21140 and 68836 SYM transceiver.
-
-- SMC EtherPower10/100 With DEC21140-AC and DP83840 MII transceiver.
- Note: The EtherPower II uses the EPIC chip, which requires a different driver.
-
-- Surecom EP-320X DEC 21140.
-
-- Thomas Conrad TC5048.
-
-- Znyx ZX345 21140-A, usually with the DP83840 N-Way MII transciever. Some ZX345
- cards made in 1996 have an ICS 1890 transciver instead.
-
-- ZNYX ZX348 Two 21140-A chips using ICS 1890 transcievers and either a 21052
- or 21152 bridge. Early versions used National 83840 transcievers, but later
- versions are depopulated ZX346 boards.
-
-- ZNYX ZX351 21140 chip with a Broadcom 100BaseT4 transciever.
-
-Our DEC driver has not been tested with all these cards, only with the D-Link
-DFE500-TX.
-
-- *[DEC21140 Hardware Manual] DIGITAL, *DIGITAL
- Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware
- Reference Manual**.
-
-- *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**.
-
-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/porting/porting_old_reference_only.rst b/porting/porting_old_reference_only.rst
deleted file mode 100644
index fdc9443..0000000
--- a/porting/porting_old_reference_only.rst
+++ /dev/null
@@ -1,1920 +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 Porting 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: 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 Porting Guide
-
-===================
-RTEMS Porting 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 Porting Guide
-###################
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Preface
-#######
-
-The purpose of this manual is to provide a roadmap to those people porting
-RTEMS to a new CPU family. This process includes a variety of activities
-including the following:
-
-- targeting the GNU development tools
-
-- porting the RTEMS executive code
-
-- developing a Board Support Package
-
-- writing an RTEMS CPU Supplement manual for the completed port.
-
-This document focuses on the process of actually porting the RTEMS
-executive code proper. Each of the data structures, routines, and macro
-definitions required of a port of RTEMS is described in this document.
-
-Porting any operating system, including RTEMS, requires knowledge of the
-operating system, target CPU architecture, and debug environment. It is
-very desirable to have a CPU simulator or hardware emulator when debugging
-the port. This manual assumes that the user is familiar with building and
-using RTEMS, the C programming language, and the target CPU architecture.
-It is desirable to be familiar with the assembly language for the target
-CPU family but since only a limited amount of assembly is required to port
-RTEMS.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Development Tools
-#################
-
-When porting RTEMS to a new CPU architecture, one will have to have a
-development environment including compiler, assembler, linker, and
-debugger. The GNU development tool suite used by RTEMS supports most
-modern CPU families. Often all that is required is to add RTEMS
-configurations for the target CPU family. RTEMS targets for the GNU tools
-usually start life as little more than aliases for existing embedded
-configurations. At this point in time, ELF is supported on most of the
-CPU families with a tool target of the form CPU-elf. If this target is
-not supported by all of the GNU tools, then it will be necessary to
-determine the configuration that makes the best starting point regardless
-of the target object format.
-
-Porting and retargetting the GNU tools is beyond the scope of this manual.
-The best advice that can be offered is to look at the existing RTEMS
-targets in the tool source and use that as a guideline.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Source Code Organization
-########################
-
-This section describes the organization of the source code within RTEMS
-that is CPU family and CPU model dependent.
-
-Introduction
-============
-
-The CPU family dependent files associated with a port of the RTEMS
-executive code proper to a particular processor family are found in
-cpukit/score/cpu. Support code for this port as well as processor
-dependent code which may be reused across multiple Board Support Packages
-is found in c/src/lib/libcpu.
-
-XXX list the files and directories here
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-CPU Model Variations
-####################
-
-XXX enhance using portability presentation from CS595 class. See
-general/portability.ppt.
-
-Since the text in the next section was written, RTEMS view of
-portability has grown to distinguish totally portable, CPU
-family dependent, CPU model dependent, peripheral chip dependent
-and board dependent. This text was part of a larger paper that
-did not even cover portability completely as it existed when this
-was written and certainly is out of date now. :)
-
-Overview of RTEMS Portability
-=============================
-
-RTEMS was designed to be a highly portable, reusable software component.
-This reflects the fundamental nature of embedded systems in which hardware
-components, ranging from boards to peripherals to even the processor
-itself, are selected specifically to meet the requirements of a particular
-project.
-
-Processor Families
-------------------
-
-Since there are a wide variety of embedded systems, there are a wide
-variety of processors targeting embedded systems. RTEMS alleviates some of
-the burden on the embedded systems programmer by providing a consistent,
-high-performance environment regardless of the target processor. RTEMS
-has been ported to a variety of microprocessor families including:
-
-- Motorola ColdFire
-
-- Motorola MC68xxx
-
-- Motorola MC683xx
-
-- Intel ix86 (i386, i486, Pentium and above)
-
-- ARM
-
-- MIPS
-
-- PowerPC 4xx, 5xx, 6xx, 7xx, 8xx, and 84xx
-
-- SPARC
-
-- Hitachi H8/300
-
-- Hitachi SH
-
-- OpenCores OR32
-
-- Texas Instruments C3x/C4x
-
-In addition, there is a port of RTEMS to UNIX that uses standard UNIX
-services to simulate the embedded environment.
-
-Each RTEMS port supplies a well-defined set of services that are the
-foundation for the highly portable RTEMS and POSIX API implementations.
-When porting to a new processor family, one must provide the processor
-dependent implementation of these services. This set of processor
-dependent core services includes software to perform interrupt
-dispatching, context switches, and manipulate task register sets.
-
-The RTEMS approach to handling varying processor models reflects the
-approach taken by the designers of the processors themselves. In each
-processor family, there is a core architecture that must be implemented on
-all processor models within the family to provide any level of
-compatibility. Many of the modern RISC architectures refer to this as the
-Architectural Definition. The Architectural Definition is intended to be
-independent of any particular implementation. Additionally, there is a
-feature set which is allowed to vary in a defined way amongst the
-processor models. These feature sets may be defined as Optional in the
-Architectural Definition, be left as implementation defined
-characteristics, or be processor model specific extensions. Support for
-floating point, virtual memory, and low power mode are common Optional
-features included in an Architectural Definition.
-
-The processor family dependent software in RTEMS includes a definition of
-which features are present in each supported processor model. This often
-makes adding support for a new processor model within a supported family
-as simple as determining which features are present in the new processor
-implementation. If the new processor model varies in a way previously
-unaccounted for, then this must be addressed. This could be the result of
-a new Optional feature set being added to the Architectural Definition.
-Alternatively, this particular processor model could have a new and
-different implementation of a feature left as undefined in the
-Architectural Definition. This would require software to be written to
-utilize that feature.
-
-There is a relatively small set of features that may vary in a processor
-family. As the number of processor models in the family grow, the
-addition of each new model only requires adding an entry for the new model
-to the single feature table. It does not require searching for every
-conditional based on processor model and adding the new model in the
-appropriate place. This significantly eases the burden of adding a new
-processor model as it centralizes and logically simplifies the process.
-
-Boards
-------
-
-Being portable both between models within a processor family and across
-processor families is not enough to address the needs of embedded systems
-developers. Custom board development is the norm for embedded systems.
-Each of these boards is optimized for a particular project. The processor
-and peripheral set have been chosen to meet a particular set of system
-requirements. The tools in the embedded systems developers’ toolbox must
-support their project’s unique board. RTEMS addresses this issue via the
-Board Support Package.
-
-RTEMS segregates board specific code to make it possible for the embedded
-systems developer to easily replace and customize this software. A
-minimal Board Support Package includes device drivers for a clock tick,
-console I/O, and a benchmark timer (optional) as well as startup and
-miscellaneous support code. The Board Support Package for a project may
-be extended to include the device drivers for any peripherals on the
-custom board.
-
-Applications
-------------
-
-One important design goal of RTEMS was to provide a bridge between the
-application software and the target hardware. Most hardware dependencies
-for real-time applications can be localized to the low level device
-drivers which provide an abstracted view of the 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. The following figure illustrates
-how RTEMS serves as a buffer between the project dependent application
-code and the target hardware.
-
-Coding Issues
-=============
-
-XXX deal with this as it applies to score/cpu. Section name may
-be bad.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-CPU Initialization
-##################
-
-This section describes the general CPU and system initialization sequence
-as it pertains to the CPU dependent code.
-
-Introduction
-============
-
-XXX general startup sequence description rewritten to make it more
-applicable to CPU depdent code in executive
-
-Initializing the CPU
-====================
-
-The _CPU_Initialize routine performs processor dependent initialization.
-.. code:: c
-
- void _CPU_Initialize(
- void (\*thread_dispatch) /* may be ignored \*/
- )
-
-The thread_dispatch argument is the address of the entry point for the
-routine called at the end of an ISR once it has been decided a context
-switch is necessary. On some compilation systems it is difficult to call
-a high-level language routine from assembly. Providing the address of the
-_Thread_ISR_Dispatch routine allows the porter an easy way to obtain this
-critical address and thus provides an easy way to work around this
-limitation on these systems.
-
-If you encounter this problem save the entry point in a CPU dependent
-variable as shown below:
-.. code:: c
-
- _CPU_Thread_dispatch_pointer = thread_dispatch;
-
-During the initialization of the context for tasks with floating point,
-the CPU dependent code is responsible for initializing the floating point
-context. If there is not an easy way to initialize the FP context during
-Context_Initialize, then it is usually easier to save an "uninitialized"
-FP context here and copy it to the task’s during Context_Initialize. If
-this technique is used to initialize the FP contexts, then it is important
-to ensure that the state of the floating point unit is in a coherent,
-initialized state.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Interrupts
-##########
-
-Introduction
-============
-
-Interrupt Levels
-================
-
-RTEMS is designed assuming that a CPU family has a level associated with
-interrupts. Interrupts below the current interrupt level are masked and
-do not interrupt the CPU until the interrupt level is lowered. This
-design provides for 256 distinct interrupt levels even though most CPU
-implementations support far fewer levels. Interrupt level 0 is assumed to
-map to the hardware settings for all interrupts enabled.
-
-Over the years that RTEMS has been available, there has been much
-discussion on how to handle CPU families which support very few interrupt
-levels such as the i386, PowerPC, and HP-PA RISC. XXX
-
-Interrupt Level Mask
---------------------
-
-The CPU_MODES_INTERRUPT_MASK macro defines the number of bits actually used in the interrupt field of the task mode. How those bits map to the CPU interrupt levels is defined by the routine _CPU_ISR_Set_level().
-
-The following illustrates how the CPU_MODES_INTERRUPT_MASK is set on a CPU
-family like the Intel i386 where the CPU itself only recognizes two
-interrupt levels - enabled and disabled.
-.. code:: c
-
- #define CPU_MODES_INTERRUPT_MASK 0x00000001
-
-Obtaining the Current Interrupt Level
--------------------------------------
-
-The _CPU_ISR_Get_level function returns the current interrupt level.
-.. code:: c
-
- uint32_t _CPU_ISR_Get_level( void )
-
-Set the Interrupt Level
------------------------
-
-The _CPU_ISR_Set_level routine maps the interrupt level in the Classic API
-task mode onto the hardware that the CPU actually provides. Currently,
-interrupt levels that do not map onto the CPU in a generic fashion are
-undefined. Someday, it would be nice if these were "mapped" by the
-application via a callout. For example, the Motorola m68k has 8 levels 0
-- 7, and levels 8 - 255 are currently undefined. Levels 8 - 255 would be
-available for bsp/application specific meaning. This could be used to
-manage a programmable interrupt controller via the rtems_task_mode
-directive.
-
-The following is a dummy implementation of the _CPU_ISR_Set_level routine:
-.. code:: c
-
- #define _CPU_ISR_Set_level( new_level ) \\
- { \\
- }
-
-The following is the implementation from the Motorola M68K:
-.. code:: c
-
- XXX insert m68k implementation here
-
-Disable Interrupts
-------------------
-
-The _CPU_ISR_Disable routine disable all external interrupts. It returns
-the previous interrupt level in the single parameter _isr_cookie. This
-routine is used to disable interrupts during a critical section in the
-RTEMS executive. Great care is taken inside the executive to ensure that
-interrupts are disabled for a minimum length of time. It is important to
-note that the way the previous level is returned forces the implementation
-to be a macro that translates to either inline assembly language or a
-function call whose return value is placed into _isr_cookie.
-
-It is important for the porter to realize that the value of _isr_cookie
-has no defined meaning except that it is the most convenient format for
-the _CPU_ISR_Disable, _CPU_ISR_Enable, and _CPU_ISR_Disable routines to
-manipulate. It is typically the contents of the processor status
-register. It is NOT the same format as manipulated by the
-_CPU_ISR_Get_level and _CPU_ISR_Set_level routines. The following is a
-dummy implementation that simply sets the previous level to 0.
-.. code:: c
-
- #define _CPU_ISR_Disable( _isr_cookie ) \\
- { \\
- (_isr_cookie) = 0; /* do something to prevent warnings \*/ \\
- }
-
-The following is the implementation from the Motorola M68K port:
-.. code:: c
-
- XXX insert m68k port here
-
-Enable Interrupts
------------------
-
-The _CPU_ISR_Enable routines enables interrupts to the previous level
-(returned by _CPU_ISR_Disable). This routine is invoked at the end of an
-RTEMS critical section to reenable interrupts. The parameter _level is
-not modified but indicates that level that interrupts should be enabled
-to. The following illustrates a dummy implementation of the
-_CPU_ISR_Enable routine:
-.. code:: c
-
- #define _CPU_ISR_Enable( _isr_cookie ) \\
- { \\
- }
-
-The following is the implementation from the Motorola M68K port:
-.. code:: c
-
- XXX insert m68k version here
-
-Flash Interrupts
-----------------
-
-The _CPU_ISR_Flash routine temporarily restores the interrupt to _level
-before immediately disabling them again. This is used to divide long
-RTEMS critical sections into two or more parts. This routine is always
-preceded by a call to _CPU_ISR_Disable and followed by a call to
-_CPU_ISR_Enable. The parameter _level is not modified.
-
-The following is a dummy implementation of the _CPU_ISR_Flash routine:
-.. code:: c
-
- #define _CPU_ISR_Flash( _isr_cookie ) \\
- { \\
- }
-
-The following is the implementation from the Motorola M68K port:
-.. code:: c
-
- XXX insert m68k version here
-
-Interrupt Stack Management
-==========================
-
-Hardware or Software Managed Interrupt Stack
---------------------------------------------
-
-The setting of the CPU_HAS_SOFTWARE_INTERRUPT_STACK indicates whether the
-interrupt stack is managed by RTEMS in software or the CPU has direct
-support for an interrupt stack. If RTEMS is to manage a dedicated
-interrupt stack in software, then this macro should be set to TRUE and the
-memory for the software managed interrupt stack is allocated in``_ISR_Handler_initialization``. If this macro is set to FALSE, then
-RTEMS assumes that the hardware managed interrupt stack is supported by
-this CPU. If the CPU has a hardware managed interrupt stack, then the
-porter has the option of letting the BSP allcoate and initialize the
-interrupt stack or letting RTEMS do this. If RTEMS is to allocate the
-memory for the interrupt stack, then the macro
-CPU_ALLOCATE_INTERRUPT_STACK should be set to TRUE. If this macro is set
-to FALSE, then it is the responsibility of the BSP to allocate the memory
-for this stack and initialize it.
-
-If the CPU does not support a dedicated interrupt stack, then the porter
-has two options: (1) execute interrupts on the stack of the interrupted
-task, and (2) have RTEMS manage a dedicated interrupt stack.
-
-NOTE: If CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE, then the macro
-CPU_ALLOCATE_INTERRUPT_STACK should also be set to TRUE.
-
-Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
-CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is possible
-that both are FALSE for a particular CPU. Although it is unclear what
-that would imply about the interrupt processing procedure on that CPU.
-
-Allocation of Interrupt Stack Memory
-------------------------------------
-
-Whether or not the interrupt stack is hardware or software managed, RTEMS
-may allocate memory for the interrupt stack from the Executive Workspace.
-If RTEMS is going to allocate the memory for a dedicated interrupt stack
-in the Interrupt Manager, then the macro CPU_ALLOCATE_INTERRUPT_STACK
-should be set to TRUE.
-
-NOTE: This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
-.. code:: c
-
- #define CPU_ALLOCATE_INTERRUPT_STACK TRUE
-
-If the CPU_HAS_SOFTWARE_INTERRUPT_STACK macro is set to TRUE, then RTEMS automatically allocates the stack memory in the initialization of the Interrupt Manager and the switch to that stack is performed in ``_ISR_Handler`` on the outermost interrupt. The _CPU_Interrupt_stack_low and _CPU_Interrupt_stack_high variables contain the addresses of the the lowest and highest addresses of the memory allocated for the interrupt stack. Although technically only one of these addresses is required to switch to the interrupt stack, by always providing both addresses, the port has more options avaialble to it without requiring modifications to the portable parts of the executive. Whether the stack grows up or down, this give the CPU dependent code the option of picking the version it wants to use.
-.. code:: c
-
- SCORE_EXTERN void \*_CPU_Interrupt_stack_low;
- SCORE_EXTERN void \*_CPU_Interrupt_stack_high;
-
-NOTE: These two variables are required if the macro
-CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
-
-Install the Interrupt Stack
----------------------------
-
-The _CPU_Install_interrupt_stack routine XXX
-
-This routine installs the hardware interrupt stack pointer.
-
-NOTE: It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STAC is TRUE.
-.. code:: c
-
- void _CPU_Install_interrupt_stack( void )
-
-ISR Installation
-================
-
-Install a Raw Interrupt Handler
--------------------------------
-
-The _CPU_ISR_install_raw_handler XXX
-.. code:: c
-
- void _CPU_ISR_install_raw_handler(
- unsigned32 vector,
- proc_ptr new_handler,
- proc_ptr \*old_handler
- )
-
-This is where we install the interrupt handler into the "raw" interrupt
-table used by the CPU to dispatch interrupt handlers.
-
-Interrupt Context
------------------
-
-Maximum Number of Vectors
--------------------------
-
-There are two related macros used to defines the number of entries in the
-_ISR_Vector_table managed by RTEMS. The macro
-CPU_INTERRUPT_NUMBER_OF_VECTORS is the actual number of vectors supported
-by this CPU model. The second macro is the
-CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER. Since the table is zero-based, this
-indicates the highest vector number which can be looked up in the table
-and mapped into a user provided handler.
-.. code:: c
-
- #define CPU_INTERRUPT_NUMBER_OF_VECTORS 32
- #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER \\
- (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
-
-Install RTEMS Interrupt Handler
--------------------------------
-
-The _CPU_ISR_install_vector routine installs the RTEMS handler for the
-specified vector.
-
-XXX Input parameters:
-vector - interrupt vector number
-old_handler - former ISR for this vector number
-new_handler - replacement ISR for this vector number
-.. code:: c
-
- void _CPU_ISR_install_vector(
- unsigned32 vector,
- proc_ptr new_handler,
- proc_ptr \*old_handler
- )
-
-.. code:: c
-
- *old_handler = _ISR_Vector_table[ vector ];
-
-If the interrupt vector table is a table of pointer to isr entry points,
-then we need to install the appropriate RTEMS interrupt handler for this
-vector number.
-.. code:: c
-
- _CPU_ISR_install_raw_handler( vector, new_handler, old_handler );
-
-We put the actual user ISR address in _ISR_vector_table. This will be
-used by the ``_ISR_Handler`` so the user gets control.
-.. code:: c
-
- _ISR_Vector_table[ vector ] = new_handler;
-
-Interrupt Processing
-====================
-
-Interrupt Frame Data Structure
-------------------------------
-
-When an interrupt occurs, it is the responsibility of the interrupt
-dispatching software to save the context of the processor such that an ISR
-written in a high-level language (typically C) can be invoked without
-damaging the state of the task that was interrupted. In general, this
-results in the saving of registers which are NOT preserved across
-subroutine calls as well as any special interrupt state. A port should
-define the ``CPU_Interrupt_frame`` structure so that application code can
-examine the saved state.
-.. code:: c
-
- typedef struct {
- unsigned32 not_preserved_register_1;
- unsigned32 special_interrupt_register;
- } CPU_Interrupt_frame;
-
-Interrupt Dispatching
----------------------
-
-The ``_ISR_Handler`` routine provides the RTEMS interrupt management.
-.. code:: c
-
- void _ISR_Handler()
-
-This discussion ignores a lot of the ugly details in a real implementation
-such as saving enough registers/state to be able to do something real.
-Keep in mind that the goal is to invoke a user’s ISR handler which is
-written in C. That ISR handler uses a known set of registers thus
-allowing the ISR to preserve only those that would normally be corrupted
-by a subroutine call.
-
-Also note that the exact order is to a large extent flexible. Hardware
-will dictate a sequence for a certain subset of ``_ISR_Handler`` while
-requirements for setting the RTEMS state variables that indicate the
-interrupt nest level (``_ISR_Nest_level``) and dispatching disable
-level (``_Thread_Dispatch_disable_level``) will also
-restrict the allowable order.
-
-Upon entry to ``_ISR_Handler``, ``_Thread_Dispatch_disable_level`` is
-zero if the interrupt occurred while outside an RTEMS service call.
-Conversely, it will be non-zero if interrupting an RTEMS service
-call. Thus, ``_Thread_Dispatch_disable_level`` will always be
-greater than or equal to ``_ISR_Nest_level`` and not strictly
-equal.
-
-Upon entry to the "common" ``_ISR_Handler``, the vector number must be
-available. On some CPUs the hardware puts either the vector number or the
-offset into the vector table for this ISR in a known place. If the
-hardware does not provide this information, then the assembly portion of
-RTEMS for this port will contain a set of distinct interrupt entry points
-which somehow place the vector number in a known place (which is safe if
-another interrupt nests this one) and branches to ``_ISR_Handler``.
-.. code:: c
-
- save some or all context on stack
- may need to save some special interrupt information for exit
- #if ( CPU_HAS_SOFTWARE_INTERRUPT_STACK == TRUE )
- if ( _ISR_Nest_level == 0 )
- switch to software interrupt stack
- #endif
- _ISR_Nest_level++;
- _Thread_Dispatch_disable_level++;
- (\*_ISR_Vector_table[ vector ])( vector );
- --_ISR_Nest_level;
- if ( _ISR_Nest_level )
- goto the label "exit interrupt (simple case)"
- #if ( CPU_HAS_SOFTWARE_INTERRUPT_STACK == TRUE )
- restore stack
- #endif
- if ( _Thread_Dispatch_disable_level )
- goto the label "exit interrupt (simple case)"
- if ( _Thread_Dispatch_necessary )
- call _Thread_Dispatch() or prepare to return to _ISR_Dispatch
- prepare to get out of interrupt
- return from interrupt (maybe to _ISR_Dispatch)
- LABEL "exit interrupt (simple case):
- prepare to get out of interrupt
- return from interrupt
-
-Some ports have the special routine ``_ISR_Dispatch`` because
-the CPU has a special "interrupt mode" and RTEMS must switch back
-to the task stack and/or non-interrupt mode before invoking``_Thread_Dispatch``. For example, consider the MC68020 where
-upon return from the outermost interrupt, the CPU must switch
-from the interrupt stack to the master stack before invoking``_Thread_Dispatch``. ``_ISR_Dispatch`` is the special port
-specific wrapper for ``_Thread_Dispatch`` used in this case.
-
-ISR Invoked with Frame Pointer
-------------------------------
-
-Does the RTEMS invoke the user’s ISR with the vector number and a pointer
-to the saved interrupt frame (1) or just the vector number (0)?
-.. code:: c
-
- #define CPU_ISR_PASSES_FRAME_POINTER 0
-
-NOTE: It is desirable to include a pointer to the interrupt stack frame as
-an argument to the interrupt service routine. Eventually, it would be
-nice if all ports included this parameter.
-
-Pointer to _Thread_Dispatch Routine
------------------------------------
-
-With some compilation systems, it is difficult if not impossible to call a
-high-level language routine from assembly language. This is especially
-true of commercial Ada compilers and name mangling C++ ones. This
-variable can be optionally defined by the CPU porter and contains the
-address of the routine _Thread_Dispatch. This can make it easier to
-invoke that routine at the end of the interrupt sequence (if a dispatch is
-necessary).
-.. code:: c
-
- void (\*_CPU_Thread_dispatch_pointer)();
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Task Context Management
-#######################
-
-Introduction
-============
-
-XXX
-
-Task Stacks
-===========
-
-XXX
-
-Direction of Stack Growth
--------------------------
-
-The CPU_STACK_GROWS_UP macro is set based upon the answer to the following
-question: Does the stack grow up (toward higher addresses) or down (toward
-lower addresses)? If the stack grows upward in memory, then this macro
-should be set to TRUE. Otherwise, it should be set to FALSE to indicate
-that the stack grows downward toward smaller addresses.
-
-The following illustrates how the CPU_STACK_GROWS_UP macro is set:
-.. code:: c
-
- #define CPU_STACK_GROWS_UP TRUE
-
-Minimum Task Stack Size
------------------------
-
-The CPU_STACK_MINIMUM_SIZE macro should be set to the minimum size of each
-task stack. This size is specified as the number of bytes. This minimum
-stack size should be large enough to run all RTEMS tests. The minimum
-stack size is chosen such that a "reasonable" small application should not
-have any problems. Choosing a minimum stack size that is too small will
-result in the RTEMS tests "blowing" their stack and not executing
-properly.
-
-There are many reasons a task could require a stack size larger than the
-minimum. For example, a task could have a very deep call path or declare
-large data structures on the stack. Tasks which utilize C++ exceptions
-tend to require larger stacks as do Ada tasks.
-
-The following illustrates setting the minimum stack size to 4 kilobytes
-per task.
-.. code:: c
-
- #define CPU_STACK_MINIMUM_SIZE (1024*4)
-
-Stack Alignment Requirements
-----------------------------
-
-The CPU_STACK_ALIGNMENT macro is set to indicate the byte alignment
-requirement for the stack. This alignment requirement may be stricter
-than that for the data types alignment specified by CPU_ALIGNMENT. If the
-CPU_ALIGNMENT is strict enough for the stack, then this should be set to
-0.
-
-The following illustrates how the CPU_STACK_ALIGNMENT macro should be set
-when there are no special requirements:
-.. code:: c
-
- #define CPU_STACK_ALIGNMENT 0
-
-NOTE: This must be a power of 2 either 0 or greater than CPU_ALIGNMENT. \[XXX is this true?]
-
-Task Context
-============
-
-Associated with each task is a context that distinguishes it from other
-tasks in the system and logically gives it its own scratch pad area for
-computations. In addition, when an interrupt occurs some processor
-context information must be saved and restored. This is managed in RTEMS
-as three items:
-
-- Basic task level context (e.g. the Context_Control structure)
-
-- Floating point task context (e.g. Context_Control_fp structure)
-
-- Interrupt level context (e.g. the Context_Control_interrupt
- structure)
-
-The integer and floating point context structures and the routines that
-manipulate them are discussed in detail in this section, while the
-interrupt level context structure is discussed in the XXX.
-
-Additionally, if the GNU debugger gdb is to be made aware of RTEMS tasks
-for this CPU, then care should be used in designing the context area.
-.. code:: c
-
- typedef struct {
- unsigned32 special_interrupt_register;
- } CPU_Interrupt_frame;
-
-Basic Context Data Structure
-----------------------------
-
-The Context_Control data structure contains the basic integer context of a
-task. In addition, this context area contains stack and frame pointers,
-processor status register(s), and any other registers that are normally
-altered by compiler generated code. In addition, this context must
-contain the processor interrupt level since the processor interrupt level
-is maintained on a per-task basis. This is necessary to support the
-interrupt level portion of the task mode as provided by the Classic RTEMS
-API.
-
-On some processors, it is cost-effective to save only the callee preserved
-registers during a task context switch. This means that the ISR code
-needs to save those registers which do not persist across function calls.
-It is not mandatory to make this distinctions between the caller/callee
-saves registers for the purpose of minimizing context saved during task
-switch and on interrupts. If the cost of saving extra registers is
-minimal, simplicity is the choice. Save the same context on interrupt
-entry as for tasks in this case.
-
-The Context_Control data structure should be defined such that the order
-of elements results in the simplest, most efficient implementation of XXX.
-A typical implementation starts with a definition such as the following:
-.. code:: c
-
- typedef struct {
- unsigned32 some_integer_register;
- unsigned32 another_integer_register;
- unsigned32 some_system_register;
- } Context_Control;
-
-Initializing a Context
-----------------------
-
-The _CPU_Context_Initialize routine initializes the context to a state
-suitable for starting a task after a context restore operation.
-Generally, this involves:
-
-- setting a starting address,
-
-- preparing the stack,
-
-- preparing the stack and frame pointers,
-
-- setting the proper interrupt level in the context, and
-
-- initializing the floating point context
-
-This routine generally does not set any unnecessary register in the
-context. The state of the "general data" registers is undefined at task
-start time. The _CPU_Context_initialize routine is prototyped as follows:
-.. code:: c
-
- void _CPU_Context_Initialize(
- Context_Control \*_the_context,
- void \*_stack_base,
- unsigned32 _size,
- unsigned32 _isr,
- void \*_entry_point,
- unsigned32 _is_fp
- );
-
-The ``is_fp`` parameter is TRUE if the thread is to be a floating point
-thread. This is typically only used on CPUs where the FPU may be easily
-disabled by software such as on the SPARC where the PSR contains an enable
-FPU bit. The use of an FPU enable bit allows RTEMS to ensure that a
-non-floating point task is unable to access the FPU. This guarantees that
-a deferred floating point context switch is safe.
-
-The ``_stack_base`` parameter is the base address of the memory area
-allocated for use as the task stack. It is critical to understand that``_stack_base`` may not be the starting stack pointer for this task.
-On CPU families where the stack grows from high addresses to lower ones,
-(i.e. ``CPU_STACK_GROWS_UP`` is FALSE) the starting stack point
-will be near the end of the stack memory area or close to``_stack_base`` + ``_size``. Even on CPU families where the stack
-grows from low to higher addresses, there may be some required
-outermost stack frame that must be put at the address ``_stack_base``.
-
-The ``_size`` parameter is the requested size in bytes of the stack for
-this task. It is assumed that the memory area ``_stack_base``
-is of this size.
-
-XXX explain other parameters and check prototype
-
-Performing a Context Switch
----------------------------
-
-The _CPU_Context_switch performs a normal non-FP context switch from the
-context of the current executing thread to the context of the heir thread.
-.. code:: c
-
- void _CPU_Context_switch(
- Context_Control \*run,
- Context_Control \*heir
- );
-
-This routine begins by saving the current state of the
-CPU (i.e. the context) in the context area at ``run``.
-Then the routine should load the CPU context pointed to
-by ``heir``. Loading the new context will cause a
-branch to its task code, so the task that invoked``_CPU_Context_switch`` will not run for a while.
-When, eventually, a context switch is made to load
-context from ``*run`` again, this task will resume
-and ``_CPU_Context_switch`` will return to its caller.
-
-Care should be exercise when writing this routine. All
-registers assumed to be preserved across subroutine calls
-must be preserved. These registers may be saved in
-the task’s context area or on its stack. However, the
-stack pointer and address to resume executing the task
-at must be included in the context (normally the subroutine
-return address to the caller of ``_Thread_Dispatch``.
-The decision of where to store the task’s context is based
-on numerous factors including the capabilities of
-the CPU architecture itself and simplicity as well
-as external considerations such as debuggers wishing
-to examine a task’s context. In this case, it is
-often simpler to save all data in the context area.
-
-Also there may be special considerations
-when loading the stack pointers or interrupt level of the
-incoming task. Independent of CPU specific considerations,
-if some context is saved on the task stack, then the porter
-must ensure that the stack pointer is adjusted *BEFORE*
-to make room for this context information before the
-information is written. Otherwise, an interrupt could
-occur writing over the context data. The following is
-an example of an *INCORRECT* sequence:
-.. code:: c
-
- save part of context beyond current top of stack
- interrupt pushes context -- overwriting written context
- interrupt returns
- adjust stack pointer
-
-Restoring a Context
--------------------
-
-The _CPU_Context_restore routine is generally used only to restart the
-currently executing thread (i.e. self) in an efficient manner. In many
-ports, it can simply be a label in _CPU_Context_switch. It may be
-unnecessary to reload some registers.
-.. code:: c
-
- void _CPU_Context_restore(
- Context_Control \*new_context
- );
-
-Restarting the Currently Executing Task
----------------------------------------
-
-The _CPU_Context_Restart_self is responsible for somehow restarting the
-currently executing task. If you are lucky when porting RTEMS, then all
-that is necessary is restoring the context. Otherwise, there will need to
-be a routine that does something special in this case. Performing a
-_CPU_Context_Restore on the currently executing task after reinitializing
-that context should work on most ports. It will not work if restarting
-self conflicts with the stack frame assumptions of restoring a context.
-
-The following is an implementation of _CPU_Context_Restart_self that can
-be used when no special handling is required for this case.
-.. code:: c
-
- #define _CPU_Context_Restart_self( _the_context ) \\
- _CPU_Context_restore( (_the_context) )
-
-XXX find a port which does not do it this way and include it here
-
-Floating Point Context
-======================
-
-CPU_HAS_FPU Macro Definition
-----------------------------
-
-The CPU_HAS_FPU macro is set based on the answer to the question: Does the
-CPU have hardware floating point? If the CPU has an FPU, then this should
-be set to TRUE. Otherwise, it should be set to FALSE. The primary
-implication of setting this macro to TRUE is that it indicates that tasks
-may have floating point contexts. In the Classic API, this means that the
-RTEMS_FLOATING_POINT task attribute specified as part of rtems_task_create
-is supported on this CPU. If CPU_HAS_FPU is set to FALSE, then no tasks
-or threads may be floating point and the RTEMS_FLOATING_POINT task
-attribute is ignored. On an API such as POSIX where all threads
-implicitly have a floating point context, then the setting of this macro
-determines whether every POSIX thread has a floating point context.
-
-The following example illustrates how the CPU_HARDWARE_FP (XXX macro name
-is varying) macro is set based on the CPU family dependent macro.
-.. code:: c
-
- #if ( THIS_CPU_FAMILY_HAS_FPU == 1 ) /* where THIS_CPU_FAMILY \*/
- /* might be M68K \*/
- #define CPU_HARDWARE_FP TRUE
- #else
- #define CPU_HARDWARE_FP FALSE
- #endif
-
-The macro name THIS_CPU_FAMILY_HAS_FPU should be made CPU specific. It
-indicates whether or not this CPU model has FP support. For example, the
-definition of the i386ex and i386sx CPU models would set I386_HAS_FPU to
-FALSE to indicate that these CPU models are i386’s without an i387 and
-wish to leave floating point support out of RTEMS when built for the
-i386_nofp processor model. On a CPU with a built-in FPU like the i486,
-this would be defined as TRUE.
-
-On some processor families, the setting of the THIS_CPU_FAMILY_HAS_FPU
-macro may be derived from compiler predefinitions. This can be used when
-the compiler distinguishes the individual CPU models for this CPU family
-as distinctly as RTEMS requires. Often RTEMS needs to need more about the
-CPU model than the compiler because of differences at the system level
-such as caching, interrupt structure.
-
-CPU_ALL_TASKS_ARE_FP Macro Setting
-----------------------------------
-
-The CPU_ALL_TASKS_ARE_FP macro is set to TRUE or FALSE based upon the
-answer to the following question: Are all tasks RTEMS_FLOATING_POINT tasks
-implicitly? If this macro is set TRUE, then all tasks and threads are
-assumed to have a floating point context. In the Classic API, this is
-equivalent to setting the RTEMS_FLOATING_POINT task attribute on all
-rtems_task_create calls. If the CPU_ALL_TASKS_ARE_FP macro is set to
-FALSE, then the RTEMS_FLOATING_POINT task attribute in the Classic API is
-honored.
-
-The rationale for this macro is that if a function that an application
-developer would not think utilize the FP unit DOES, then one can not
-easily predict which tasks will use the FP hardware. In this case, this
-option should be TRUE. So far, the only CPU families for which this macro
-has been to TRUE are the HP PA-RISC and PowerPC. For the HP PA-RISC, the
-HP C compiler and gcc both implicitly use the floating point registers to
-perform integer multiplies. For the PowerPC, this feature macro is set to
-TRUE because the printf routine saves a floating point register whether or
-not a floating point number is actually printed. If the newlib
-implementation of printf were restructured to avoid this, then the PowerPC
-port would not have to have this option set to TRUE.
-
-The following example illustrates how the CPU_ALL_TASKS_ARE_FP is set on
-the PowerPC. On this CPU family, this macro is set to TRUE if the CPU
-model has hardware floating point.
-.. code:: c
-
- #if (CPU_HARDWARE_FP == TRUE)
- #define CPU_ALL_TASKS_ARE_FP TRUE
- #else
- #define CPU_ALL_TASKS_ARE_FP FALSE
- #endif
-
-NOTE: If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
-
-CPU_USE_DEFERRED_FP_SWITCH Macro Setting
-----------------------------------------
-
-The CPU_USE_DEFERRED_FP_SWITCH macro is set based upon the answer to the
-following question: Should the saving of the floating point registers be
-deferred until a context switch is made to another different floating
-point task? If the floating point context will not be stored until
-necessary, then this macro should be set to TRUE. When set to TRUE, the
-floating point context of a task will remain in the floating point
-registers and not disturbed until another floating point task is switched
-to.
-
-If the CPU_USE_DEFERRED_FP_SWITCH is set to FALSE, then the floating point
-context is saved each time a floating point task is switched out and
-restored when the next floating point task is restored. The state of the
-floating point registers between those two operations is not specified.
-
-There are a couple of known cases where the port should not defer saving
-the floating point context. The first case is when the compiler generates
-instructions that use the FPU when floating point is not actually used.
-This occurs on the HP PA-RISC for example when an integer multiply is
-performed. On the PowerPC, the printf routine includes a save of a
-floating point register to support printing floating point numbers even if
-the path that actually prints the floating point number is not invoked.
-In both of these cases, deferred floating point context switches can not
-be used. If the floating point context has to be saved as part of
-interrupt dispatching, then it may also be necessary to disable deferred
-context switches.
-
-Setting this flag to TRUE results in using a different algorithm for
-deciding when to save and restore the floating point context. The
-deferred FP switch algorithm minimizes the number of times the FP context
-is saved and restored. The FP context is not saved until a context switch
-is made to another, different FP task. Thus in a system with only one FP
-task, the FP context will never be saved or restored.
-
-The following illustrates setting the CPU_USE_DEFERRED_FP_SWITCH macro on
-a processor family such as the M68K or i386 which can use deferred
-floating point context switches.
-.. code:: c
-
- #define CPU_USE_DEFERRED_FP_SWITCH TRUE
-
-Note that currently, when in SMP configuration, deferred floating point
-context switching is unavailable.
-
-Floating Point Context Data Structure
--------------------------------------
-
-The Context_Control_fp contains the per task information for the floating
-point unit. The organization of this structure may be a list of floating
-point registers along with any floating point control and status registers
-or it simply consist of an array of a fixed number of bytes. Defining the
-floating point context area as an array of bytes is done when the floating
-point context is dumped by a "FP save context" type instruction and the
-format is either not completely defined by the CPU documentation or the
-format is not critical for the implementation of the floating point
-context switch routines. In this case, there is no need to figure out the
-exact format – only the size. Of course, although this is enough
-information for RTEMS, it is probably not enough for a debugger such as
-gdb. But that is another problem.
-.. code:: c
-
- typedef struct {
- double some_float_register;
- } Context_Control_fp;
-
-On some CPUs with hardware floating point support, the Context_Control_fp
-structure will not be used.
-
-Size of Floating Point Context Macro
-------------------------------------
-
-The CPU_CONTEXT_FP_SIZE macro is set to the size of the floating point
-context area. On some CPUs this will not be a "sizeof" because the format
-of the floating point area is not defined – only the size is. This is
-usually on CPUs with a "floating point save context" instruction. In
-general, though it is easier to define the structure as a "sizeof"
-operation and define the Context_Control_fp structure to be an area of
-bytes of the required size in this case.
-.. code:: c
-
- #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
-
-Start of Floating Point Context Area Macro
-------------------------------------------
-
-The _CPU_Context_Fp_start macro is used in the XXX routine and allows the initial pointer into a floating point context area (used to save the floating point context) to be at an arbitrary place in the floating point context area. This is necessary because some FP units are designed to have their context saved as a stack which grows into lower addresses. Other FP units can be saved by simply moving registers into offsets from the base of the context area. Finally some FP units provide a "dump context" instruction which could fill in from high to low or low to high based on the whim of the CPU designers. Regardless, the address at which that floating point context area pointer should start within the actual floating point context area varies between ports and this macro provides a clean way of addressing this.
-
-This is a common implementation of the _CPU_Context_Fp_start routine which
-is suitable for many processors. In particular, RISC processors tend to
-use this implementation since the floating point context is saved as a
-sequence of store operations.
-.. code:: c
-
- #define _CPU_Context_Fp_start( _base, _offset ) \\
- ( (void \*) _Addresses_Add_offset( (_base), (_offset) ) )
-
-In contrast, the m68k treats the floating point context area as a stack
-which grows downward in memory. Thus the following implementation of
-_CPU_Context_Fp_start is used in that port:
-
-.. code:: c
-
- XXX insert m68k version here
-
-Initializing a Floating Point Context
--------------------------------------
-
-The _CPU_Context_Initialize_fp routine initializes the floating point
-context area passed to it to. There are a few standard ways in which to
-initialize the floating point context. The simplest, and least
-deterministic behaviorally, is to do nothing. This leaves the FPU in a
-random state and is generally not a suitable way to implement this
-routine. The second common implementation is to place a "null FP status
-word" into some status/control register in the FPU. This mechanism is
-simple and works on many FPUs. Another common way is to initialize the
-FPU to a known state during _CPU_Initialize and save the context (using
-_CPU_Context_save_fp_context) into the special floating point context
-_CPU_Null_fp_context. Then all that is required to initialize a floating
-point context is to copy _CPU_Null_fp_context to the destination floating
-point context passed to it. The following example implementation shows
-how to accomplish this:
-.. code:: c
-
- #define _CPU_Context_Initialize_fp( _destination ) \\
- { \\
- \*((Context_Control_fp \*) \*((void \**) _destination)) = \\
- _CPU_Null_fp_context; \\
- }
-
-The _CPU_Null_fp_context is optional. A port need only include this variable when it uses the above mechanism to initialize a floating point context. This is typically done on CPUs where it is difficult to generate an "uninitialized" FP context. If the port requires this variable, then it is declared as follows:
-.. code:: c
-
- Context_Control_fp _CPU_Null_fp_context;
-
-Saving a Floating Point Context
--------------------------------
-
-The _CPU_Context_save_fp_context routine is responsible for saving the FP
-context at \*fp_context_ptr. If the point to load the FP context from is
-changed then the pointer is modified by this routine.
-
-Sometimes a macro implementation of this is in cpu.h which dereferences
-the \** and a similarly named routine in this file is passed something like
-a (Context_Control_fp \*). The general rule on making this decision is to
-avoid writing assembly language.
-.. code:: c
-
- void _CPU_Context_save_fp(
- void \**fp_context_ptr
- )
-
-Restoring a Floating Point Context
-----------------------------------
-
-The _CPU_Context_restore_fp_context is responsible for restoring the FP
-context at \*fp_context_ptr. If the point to load the FP context from is
-changed then the pointer is modified by this routine.
-
-Sometimes a macro implementation of this is in cpu.h which dereferences
-the \** and a similarly named routine in this file is passed something like
-a (Context_Control_fp \*). The general rule on making this decision is to
-avoid writing assembly language.
-.. code:: c
-
- void _CPU_Context_restore_fp(
- void \**fp_context_ptr
- );
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-IDLE Thread
-###########
-
-Does Idle Thread Have a Floating Point Context?
-===============================================
-
-The setting of the macro CPU_IDLE_TASK_IS_FP is based on the answer to the
-question: Should the IDLE task have a floating point context? If the
-answer to this question is TRUE, then the IDLE task has a floating point
-context associated. This is equivalent to creating a task in the Classic
-API (using rtems_task_create) as a RTEMS_FLOATING_POINT task. If
-CPU_IDLE_TASK_IS_FP is set to TRUE, then a floating point context switch
-occurs when the IDLE task is switched in and out. This adds to the
-execution overhead of the system but is necessary on some ports.
-
-If FALSE, then the IDLE task does not have a floating point context.
-
-NOTE: Setting CPU_IDLE_TASK_IS_FP to TRUE negatively impacts the time
-required to preempt the IDLE task from an interrupt because the floating
-point context must be saved as part of the preemption.
-
-The following illustrates how to set this macro:
-.. code:: c
-
- #define CPU_IDLE_TASK_IS_FP FALSE
-
-CPU Dependent Idle Thread Body
-==============================
-
-CPU_PROVIDES_IDLE_THREAD_BODY Macro Setting
--------------------------------------------
-
-The CPU_PROVIDES_IDLE_THREAD_BODY macro setting is based upon the answer
-to the question: Does this port provide a CPU dependent IDLE task
-implementation? If the answer to this question is yes, then the
-CPU_PROVIDES_IDLE_THREAD_BODY macro should be set to TRUE, and the routine
-_CPU_Thread_Idle_body must be provided. This routine overrides the
-default IDLE thread body of _Thread_Idle_body. If the
-CPU_PROVIDES_IDLE_THREAD_BODY macro is set to FALSE, then the generic
-_Thread_Idle_body is the default IDLE thread body for this port.
-Regardless of whether or not a CPU dependent IDLE thread implementation is
-provided, the BSP can still override it.
-
-This is intended to allow for supporting processors which have a low power
-or idle mode. When the IDLE thread is executed, then the CPU can be
-powered down when the processor is idle.
-
-The order of precedence for selecting the IDLE thread body is:
-
-# BSP provided
-
-# CPU dependent (if provided)
-
-# generic (if no BSP and no CPU dependent)
-
-The following illustrates setting the CPU_PROVIDES_IDLE_THREAD_BODY macro:
-.. code:: c
-
- #define CPU_PROVIDES_IDLE_THREAD_BODY TRUE
-
-Implementation details of a CPU model specific IDLE thread body are in the
-next section.
-
-Idle Thread Body
-----------------
-
-The _CPU_Thread_Idle_body routine only needs to be provided if the porter
-wishes to include a CPU dependent IDLE thread body. If the port includes
-a CPU dependent implementation of the IDLE thread body, then the
-CPU_PROVIDES_IDLE_THREAD_BODY macro should be defined to TRUE. This
-routine is prototyped as follows:
-.. code:: c
-
- void \*_CPU_Thread_Idle_body( uintptr_t );
-
-As mentioned above, RTEMS does not require that a CPU dependent IDLE
-thread body be provided as part of the port. If
-CPU_PROVIDES_IDLE_THREAD_BODY is defined to FALSE, then the CPU
-independent algorithm is used. This algorithm consists of a "branch to
-self" which is implemented in a routine as follows.
-.. code:: c
-
- void \*_Thread_Idle_body( uintptr_t ignored )
- {
- while( 1 ) ;
- }
-
-If the CPU dependent IDLE thread body is implementation centers upon using
-a "halt", "idle", or "shutdown" instruction, then don’t forget to put it
-in an infinite loop as the CPU will have to reexecute this instruction
-each time the IDLE thread is dispatched.
-.. code:: c
-
- void \*_CPU_Thread_Idle_body( uintptr_t ignored )
- {
- for( ; ; )
- /* insert your "halt" instruction here \*/ ;
- }
-
-Be warned. Some processors with onboard DMA have been known to stop the
-DMA if the CPU were put in IDLE mode. This might also be a problem with
-other on-chip peripherals. So use this hook with caution.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Priority Bitmap Manipulation
-############################
-
-Introduction
-============
-
-The RTEMS chain of ready tasks is implemented as an array of FIFOs with
-each priority having its own FIFO. This makes it very efficient to
-determine the first and last ready task at each priority. In addition,
-blocking a task only requires appending the task to the end of the FIFO
-for its priority rather than a lengthy search down a single chain of all
-ready tasks. This works extremely well except for one problem. When the
-currently executing task blocks, there may be no easy way to determine
-what is the next most important ready task. If the blocking task was the
-only ready task at its priority, then RTEMS must search all of the FIFOs
-in the ready chain to determine the highest priority with a ready task.
-
-RTEMS uses a bitmap array to efficiently solve this problem. The state of
-each bit in the priority map bit array indicates whether or not there is a
-ready task at that priority. The bit array can be efficiently searched to
-determine the highest priority ready task. This family of data type and
-routines is used to maintain and search the bit map array.
-
-When manipulating the bitmap array, RTEMS internally divides the
-8 bits of the task priority into "major" and "minor" components.
-The most significant 4 bits are the major component, while the least
-significant are the minor component. The major component of a priority
-value is used to determine which 16-bit wide entry in the``_Priority_Bit_map`` array is associated with this priority.
-Each element in the ``_Priority_Bit_map`` array has a bit
-in the ``_Priority_Major_bit_map`` associated with it.
-That bit is cleared when all of the bits in a particular``_Priority_Bit_map`` array entry are zero.
-
-The minor component of a priority is used to determine
-specifically which bit in ``_Priority_Bit_map[major]``
-indicates whether or not there is a ready to execute task
-at the priority.
-
-_Priority_bit_map_Control Type
-==============================
-
-The ``_Priority_Bit_map_Control`` type is the fundamental data type of the
-priority bit map array used to determine which priorities have ready
-tasks. This type may be either 16 or 32 bits wide although only the 16
-least significant bits will be used. The data type is based upon what is
-the most efficient type for this CPU to manipulate. For example, some
-CPUs have bit scan instructions that only operate on a particular size of
-data. In this case, this type will probably be defined to work with this
-instruction.
-
-Find First Bit Routine
-======================
-
-The _CPU_Bitfield_Find_first_bit routine sets _output to the bit number of
-the first bit set in ``_value``. ``_value`` is of CPU dependent type``Priority_bit_map_Control``. A stub version of this routine is as follows:
-.. code:: c
-
- #define _CPU_Bitfield_Find_first_bit( _value, _output ) \\
- { \\
- (_output) = 0; /* do something to prevent warnings \*/ \\
- }
-
-There are a number of variables in using a "find first bit" type
-instruction.
-
-# What happens when run on a value of zero?
-
-# Bits may be numbered from MSB to LSB or vice-versa.
-
-# The numbering may be zero or one based.
-
-# The "find first bit" instruction may search from MSB or LSB.
-
-RTEMS guarantees that (1) will never happen so it is not a concern.
-Cases (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
-_CPU_Priority_bits_index(). These three form a set of routines which must
-logically operate together. Bits in the ``_value`` are set and cleared based
-on masks built by CPU_Priority_mask(). The basic major and minor values
-calculated by _Priority_Major() and _Priority_Minor() are "massaged" by
-_CPU_Priority_bits_index() to properly range between the values returned
-by the "find first bit" instruction. This makes it possible for
-_Priority_Get_highest() to calculate the major and directly index into the
-minor table. This mapping is necessary to ensure that 0 (a high priority
-major/minor) is the first bit found.
-
-This entire "find first bit" and mapping process depends heavily on the
-manner in which a priority is broken into a major and minor components
-with the major being the 4 MSB of a priority and minor the 4 LSB. Thus (0
-<< 4) + 0 corresponds to priority 0 – the highest priority. And (15 <<
-4) + 14 corresponds to priority 254 – the next to the lowest priority.
-
-If your CPU does not have a "find first bit" instruction, then there are
-ways to make do without it. Here are a handful of ways to implement this
-in software:
-
-- a series of 16 bit test instructions
-
-- a "binary search using if’s"
-
-- the following algorithm based upon a 16 entry lookup table. In this pseudo-code, bit_set_table[16] has values which indicate the first bit set:
-
- .. code:: c
-
- _number = 0 if _value > 0x00ff
- _value >>=8
- _number = 8;
- if _value > 0x0000f
- _value >=8
- _number += 4
- _number += bit_set_table[ _value ]
-
-The following illustrates how the CPU_USE_GENERIC_BITFIELD_CODE macro may
-be so the port can use the generic implementation of this bitfield code.
-This can be used temporarily during the porting process to avoid writing
-these routines until the end. This results in a functional although lower
-performance port. This is perfectly acceptable during development and
-testing phases.
-.. code:: c
-
- #define CPU_USE_GENERIC_BITFIELD_CODE TRUE
- #define CPU_USE_GENERIC_BITFIELD_DATA TRUE
-
-Eventually, CPU specific implementations of these routines are usually
-written since they dramatically impact the performance of blocking
-operations. However they may take advantage of instructions which are not
-available on all models in the CPU family. In this case, one might find
-something like this stub example did:
-.. code:: c
-
- #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
- #define _CPU_Bitfield_Find_first_bit( _value, _output ) \\
- { \\
- (_output) = 0; /* do something to prevent warnings \*/ \\
- }
- #endif
-
-Build Bit Field Mask
-====================
-
-The _CPU_Priority_Mask routine builds the mask that corresponds to the bit
-fields searched by _CPU_Bitfield_Find_first_bit(). See the discussion of
-that routine for more details.
-
-The following is a typical implementation when the
-_CPU_Bitfield_Find_first_bit searches for the most significant bit set:
-.. code:: c
-
- #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
- #define _CPU_Priority_Mask( _bit_number ) \\
- ( 1 << (_bit_number) )
- #endif
-
-Bit Scan Support
-================
-
-The ``_CPU_Priority_bits_index`` routine translates the bit numbers
-returned by ``_CPU_Bitfield_Find_first_bit()`` into something
-suitable for use as a major or minor component of a priority.
-The find first bit routine may number the bits in a
-way that is difficult to map into the major and minor components
-of the priority. For example, when finding the first bit set in
-the value 0x8000, a CPU may indicate that bit 15 or 16 is set
-based on whether the least significant bit is "zero" or "one".
-Similarly, a CPU may only scan 32-bit values and consider the
-most significant bit to be bit zero or one. In this case, this
-would be bit 16 or 17.
-
-This routine allows that unwieldy form to be converted
-into a normalized form that is easier to process and use
-as an index.
-.. code:: c
-
- #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
- #define _CPU_Priority_bits_index( _priority ) \\
- (_priority)
- #endif
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Code Tuning Parameters
-######################
-
-Inline Thread_Enable_dispatch
-=============================
-
-Should the calls to _Thread_Enable_dispatch be inlined?
-
-If TRUE, then they are inlined.
-
-If FALSE, then a subroutine call is made.
-
-Basically this is an example of the classic trade-off of size versus
-speed. Inlining the call (TRUE) typically increases the size of RTEMS
-while speeding up the enabling of dispatching.
-
-[NOTE: In general, the _Thread_Dispatch_disable_level will only be 0 or 1
-unless you are in an interrupt handler and that interrupt handler invokes
-the executive.] When not inlined something calls _Thread_Enable_dispatch
-which in turns calls _Thread_Dispatch. If the enable dispatch is inlined,
-then one subroutine call is avoided entirely.]
-.. code:: c
-
- #define CPU_INLINE_ENABLE_DISPATCH FALSE
-
-Inline Thread_queue_Enqueue_priority
-====================================
-
-Should the body of the search loops in _Thread_queue_Enqueue_priority be
-unrolled one time? In unrolled each iteration of the loop examines two
-"nodes" on the chain being searched. Otherwise, only one node is examined
-per iteration.
-
-If TRUE, then the loops are unrolled.
-
-If FALSE, then the loops are not unrolled.
-
-The primary factor in making this decision is the cost of disabling and
-enabling interrupts (_ISR_Flash) versus the cost of rest of the body of
-the loop. On some CPUs, the flash is more expensive than one iteration of
-the loop body. In this case, it might be desirable to unroll the loop.
-It is important to note that on some CPUs, this code is the longest
-interrupt disable period in RTEMS. So it is necessary to strike a balance
-when setting this parameter.
-.. code:: c
-
- #define CPU_UNROLL_ENQUEUE_PRIORITY TRUE
-
-Structure Alignment Optimization
-================================
-
-The following macro may be defined to the attribute setting used to force
-alignment of critical RTEMS structures. On some processors it may make
-sense to have these aligned on tighter boundaries than the minimum
-requirements of the compiler in order to have as much of the critical data
-area as possible in a cache line. This ensures that the first access of
-an element in that structure fetches most, if not all, of the data
-structure and places it in the data cache. Modern CPUs often have cache
-lines of at least 16 bytes and thus a single access implicitly fetches
-some surrounding data and places that unreferenced data in the cache.
-Taking advantage of this allows RTEMS to essentially prefetch critical
-data elements.
-
-The placement of this macro in the declaration of the variables is based
-on the syntactically requirements of the GNU C "__attribute__" extension.
-For another toolset, the placement of this macro could be incorrect. For
-example with GNU C, use the following definition of
-CPU_STRUCTURE_ALIGNMENT to force a structures to a 32 byte boundary.
-
-#define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32)))
-
-To benefit from using this, the data must be heavily used so it will stay
-in the cache and used frequently enough in the executive to justify
-turning this on. NOTE: Because of this, only the Priority Bit Map table
-currently uses this feature.
-
-The following illustrates how the CPU_STRUCTURE_ALIGNMENT is defined on
-ports which require no special alignment for optimized access to data
-structures:
-.. code:: c
-
- #define CPU_STRUCTURE_ALIGNMENT
-
-Data Alignment Requirements
-===========================
-
-Data Element Alignment
-----------------------
-
-The CPU_ALIGNMENT macro should be set to the CPU’s worst alignment
-requirement for data types on a byte boundary. This is typically the
-alignment requirement for a C double. This alignment does not take into
-account the requirements for the stack.
-
-The following sets the CPU_ALIGNMENT macro to 8 which indicates that there
-is a basic C data type for this port which much be aligned to an 8 byte
-boundary.
-.. code:: c
-
- #define CPU_ALIGNMENT 8
-
-Heap Element Alignment
-----------------------
-
-The CPU_HEAP_ALIGNMENT macro is set to indicate the byte alignment
-requirement for data allocated by the RTEMS Code Heap Handler. This
-alignment requirement may be stricter than that for the data types
-alignment specified by CPU_ALIGNMENT. It is common for the heap to follow
-the same alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is
-strict enough for the heap, then this should be set to CPU_ALIGNMENT. This
-macro is necessary to ensure that allocated memory is properly aligned for
-use by high level language routines.
-
-The following example illustrates how the CPU_HEAP_ALIGNMENT macro is set
-when the required alignment for elements from the heap is the same as the
-basic CPU alignment requirements.
-.. code:: c
-
- #define CPU_HEAP_ALIGNMENT CPU_ALIGNMENT
-
-NOTE: This does not have to be a power of 2. It does have to be greater
-or equal to than CPU_ALIGNMENT.
-
-Partition Element Alignment
----------------------------
-
-The CPU_PARTITION_ALIGNMENT macro is set to indicate the byte alignment
-requirement for memory buffers allocated by the RTEMS Partition Manager
-that is part of the Classic API. This alignment requirement may be
-stricter than that for the data types alignment specified by
-CPU_ALIGNMENT. It is common for the partition to follow the same
-alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict
-enough for the partition, then this should be set to CPU_ALIGNMENT. This
-macro is necessary to ensure that allocated memory is properly aligned for
-use by high level language routines.
-
-The following example illustrates how the CPU_PARTITION_ALIGNMENT macro is
-set when the required alignment for elements from the RTEMS Partition
-Manager is the same as the basic CPU alignment requirements.
-
-.. code:: c
-
- #define CPU_PARTITION_ALIGNMENT CPU_ALIGNMENT
-
-NOTE: This does not have to be a power of 2. It does have to be greater
-or equal to than CPU_ALIGNMENT.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Miscellaneous
-#############
-
-Fatal Error Default Handler
-===========================
-
-The ``_CPU_Fatal_halt`` routine is the default fatal error handler. This
-routine copies _error into a known place – typically a stack location or
-a register, optionally disables interrupts, and halts/stops the CPU. It
-is prototyped as follows and is often implemented as a macro:
-.. code:: c
-
- void _CPU_Fatal_halt(
- unsigned32 _error
- );
-
-CPU Context Validation
-======================
-
-The test case ``sptests/spcontext01`` ensures that the context switching and
-interrupt processing works. This test uses two support functions provided by
-the CPU port. These two functions are only used for this test and have no
-other purpose.
-.. code:: c
-
- void _CPU_Context_volatile_clobber( uintptr_t pattern );
- void _CPU_Context_validate( uintptr_t pattern );
-
-The ``_CPU_Context_volatile_clobber()`` function clobbers all volatile
-registers with values derived from the pattern parameter. This makes sure that
-the interrupt prologue code restores all volatile registers of the interrupted
-context.
-
-The ``_CPU_Context_validate()`` function initializes and validates the CPU
-context with values derived from the pattern parameter. This function will not
-return if the CPU context remains consistent. In case this function returns
-the CPU port is broken. The test uses two threads which concurrently validate
-the CPU context with a different patterns for each thread. This ensures that
-the context switching code works.
-
-Processor Endianness
-====================
-
-Endianness refers to the order in which numeric values are stored in
-memory by the microprocessor. Big endian architectures store the most
-significant byte of a multi-byte numeric value in the byte with the lowest
-address. This results in the hexadecimal value 0x12345678 being stored as
-0x12345678 with 0x12 in the byte at offset zero, 0x34 in the byte at
-offset one, etc.. The Motorola M68K and numerous RISC processor families
-is big endian. Conversely, little endian architectures store the least
-significant byte of a multi-byte numeric value in the byte with the lowest
-address. This results in the hexadecimal value 0x12345678 being stored as
-0x78563412 with 0x78 in the byte at offset zero, 0x56 in the byte at
-offset one, etc.. The Intel ix86 family is little endian.
-Interestingly, some CPU models within the PowerPC and MIPS architectures
-can be switched between big and little endian modes. Most embedded
-systems use these families strictly in big endian mode.
-
-RTEMS must be informed of the byte ordering for this microprocessor family
-and, optionally, endian conversion routines may be provided as part of the
-port. Conversion between endian formats is often necessary in
-multiprocessor environments and sometimes needed when interfacing with
-peripheral controllers.
-
-Specifying Processor Endianness
--------------------------------
-
-The ``CPU_BIG_ENDIAN`` and ``CPU_LITTLE_ENDIAN`` are
-set to specify the endian
-format used by this microprocessor. These macros should not be set to the
-same value. The following example illustrates how these macros should be
-set on a processor family that is big endian.
-.. code:: c
-
- #define CPU_BIG_ENDIAN TRUE
- #define CPU_LITTLE_ENDIAN FALSE
-
-The ``CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK`` macro is set to the amount of
-stack space above the minimum thread stack space required by the MPCI
-Receive Server Thread. This macro is needed because in a multiprocessor
-system the MPCI Receive Server Thread must be able to process all
-directives.
-.. code:: c
-
- #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
-
-Endian Swap Unsigned Integers
------------------------------
-
-The port should provide routines to swap sixteen (``CPU_swap_u16``) and
-thirty-bit (``CPU_swap_u32``) unsigned integers. These are primarily used in
-two areas of RTEMS - multiprocessing support and the network endian swap
-routines. The ``CPU_swap_u32`` routine must be implemented as a static
-routine rather than a macro because its address is taken and used
-indirectly. On the other hand, the ``CPU_swap_u16`` routine may be
-implemented as a macro.
-
-Some CPUs have special instructions that swap a 32-bit quantity in a
-single instruction (e.g. i486). It is probably best to avoid an "endian
-swapping control bit" in the CPU. One good reason is that interrupts
-would probably have to be disabled to insure that an interrupt does not
-try to access the same "chunk" with the wrong endian. Another good reason
-is that on some CPUs, the endian bit endianness for ALL fetches – both
-code and data – so the code will be fetched incorrectly.
-
-The following is an implementation of the ``CPU_swap_u32`` routine that will
-work on any CPU. It operates by breaking the unsigned thirty-two bit
-integer into four byte-wide quantities and reassemblying them.
-.. code:: c
-
- static inline unsigned int CPU_swap_u32(
- unsigned int value
- )
- {
- unsigned32 byte1, byte2, byte3, byte4, swapped;
- byte4 = (value >> 24) & 0xff;
- byte3 = (value >> 16) & 0xff;
- byte2 = (value >> 8) & 0xff;
- byte1 = value & 0xff;
- swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4;
- return( swapped );
- }
-
-Although the above implementation is portable, it is not particularly
-efficient. So if there is a better way to implement this on a particular
-CPU family or model, please do so. The efficiency of this routine has
-significant impact on the efficiency of the multiprocessing support code
-in the shared memory driver and in network applications using the ntohl()
-family of routines.
-
-Most microprocessor families have rotate instructions which can be used to
-greatly improve the ``CPU_swap_u32`` routine. The most common
-way to do this is to:
-.. code:: c
-
- swap least significant two bytes with 16-bit rotate
- swap upper and lower 16-bits
- swap most significant two bytes with 16-bit rotate
-
-Some CPUs have special instructions that swap a 32-bit quantity in a
-single instruction (e.g. i486). It is probably best to avoid an "endian
-swapping control bit" in the CPU. One good reason is that interrupts
-would probably have to be disabled to insure that an interrupt does not
-try to access the same "chunk" with the wrong endian. Another good reason
-is that on some CPUs, the endian bit endianness for ALL fetches – both
-code and data – so the code will be fetched incorrectly.
-
-Similarly, here is a portable implementation of the ``CPU_swap_u16``
-routine. Just as with the ``CPU_swap_u32`` routine, the porter
-should provide a better implementation if possible.
-.. code:: c
-
- #define CPU_swap_u16( value ) \\
- (((value&0xff) << 8) | ((value >> 8)&0xff))
-
-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/posix_users/posix_users_old_reference_only.rst b/posix_users/posix_users_old_reference_only.rst
deleted file mode 100644
index 0ac495c..0000000
--- a/posix_users/posix_users_old_reference_only.rst
+++ /dev/null
@@ -1,11612 +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 POSIX API 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: variable substitution info:
-
-.. COMMENT: Note: At the moment we do not document the Ada interface but by building
-
-.. COMMENT: in the infrastructure Florist support should be simple to add.
-
-.. 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 POSIX API User's Guide
-
-============================
-RTEMS POSIX API 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 POSIX API User’s Guide
-############################
-
-.. COMMENT: COPYRIGHT (c) 1989-2011.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Preface
-#######
-
-This is the User’s Guide for the POSIX API support
-provided in RTEMS.
-
-The functionality described in this document is based
-on the following standards:
-
-- POSIX 1003.1b-1993.
-
-- POSIX 1003.1h/D3.
-
-- Open Group Single UNIX Specification.
-
-Much of the POSIX API standard is actually implemented in the
-Cygnus Newlib ANSI C Library. Please refer to documentation on
-Newlib for more information on the functionality it supplies.
-
-This manual is still under construction and improvements
-are welcomed from users.
-
-Acknowledgements
-================
-
-.. COMMENT: COPYRIGHT (c) 1988-2009.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The RTEMS Project has been granted permission from The Open Group
-
-.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents
-
-.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
-
-.. COMMENT: We have to include a specific acknowledgement paragraph in these
-
-.. COMMENT: documents (e.g. preface or copyright page) and another slightly
-
-.. COMMENT: different paragraph for each manual page that excerpts and uses
-
-.. COMMENT: text from the standards.
-
-.. COMMENT: This file should help ensure that the paragraphs are consistent
-
-.. COMMENT: and not duplicated
-
- The Institute of Electrical and Electronics Engineers, Inc and The
- Open Group, have given us permission to reprint portions of their
- documentation.
- Portions of this text are reprinted and reproduced in electronic
- form from IEEE Std 1003.1, 2004 Edition, Standard for Information
- Technology — Operating System Interface (POSIX), The Open
- Group Base Specifications Issue 6, Copyright © 2001-2004 by the
- Institute of Electrical and Electronics Engineers, Inc and The
- Open Group. In the event of any discrepancy between this version
- and the original IEEE and The Open Group Standard, the original
- IEEE and The Open Group Standard is the referee document. The
- original Standard can be obtained online athttp://www.opengroup.org/unix/online.html.
- This notice shall appear on any product containing this material.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Process Creation and Execution Manager
-######################################
-
-Introduction
-============
-
-The process creation and execution manager provides the
-functionality associated with the creation and termination
-of processes.
-
-The directives provided by the process creation and execution manager are:
-
-- ``fork`` - Create a Process
-
-- ``execl`` - Execute a File
-
-- ``execv`` - Execute a File
-
-- ``execle`` - Execute a File
-
-- ``execve`` - Execute a File
-
-- ``execlp`` - Execute a File
-
-- ``execvp`` - Execute a File
-
-- ``pthread_atfork`` - Register Fork Handlers
-
-- ``wait`` - Wait for Process Termination
-
-- ``waitpid`` - Wait for Process Termination
-
-- ``_exit`` - Terminate a Process
-
-Background
-==========
-
-POSIX process functionality can not be completely
-supported by RTEMS. This is because RTEMS provides no memory
-protection and implements a *single process, multi-threaded
-execution model*. In this light, RTEMS provides none of the
-routines that are associated with the creation of new processes.
-However, since the entire RTEMS application (e.g. executable)
-is logically a single POSIX process, RTEMS is able to provide
-implementations of many operations on processes. The rule of
-thumb is that those routines provide a meaningful result.
-For example, ``getpid()`` returns the node number.
-
-Operations
-==========
-
-The only functionality method defined by this manager which is
-supported by RTEMS is the ``_exit`` service. The
-implementation of ``_exit`` shuts the application down and
-is equivalent to invoking either ``exit`` or``rtems_shutdown_executive``.
-
-Directives
-==========
-
-This section details the process creation and execution 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.
-
-fork - Create a Process
------------------------
-.. index:: fork
-.. index:: create a process
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- int fork( void );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-execl - Execute a File
-----------------------
-.. index:: execl
-.. index:: execute a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int execl(
- const char \*path,
- const char \*arg,
- ...
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-execv - Execute a File
-----------------------
-.. index:: execv
-.. index:: execute a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int execv(
- const char \*path,
- char const \*argv[],
- ...
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-execle - Execute a File
------------------------
-.. index:: execle
-.. index:: execute a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int execle(
- const char \*path,
- const char \*arg,
- ...
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-execve - Execute a File
------------------------
-.. index:: execve
-.. index:: execute a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int execve(
- const char \*path,
- char \*const argv[],
- char \*const envp[]
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-execlp - Execute a File
------------------------
-.. index:: execlp
-.. index:: execute a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int execlp(
- const char \*file,
- const char \*arg,
- ...
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-execvp - Execute a File
------------------------
-.. index:: execvp
-.. index:: execute a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int execvp(
- const char \*file,
- char \*const argv[]
- ...
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-pthread_atfork - Register Fork Handlers
----------------------------------------
-.. index:: pthread_atfork
-.. index:: register fork handlers
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- int pthread_atfork(
- void (\*prepare)(void),
- void (\*parent)(void),
- void (\*child)(void)
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-wait - Wait for Process Termination
------------------------------------
-.. index:: wait
-.. index:: wait for process termination
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/wait.h>
- int wait(
- int \*stat_loc
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-waitpid - Wait for Process Termination
---------------------------------------
-.. index:: waitpid
-.. index:: wait for process termination
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int wait(
- pid_t pid,
- int \*stat_loc,
- int options
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- This routine is not supported by RTEMS.
-
-**DESCRIPTION:**
-
-This routine is not supported by RTEMS.
-
-**NOTES:**
-
-NONE
-
-_exit - Terminate a Process
----------------------------
-.. index:: _exit
-.. index:: terminate a process
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void _exit(
- int status
- );
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-The ``_exit()`` function terminates the calling process.
-
-**NOTES:**
-
-In RTEMS, a process is equivalent to the entire application on a single
-processor. Invoking this service terminates the application.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Signal Manager
-##############
-
-Introduction
-============
-
-The signal manager provides the functionality associated with
-the generation, delivery, and management of process-oriented
-signals.
-
-The directives provided by the signal manager are:
-
-- ``sigaddset`` - Add a Signal to a Signal Set
-
-- ``sigdelset`` - Delete a Signal from a Signal Set
-
-- ``sigfillset`` - Fill a Signal Set
-
-- ``sigismember`` - Is Signal a Member of a Signal Set
-
-- ``sigemptyset`` - Empty a Signal Set
-
-- ``sigaction`` - Examine and Change Signal Action
-
-- ``pthread_kill`` - Send a Signal to a Thread
-
-- ``sigprocmask`` - Examine and Change Process Blocked Signals
-
-- ``pthread_sigmask`` - Examine and Change Thread Blocked Signals
-
-- ``kill`` - Send a Signal to a Process
-
-- ``sigpending`` - Examine Pending Signals
-
-- ``sigsuspend`` - Wait for a Signal
-
-- ``pause`` - Suspend Process Execution
-
-- ``sigwait`` - Synchronously Accept a Signal
-
-- ``sigwaitinfo`` - Synchronously Accept a Signal
-
-- ``sigtimedwait`` - Synchronously Accept a Signal with Timeout
-
-- ``sigqueue`` - Queue a Signal to a Process
-
-- ``alarm`` - Schedule Alarm
-
-- ``ualarm`` - Schedule Alarm in Microseconds
-
-Background
-==========
-
-Signals
--------
-
-POSIX signals are an asynchronous event mechanism. Each process
-and thread has a set of signals associated with it. Individual
-signals may be enabled (e.g. unmasked) or blocked (e.g. ignored)
-on both a per-thread and process level. Signals which are
-enabled have a signal handler associated with them. When the
-signal is generated and conditions are met, then the signal
-handler is invoked in the proper process or thread context
-asynchronous relative to the logical thread of execution.
-
-If a signal has been blocked when it is generated, then it
-is queued and kept pending until the thread or process unblocks
-the signal or explicitly checks for it.
-Traditional, non-real-time POSIX signals do not queue. Thus
-if a process or thread has blocked a particular signal, then
-multiple occurrences of that signal are recorded as a
-single occurrence of that signal.
-
-.. COMMENT: TODO: SIGRTMIN and SIGRTMAX ?
-
-One can check for the set of outstanding signals that have been
-blocked. Services are provided to check for outstanding process
-or thread directed signals.
-
-Signal Delivery
----------------
-
-Signals which are directed at a thread are delivered to the specified thread.
-
-Signals which are directed at a process are delivered to a thread which
-is selected based on the following algorithm:
-
-# If the action for this signal is currently ``SIG_IGN``,
- then the signal is simply ignored.
-
-# If the currently executing thread has the signal unblocked, then
- the signal is delivered to it.
-
-# If any threads are currently blocked waiting for this signal
- (``sigwait()``), then the signal is delivered to the highest priority
- thread waiting for this signal.
-
-# If any other threads are willing to accept delivery of the signal, then
- the signal is delivered to the highest priority thread of this set. In the
- event, multiple threads of the same priority are willing to accept this
- signal, then priority is given first to ready threads, then to threads
- blocked on calls which may be interrupted, and finally to threads blocked
- on non-interruptible calls.
-
-# In the event the signal still can not be delivered, then it is left
- pending. The first thread to unblock the signal (``sigprocmask()`` or``pthread_sigprocmask()``) or to wait for this signal
- (``sigwait()``) will be the recipient of the signal.
-
-Operations
-==========
-
-Signal Set Management
----------------------
-
-Each process and each thread within that process has a set of
-individual signals and handlers associated with it. Services
-are provided to construct signal sets for the purposes of building
-signal sets – type ``sigset_t`` – that are used to
-provide arguments to the services that mask, unmask, and
-check on pending signals.
-
-Blocking Until Signal Generation
---------------------------------
-
-A thread may block until receipt of a signal. The "sigwait"
-and "pause" families of functions block until the requested
-signal is received or if using ``sigtimedwait()`` until the specified
-timeout period has elapsed.
-
-Sending a Signal
-----------------
-
-This is accomplished
-via one of a number of services that sends a signal to either a
-process or thread. Signals may be directed at a process by
-the service ``kill()`` or at a thread by the service``pthread_kill()``
-
-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.
-
-sigaddset - Add a Signal to a Signal Set
-----------------------------------------
-.. index:: sigaddset
-.. index:: add a signal to a signal set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigaddset(
- sigset_t \*set,
- int signo
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function adds the signal ``signo`` to the specified signal ``set``.
-
-**NOTES:**
-
-The set must be initialized using either ``sigemptyset`` or ``sigfillset``
-before using this function.
-
-sigdelset - Delete a Signal from a Signal Set
----------------------------------------------
-.. index:: sigdelset
-.. index:: delete a signal from a signal set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigdelset(
- sigset_t \*set,
- int signo
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function deletes the signal specified by ``signo`` from the specified
-signal ``set``.
-
-**NOTES:**
-
-The set must be initialized using either ``sigemptyset`` or ``sigfillset``
-before using this function.
-
-sigfillset - Fill a Signal Set
-------------------------------
-.. index:: sigfillset
-.. index:: fill a signal set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigfillset(
- sigset_t \*set
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function fills the specified signal ``set`` such that all
-signals are set.
-
-sigismember - Is Signal a Member of a Signal Set
-------------------------------------------------
-.. index:: sigismember
-.. index:: is signal a member of a signal set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigismember(
- const sigset_t \*set,
- int signo
- );
-
-**STATUS CODES:**
-
-The function returns either 1 or 0 if completed successfully, otherwise it
-returns -1 and sets ``errno`` to indicate the error. ``errno`` may be set
-to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function returns returns 1 if ``signo`` is a member of ``set``
-and 0 otherwise.
-
-**NOTES:**
-
-The set must be initialized using either ``sigemptyset`` or ``sigfillset``
-before using this function.
-
-sigemptyset - Empty a Signal Set
---------------------------------
-.. index:: sigemptyset
-.. index:: empty a signal set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigemptyset(
- sigset_t \*set
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function initializes an empty signal set pointed to by ``set``.
-
-sigaction - Examine and Change Signal Action
---------------------------------------------
-.. index:: sigaction
-.. index:: examine and change signal action
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigaction(
- int sig,
- const struct sigaction \*act,
- struct sigaction \*oact
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-*ENOTSUP*
- Realtime Signals Extension option not supported.
-
-**DESCRIPTION:**
-
-If the argument act is not a null pointer, it points to a structure specifying
-the action to be associated with the specified signal. If the argument oact is
-not a null pointer, the action previously associated with the signal is stored
-in the location pointed to by the argument oact. If the argument act is a null
-pointer, signal handling is unchanged; thus, the call can be used to enquire
-about the current handling of a given signal.
-
-The structure ``sigaction`` has the following members:
-
-``void(\*)(int) sa_handler``
- Pointer to a signal-catching function or one of the macros SIG_IGN or SIG_DFL.
-
-``sigset_t sa_mask``
- Additional set of signals to be blocked during execution of signal-catching function.
-
-``int sa_flags``
- Special flags to affect behavior of signal.
-
-``void(\*)(int, siginfo_t*, void*) sa_sigaction``
- Alternative pointer to a signal-catching function.
-
-``sa_handler`` and ``sa_sigaction`` should never be used at the same time as their storage may overlap.
-
-If the ``SA_SIGINFO`` flag (see below) is set in ``sa_flags``, the``sa_sigaction`` field specifies a signal-catching function, otherwise``sa_handler`` specifies the action to be associated with the signal, which
-may be a signal-catching function or one of the macros ``SIG_IGN`` or``SIG_DFN``.
-
-The following flags can be set in the ``sa_flags`` field:
-
-``SA_SIGINFO``
- If not set, the signal-catching function should be declared as ``void
- func(int signo)`` and the address of the function should be set in``sa_handler``. If set, the signal-catching function should be declared as``void func(int signo, siginfo_t* info, void* context)`` and the address of
- the function should be set in ``sa_sigaction``.
-
-The prototype of the ``siginfo_t`` structure is the following:
-.. code:: c
-
- typedef struct
- {
- int si_signo; /* Signal number \*/
- int si_code; /* Cause of the signal \*/
- pid_t si_pid; /* Sending process ID \*/
- uid_t si_uid; /* Real user ID of sending process \*/
- void* si_addr; /* Address of faulting instruction \*/
- int si_status; /* Exit value or signal \*/
- union sigval
- {
- int sival_int; /* Integer signal value \*/
- void* sival_ptr; /* Pointer signal value \*/
- } si_value; /* Signal value \*/
- }
-
-**NOTES:**
-
-The signal number cannot be SIGKILL.
-
-pthread_kill - Send a Signal to a Thread
-----------------------------------------
-.. index:: pthread_kill
-.. index:: send a signal to a thread
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int pthread_kill(
- pthread_t thread,
- int sig
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*ESRCH*
- The thread indicated by the parameter thread is invalid.
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This functions sends the specified signal ``sig`` to a thread referenced
-to by ``thread``.
-
-If the signal code is ``0``, arguments are validated and no signal is sent.
-
-sigprocmask - Examine and Change Process Blocked Signals
---------------------------------------------------------
-.. index:: sigprocmask
-.. index:: examine and change process blocked signals
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigprocmask(
- int how,
- const sigset_t \*set,
- sigset_t \*oset
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function is used to alter the set of currently blocked signals
-on a process wide basis. A blocked signal will not be received by the
-process. The behavior of this function is dependent on the value of``how`` which may be one of the following:
-
-``SIG_BLOCK``
- The set of blocked signals is set to the union of ``set`` and
- those signals currently blocked.
-
-``SIG_UNBLOCK``
- The signals specific in ``set`` are removed from the currently
- blocked set.
-
-``SIG_SETMASK``
- The set of currently blocked signals is set to ``set``.
-
-If ``oset`` is not ``NULL``, then the set of blocked signals prior to
-this call is returned in ``oset``. If ``set`` is *NULL*, no change is
-done, allowing to examine the set of currently blocked signals.
-
-**NOTES:**
-
-It is not an error to unblock a signal which is not blocked.
-
-In the current implementation of RTEMS POSIX API sigprocmask() is technically
-mapped to pthread_sigmask().
-
-pthread_sigmask - Examine and Change Thread Blocked Signals
------------------------------------------------------------
-.. index:: pthread_sigmask
-.. index:: examine and change thread blocked signals
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int pthread_sigmask(
- int how,
- const sigset_t \*set,
- sigset_t \*oset
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-This function is used to alter the set of currently blocked signals
-for the calling thread. A blocked signal will not be received by the
-process. The behavior of this function is dependent on the value of``how`` which may be one of the following:
-
-``SIG_BLOCK``
- The set of blocked signals is set to the union of ``set`` and
- those signals currently blocked.
-
-``SIG_UNBLOCK``
- The signals specific in ``set`` are removed from the currently
- blocked set.
-
-``SIG_SETMASK``
- The set of currently blocked signals is set to ``set``.
-
-If ``oset`` is not ``NULL``, then the set of blocked signals prior to
-this call is returned in ``oset``. If ``set`` is *NULL*, no change is
-done, allowing to examine the set of currently blocked signals.
-
-**NOTES:**
-
-It is not an error to unblock a signal which is not blocked.
-
-kill - Send a Signal to a Process
----------------------------------
-.. index:: kill
-.. index:: send a signal to a process
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <signal.h>
- int kill(
- pid_t pid,
- int sig
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-*EPERM*
- Process does not have permission to send the signal to any receiving process.
-
-*ESRCH*
- The process indicated by the parameter pid is invalid.
-
-**DESCRIPTION:**
-
-This function sends the signal ``sig`` to the process ``pid``.
-
-**NOTES:**
-
-Since RTEMS is a single-process system, a signal can only be sent to the calling
-process (i.e. the current node).
-
-sigpending - Examine Pending Signals
-------------------------------------
-.. index:: sigpending
-.. index:: examine pending signals
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigpending(
- const sigset_t \*set
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EFAULT*
- Invalid address for set.
-
-**DESCRIPTION:**
-
-This function allows the caller to examine the set of currently pending
-signals. A pending signal is one which has been raised but is currently
-blocked. The set of pending signals is returned in ``set``.
-
-sigsuspend - Wait for a Signal
-------------------------------
-.. index:: sigsuspend
-.. index:: wait for a signal
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigsuspend(
- const sigset_t \*sigmask
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINTR*
- Signal interrupted this function.
-
-**DESCRIPTION:**
-
-This function temporarily replaces the signal mask for the process
-with that specified by ``sigmask`` and blocks the calling thread
-until a signal is raised.
-
-pause - Suspend Process Execution
----------------------------------
-.. index:: pause
-.. index:: suspend process execution
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int pause( void );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINTR*
- Signal interrupted this function.
-
-**DESCRIPTION:**
-
-This function causes the calling thread to be blocked until an
-unblocked signal is received.
-
-sigwait - Synchronously Accept a Signal
----------------------------------------
-.. index:: sigwait
-.. index:: synchronously accept a signal
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigwait(
- const sigset_t \*set,
- int \*sig
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
-
-*EINTR*
- Signal interrupted this function.
-
-**DESCRIPTION:**
-
-This function selects a pending signal based on the set specified in``set``, atomically clears it from the set of pending signals, and
-returns the signal number for that signal in ``sig``.
-
-sigwaitinfo - Synchronously Accept a Signal
--------------------------------------------
-.. index:: sigwaitinfo
-.. index:: synchronously accept a signal
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigwaitinfo(
- const sigset_t \*set,
- siginfo_t \*info
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINTR*
- Signal interrupted this function.
-
-**DESCRIPTION:**
-
-This function selects a pending signal based on the set specified in``set``, atomically clears it from the set of pending signals, and
-returns information about that signal in ``info``.
-
-The prototype of the ``siginfo_t`` structure is the following:
-.. code:: c
-
- typedef struct
- {
- int si_signo; /* Signal number \*/
- int si_code; /* Cause of the signal \*/
- pid_t si_pid; /* Sending process ID \*/
- uid_t si_uid; /* Real user ID of sending process \*/
- void* si_addr; /* Address of faulting instruction \*/
- int si_status; /* Exit value or signal \*/
- union sigval
- {
- int sival_int; /* Integer signal value \*/
- void* sival_ptr; /* Pointer signal value \*/
- } si_value; /* Signal value \*/
- }
-
-sigtimedwait - Synchronously Accept a Signal with Timeout
----------------------------------------------------------
-.. index:: sigtimedwait
-.. index:: synchronously accept a signal with timeout
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigtimedwait(
- const sigset_t \*set,
- siginfo_t \*info,
- const struct timespec \*timeout
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EAGAIN*
- Timed out while waiting for the specified signal set.
-
-*EINVAL*
- Nanoseconds field of the timeout argument is invalid.
-
-*EINTR*
- Signal interrupted this function.
-
-**DESCRIPTION:**
-
-This function selects a pending signal based on the set specified in``set``, atomically clears it from the set of pending signals, and
-returns information about that signal in ``info``. The calling thread
-will block up to ``timeout`` waiting for the signal to arrive.
-
-The ``timespec`` structure is defined as follows:
-.. code:: c
-
- struct timespec
- {
- time_t tv_sec; /* Seconds \*/
- long tv_nsec; /* Nanoseconds \*/
- }
-
-**NOTES:**
-
-If ``timeout`` is NULL, then the calling thread will wait forever for
-the specified signal set.
-
-sigqueue - Queue a Signal to a Process
---------------------------------------
-.. index:: sigqueue
-.. index:: queue a signal to a process
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <signal.h>
- int sigqueue(
- pid_t pid,
- int signo,
- const union sigval value
- );
-
-**STATUS CODES:**
-
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EAGAIN*
- No resources available to queue the signal. The process has already
- queued SIGQUEUE_MAX signals that are still pending at the receiver
- or the systemwide resource limit has been exceeded.
-
-*EINVAL*
- The value of the signo argument is an invalid or unsupported signal
- number.
-
-*EPERM*
- The process does not have the appropriate privilege to send the signal
- to the receiving process.
-
-*ESRCH*
- The process pid does not exist.
-
-**DESCRIPTION:**
-
-This function sends the signal specified by ``signo`` to the
-process ``pid``
-
-The ``sigval`` union is specified as:
-.. code:: c
-
- union sigval
- {
- int sival_int; /* Integer signal value \*/
- void* sival_ptr; /* Pointer signal value \*/
- }
-
-**NOTES:**
-
-Since RTEMS is a single-process system, a signal can only be sent to the calling
-process (i.e. the current node).
-
-alarm - Schedule Alarm
-----------------------
-.. index:: alarm
-.. index:: schedule alarm
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- unsigned int alarm(
- unsigned int seconds
- );
-
-**STATUS CODES:**
-
-This call always succeeds.
-
-If there was a previous ``alarm()`` request with time remaining,
-then this routine returns the number of seconds until that outstanding
-alarm would have fired. If no previous ``alarm()`` request was
-outstanding, then zero is returned.
-
-**DESCRIPTION:**
-
-The ``alarm()`` service causes the ``SIGALRM`` signal to
-be generated after the number of seconds specified by``seconds`` has elapsed.
-
-**NOTES:**
-
-Alarm requests do not queue. If ``alarm`` is called while
-a previous request is outstanding, the call will result in
-rescheduling the time at which the ``SIGALRM`` signal
-will be generated.
-
-If the notification signal, ``SIGALRM``, is not caught or ignored, the
-calling process is terminated.
-
-ualarm - Schedule Alarm in Microseconds
----------------------------------------
-.. index:: alarm
-.. index:: microseonds alarm
-.. index:: usecs alarm
-.. index:: schedule alarm in microseonds
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- useconds_t ualarm(
- useconds_t useconds,
- useconds_t interval
- );
-
-**STATUS CODES:**
-
-This call always succeeds.
-
-If there was a previous ``ualarm()`` request with time remaining,
-then this routine returns the number of seconds until that outstanding
-alarm would have fired. If no previous ``alarm()`` request was
-outstanding, then zero is returned.
-
-**DESCRIPTION:**
-
-The ``ualarm()`` service causes the ``SIGALRM`` signal to
-be generated after the number of microseconds specified by``useconds`` has elapsed.
-
-When ``interval`` is non-zero, repeated timeout notification occurs
-with a period in microseconds specified by ``interval``.
-
-**NOTES:**
-
-Alarm requests do not queue. If ``alarm`` is called while
-a previous request is outstanding, the call will result in
-rescheduling the time at which the ``SIGALRM`` signal
-will be generated.
-
-If the notification signal, ``SIGALRM``, is not caught or ignored, the
-calling process is terminated.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Process Environment Manager
-###########################
-
-Introduction
-============
-
-The process environment manager is responsible for providing the
-functions related to user and group Id management.
-
-The directives provided by the process environment manager are:
-
-- ``getpid`` - Get Process ID
-
-- ``getppid`` - Get Parent Process ID
-
-- ``getuid`` - Get User ID
-
-- ``geteuid`` - Get Effective User ID
-
-- ``getgid`` - Get Real Group ID
-
-- ``getegid`` - Get Effective Group ID
-
-- ``setuid`` - Set User ID
-
-- ``setgid`` - Set Group ID
-
-- ``getgroups`` - Get Supplementary Group IDs
-
-- ``getlogin`` - Get User Name
-
-- ``getlogin_r`` - Reentrant Get User Name
-
-- ``getpgrp`` - Get Process Group ID
-
-- ``setsid`` - Create Session and Set Process Group ID
-
-- ``setpgid`` - Set Process Group ID for Job Control
-
-- ``uname`` - Get System Name
-
-- ``times`` - Get Process Times
-
-- ``getenv`` - Get Environment Variables
-
-- ``setenv`` - Set Environment Variables
-
-- ``ctermid`` - Generate Terminal Pathname
-
-- ``ttyname`` - Determine Terminal Device Name
-
-- ``ttyname_r`` - Reentrant Determine Terminal Device Name
-
-- ``isatty`` - Determine if File Descriptor is Terminal
-
-- ``sysconf`` - Get Configurable System Variables
-
-Background
-==========
-
-Users and Groups
-----------------
-
-RTEMS provides a single process, multi-threaded execution environment.
-In this light, the notion of user and group is somewhat without meaning.
-But RTEMS does provide services to provide a synthetic version of
-user and group. By default, a single user and group is associated
-with the application. Thus unless special actions are taken,
-every thread in the application shares the same user and group Id.
-The initial rationale for providing user and group Id functionality
-in RTEMS was for the filesystem infrastructure to implement
-file permission checks. The effective user/group Id capability
-has since been used to implement permissions checking by
-the ``ftpd`` server.
-
-In addition to the "real" user and group Ids, a process may
-have an effective user/group Id. This allows a process to
-function using a more limited permission set for certain operations.
-
-User and Group Names
---------------------
-
-POSIX considers user and group Ids to be a unique integer that
-may be associated with a name. This is usually accomplished
-via a file named ``/etc/passwd`` for user Id mapping and``/etc/groups`` for group Id mapping. Again, although
-RTEMS is effectively a single process and thus single user
-system, it provides limited support for user and group
-names. When configured with an appropriate filesystem, RTEMS
-will access the appropriate files to map user and group Ids
-to names.
-
-If these files do not exist, then RTEMS will synthesize
-a minimal version so this family of services return without
-error. It is important to remember that a design goal of
-the RTEMS POSIX services is to provide useable and
-meaningful results even though a full process model
-is not available.
-
-Environment Variables
----------------------
-
-POSIX allows for variables in the run-time environment. These are
-name/value pairs that make be dynamically set and obtained by
-programs. In a full POSIX environment with command line shell
-and multiple processes, environment variables may be set in
-one process – such as the shell – and inherited by child
-processes. In RTEMS, there is only one process and thus
-only one set of environment variables across all processes.
-
-Operations
-==========
-
-Accessing User and Group Ids
-----------------------------
-
-The user Id associated with the current thread may be obtain
-using the ``getuid()`` service. Similarly, the group Id
-may be obtained using the ``getgid()`` service.
-
-Accessing Environment Variables
--------------------------------
-
-The value associated with an environment variable may be
-obtained using the ``getenv()`` service and set using
-the ``putenv()`` service.
-
-Directives
-==========
-
-This section details the process environment 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.
-
-getpid - Get Process ID
------------------------
-.. index:: getpid
-.. index:: get process id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getpid( void );
-
-**STATUS CODES:**
-
-The process Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the process Id.
-
-**NOTES:**
-
-NONE
-
-getppid - Get Parent Process ID
--------------------------------
-.. index:: getppid
-.. index:: get parent process id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getppid( void );
-
-**STATUS CODES:**
-
-The parent process Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the parent process Id.
-
-**NOTES:**
-
-NONE
-
-getuid - Get User ID
---------------------
-.. index:: getuid
-.. index:: get user id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getuid( void );
-
-**STATUS CODES:**
-
-The effective user Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the effective user Id.
-
-**NOTES:**
-
-NONE
-
-geteuid - Get Effective User ID
--------------------------------
-.. index:: geteuid
-.. index:: get effective user id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int geteuid( void );
-
-**STATUS CODES:**
-
-The effective group Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the effective group Id.
-
-**NOTES:**
-
-NONE
-
-getgid - Get Real Group ID
---------------------------
-.. index:: getgid
-.. index:: get real group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getgid( void );
-
-**STATUS CODES:**
-
-The group Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the group Id.
-
-**NOTES:**
-
-NONE
-
-getegid - Get Effective Group ID
---------------------------------
-.. index:: getegid
-.. index:: get effective group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getegid( void );
-
-**STATUS CODES:**
-
-The effective group Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the effective group Id.
-
-**NOTES:**
-
-NONE
-
-setuid - Set User ID
---------------------
-.. index:: setuid
-.. index:: set user id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int setuid(
- uid_t uid
- );
-
-**STATUS CODES:**
-
-This service returns 0.
-
-**DESCRIPTION:**
-
-This service sets the user Id to ``uid``.
-
-**NOTES:**
-
-NONE
-
-setgid - Set Group ID
----------------------
-.. index:: setgid
-.. index:: set group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int setgid(
- gid_t gid
- );
-
-**STATUS CODES:**
-
-This service returns 0.
-
-**DESCRIPTION:**
-
-This service sets the group Id to ``gid``.
-
-**NOTES:**
-
-NONE
-
-getgroups - Get Supplementary Group IDs
----------------------------------------
-.. index:: getgroups
-.. index:: get supplementary group ids
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getgroups(
- int gidsetsize,
- gid_t grouplist[]
- );
-
-**STATUS CODES:**
-
-NA
-
-**DESCRIPTION:**
-
-This service is not implemented as RTEMS has no notion of
-supplemental groups.
-
-**NOTES:**
-
-If supported, this routine would only be allowed for
-the super-user.
-
-getlogin - Get User Name
-------------------------
-.. index:: getlogin
-.. index:: get user name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- char \*getlogin( void );
-
-**STATUS CODES:**
-
-Returns a pointer to a string containing the name of the
-current user.
-
-**DESCRIPTION:**
-
-This routine returns the name of the current user.
-
-**NOTES:**
-
-This routine is not reentrant and subsequent calls to``getlogin()`` will overwrite the same buffer.
-
-getlogin_r - Reentrant Get User Name
-------------------------------------
-.. index:: getlogin_r
-.. index:: reentrant get user name
-.. index:: get user name, reentrant
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getlogin_r(
- char \*name,
- size_t namesize
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The arguments were invalid.
-
-**DESCRIPTION:**
-
-This is a reentrant version of the ``getlogin()`` service. The
-caller specified their own buffer, ``name``, as well as the
-length of this buffer, ``namesize``.
-
-**NOTES:**
-
-NONE
-
-getpgrp - Get Process Group ID
-------------------------------
-.. index:: getpgrp
-.. index:: get process group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- pid_t getpgrp( void );
-
-**STATUS CODES:**
-
-The procress group Id is returned.
-
-**DESCRIPTION:**
-
-This service returns the current progress group Id.
-
-**NOTES:**
-
-This routine is implemented in a somewhat meaningful
-way for RTEMS but is truly not functional.
-
-setsid - Create Session and Set Process Group ID
-------------------------------------------------
-.. index:: setsid
-.. index:: create session and set process group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- pid_t setsid( void );
-
-**STATUS CODES:**
-
-*EPERM*
- The application does not have permission to create a process group.
-
-**DESCRIPTION:**
-
-This routine always returns ``EPERM`` as RTEMS has no way
-to create new processes and thus no way to create a new process
-group.
-
-**NOTES:**
-
-NONE
-
-setpgid - Set Process Group ID for Job Control
-----------------------------------------------
-.. index:: setpgid
-.. index:: set process group id for job control
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int setpgid(
- pid_t pid,
- pid_t pgid
- );
-
-**STATUS CODES:**
-
-*ENOSYS*
- The routine is not implemented.
-
-**DESCRIPTION:**
-
-This service is not implemented for RTEMS as process groups are not
-supported.
-
-**NOTES:**
-
-NONE
-
-uname - Get System Name
------------------------
-.. index:: uname
-.. index:: get system name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int uname(
- struct utsname \*name
- );
-
-**STATUS CODES:**
-
-*EPERM*
- The provided structure pointer is invalid.
-
-**DESCRIPTION:**
-
-This service returns system information to the caller. It does this
-by filling in the ``struct utsname`` format structure for the
-caller.
-
-**NOTES:**
-
-The information provided includes the operating system (RTEMS in
-all configurations), the node number, the release as the RTEMS
-version, and the CPU family and model. The CPU model name
-will indicate the multilib executive variant being used.
-
-times - Get process times
--------------------------
-.. index:: times
-.. index:: get process times
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/time.h>
- clock_t times(
- struct tms \*ptms
- );
-
-**STATUS CODES:**
-
-This routine returns the number of clock ticks that have elapsed
-since the system was initialized (e.g. the application was
-started).
-
-**DESCRIPTION:**
-
-``times`` stores the current process times in ``ptms``. The
-format of ``struct tms`` is as defined in``<sys/times.h>``. RTEMS fills in the field ``tms_utime``
-with the number of ticks that the calling thread has executed
-and the field ``tms_stime`` with the number of clock ticks
-since system boot (also returned). All other fields in the``ptms`` are left zero.
-
-**NOTES:**
-
-RTEMS has no way to distinguish between user and system time
-so this routine returns the most meaningful information
-possible.
-
-getenv - Get Environment Variables
-----------------------------------
-.. index:: getenv
-.. index:: get environment variables
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- char \*getenv(
- const char \*name
- );
-
-**STATUS CODES:**
-
-*NULL*
- when no match
-
-*pointer to value*
- when successful
-
-**DESCRIPTION:**
-
-This service searches the set of environment variables for
-a string that matches the specified ``name``. If found,
-it returns the associated value.
-
-**NOTES:**
-
-The environment list consists of name value pairs that
-are of the form *name = value*.
-
-setenv - Set Environment Variables
-----------------------------------
-.. index:: setenv
-.. index:: set environment variables
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int setenv(
- const char \*name,
- const char \*value,
- int overwrite
- );
-
-**STATUS CODES:**
-
-Returns 0 if successful and -1 otherwise.
-
-**DESCRIPTION:**
-
-This service adds the variable ``name`` to the environment with``value``. If ``name`` is not already exist, then it is
-created. If ``name`` exists and ``overwrite`` is zero, then
-the previous value is not overwritten.
-
-**NOTES:**
-
-NONE
-
-ctermid - Generate Terminal Pathname
-------------------------------------
-.. index:: ctermid
-.. index:: generate terminal pathname
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- char \*ctermid(
- char \*s
- );
-
-**STATUS CODES:**
-
-Returns a pointer to a string indicating the pathname for the controlling
-terminal.
-
-**DESCRIPTION:**
-
-This service returns the name of the terminal device associated with
-this process. If ``s`` is NULL, then a pointer to a static buffer
-is returned. Otherwise, ``s`` is assumed to have a buffer of
-sufficient size to contain the name of the controlling terminal.
-
-**NOTES:**
-
-By default on RTEMS systems, the controlling terminal is ``/dev/console``.
-Again this implementation is of limited meaning, but it provides
-true and useful results which should be sufficient to ease porting
-applications from a full POSIX implementation to the reduced
-profile supported by RTEMS.
-
-ttyname - Determine Terminal Device Name
-----------------------------------------
-.. index:: ttyname
-.. index:: determine terminal device name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- char \*ttyname(
- int fd
- );
-
-**STATUS CODES:**
-
-Pointer to a string containing the terminal device name or
-NULL is returned on any error.
-
-**DESCRIPTION:**
-
-This service returns a pointer to the pathname of the terminal
-device that is open on the file descriptor ``fd``. If``fd`` is not a valid descriptor for a terminal device,
-then NULL is returned.
-
-**NOTES:**
-
-This routine uses a static buffer.
-
-ttyname_r - Reentrant Determine Terminal Device Name
-----------------------------------------------------
-.. index:: ttyname_r
-.. index:: reentrant determine terminal device name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int ttyname_r(
- int fd,
- char \*name,
- int namesize
- );
-
-**STATUS CODES:**
-
-This routine returns -1 and sets ``errno`` as follows:
-
-*EBADF*
- If not a valid descriptor for a terminal device.
-
-*EINVAL*
- If ``name`` is NULL or ``namesize`` are insufficient.
-
-**DESCRIPTION:**
-
-This service the pathname of the terminal device that is open
-on the file descriptor ``fd``.
-
-**NOTES:**
-
-NONE
-
-isatty - Determine if File Descriptor is Terminal
--------------------------------------------------
-.. index:: isatty
-.. index:: determine if file descriptor is terminal
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int isatty(
- int fd
- );
-
-**STATUS CODES:**
-
-Returns 1 if ``fd`` is a terminal device and 0 otherwise.
-
-**DESCRIPTION:**
-
-This service returns 1 if ``fd`` is an open file descriptor
-connected to a terminal and 0 otherwise.
-
-**NOTES:**
-
-sysconf - Get Configurable System Variables
--------------------------------------------
-.. index:: sysconf
-.. index:: get configurable system variables
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- long sysconf(
- int name
- );
-
-**STATUS CODES:**
-
-The value returned is the actual value of the system resource.
-If the requested configuration name is a feature flag, then
-1 is returned if the available and 0 if it is not. On any
-other error condition, -1 is returned.
-
-**DESCRIPTION:**
-
-This service is the mechanism by which an application determines
-values for system limits or options at runtime.
-
-**NOTES:**
-
-Much of the information that may be obtained via ``sysconf``
-has equivalent macros in ``<unistd.h``. However, those
-macros reflect conservative limits which may have been altered
-by application configuration.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Files and Directories Manager
-#############################
-
-Introduction
-============
-
-The files and directories manager is ...
-
-The directives provided by the files and directories manager are:
-
-- ``opendir`` - Open a Directory
-
-- ``readdir`` - Reads a directory
-
-- ``rewinddir`` - Resets the ``readdir()`` pointer
-
-- ``scandir`` - Scan a directory for matching entries
-
-- ``telldir`` - Return current location in directory stream
-
-- ``closedir`` - Ends directory read operation
-
-- ``getdents`` - Get directory entries
-
-- ``chdir`` - Changes the current working directory
-
-- ``fchdir`` - Changes the current working directory
-
-- ``getcwd`` - Gets current working directory
-
-- ``open`` - Opens a file
-
-- ``creat`` - Create a new file or rewrite an existing one
-
-- ``umask`` - Sets a file creation mask
-
-- ``link`` - Creates a link to a file
-
-- ``symlink`` - Creates a symbolic link to a file
-
-- ``readlink`` - Obtain the name of the link destination
-
-- ``mkdir`` - Makes a directory
-
-- ``mkfifo`` - Makes a FIFO special file
-
-- ``unlink`` - Removes a directory entry
-
-- ``rmdir`` - Delete a directory
-
-- ``rename`` - Renames a file
-
-- ``stat`` - Gets information about a file.
-
-- ``fstat`` - Gets file status
-
-- ``lstat`` - Gets file status
-
-- ``access`` - Check permissions for a file.
-
-- ``chmod`` - Changes file mode
-
-- ``fchmod`` - Changes permissions of a file
-
-- ``chown`` - Changes the owner and/ or group of a file
-
-- ``utime`` - Change access and/or modification times of an inode
-
-- ``ftruncate`` - Truncate a file to a specified length
-
-- ``truncate`` - Truncate a file to a specified length
-
-- ``pathconf`` - Gets configuration values for files
-
-- ``fpathconf`` - Get configuration values for files
-
-- ``mknod`` - Create a directory
-
-Background
-==========
-
-Path Name Evaluation
---------------------
-
-A pathname is a string that consists of no more than ``PATH_MAX``
-bytes, including the terminating null character. A pathname has an optional
-beginning slash, followed by zero or more filenames separated by slashes.
-If the pathname refers to a directory, it may also have one or more trailing
-slashes. Multiple successive slahes are considered to be the same as
-one slash.
-
-POSIX allows a pathname that begins with precisely two successive slashes to be
-interpreted in an implementation-defined manner. RTEMS does not currently
-recognize this as a special condition. Any number of successive
-slashes is treated the same as a single slash. POSIX requires that
-an implementation treat more than two leading slashes as a single slash.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the files and directories 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.
-
-opendir - Open a Directory
---------------------------
-.. index:: opendir
-.. index:: open a directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <dirent.h>
- int opendir(
- const char \*dirname
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission was denied on a component of the path
- prefix of ``dirname``, or read permission is denied
-
-*EMFILE*
- Too many file descriptors in use by process
-
-*ENFILE*
- Too many files are currently open in the system.
-
-*ENOENT*
- Directory does not exist, or ``name`` is an empty string.
-
-*ENOMEM*
- Insufficient memory to complete the operation.
-
-*ENOTDIR*
- ``name`` is not a directory.
-
-**DESCRIPTION:**
-
-This routine opens a directory stream corresponding to the
-directory specified by the ``dirname`` argument. The
-directory stream is positioned at the first entry.
-
-**NOTES:**
-
-The routine is implemented in Cygnus newlib.
-
-readdir - Reads a directory
----------------------------
-.. index:: readdir
-.. index:: reads a directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <dirent.h>
- int readdir(
- DIR \*dirp
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-**DESCRIPTION:**
-
-The ``readdir()`` function returns a pointer to a structure ``dirent``
-representing the next directory entry from the directory stream pointed to
-by ``dirp``. On end-of-file, NULL is returned.
-
-The ``readdir()`` function may (or may not) return entries for . or .. Your
-program should tolerate reading dot and dot-dot but not require them.
-
-The data pointed to be ``readdir()`` may be overwritten by another call to``readdir()`` for the same directory stream. It will not be overwritten by
-a call for another directory.
-
-**NOTES:**
-
-If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or``realloc()`` or has been deallocated with ``free()`` or``realloc()``, the results are not portable and are probably disastrous.
-
-The routine is implemented in Cygnus newlib.
-
-rewinddir - Resets the readdir() pointer
-----------------------------------------
-.. index:: rewinddir
-.. index:: resets the readdir() pointer
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <dirent.h>
- void rewinddir(
- DIR \*dirp
- );
-
-**STATUS CODES:**
-
-No value is returned.
-
-**DESCRIPTION:**
-
-The ``rewinddir()`` function resets the position associated with
-the directory stream pointed to by ``dirp``. It also causes the
-directory stream to refer to the current state of the directory.
-
-**NOTES:**
-
-NONE
-
-If ``dirp`` is not a pointer by ``opendir()``, the results are
-undefined.
-
-The routine is implemented in Cygnus newlib.
-
-scandir - Scan a directory for matching entries
------------------------------------------------
-.. index:: scandir
-.. index:: scan a directory for matching entries
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <dirent.h>
- int scandir(
- const char \*dir,
- struct dirent \***namelist,
- int (\*select)(const struct dirent \*),
- int (\*compar)(const struct dirent \**, const struct dirent \**)
- );
-
-**STATUS CODES:**
-
-*ENOMEM*
- Insufficient memory to complete the operation.
-
-**DESCRIPTION:**
-
-The ``scandir()`` function scans the directory ``dir``, calling``select()`` on each directory entry. Entries for which ``select()``
-returns non-zero are stored in strings allocated via ``malloc()``,
-sorted using ``qsort()`` with the comparison function ``compar()``,
-and collected in array ``namelist`` which is allocated via ``malloc()``.
-If ``select`` is NULL, all entries are selected.
-
-**NOTES:**
-
-The routine is implemented in Cygnus newlib.
-
-telldir - Return current location in directory stream
------------------------------------------------------
-.. index:: telldir
-.. index:: return current location in directory stream
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <dirent.h>
- off_t telldir(
- DIR \*dir
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid directory stream descriptor ``dir``.
-
-**DESCRIPTION:**
-
-The ``telldir()`` function returns the current location associated with the
-directory stream ``dir``.
-
-**NOTES:**
-
-The routine is implemented in Cygnus newlib.
-
-closedir - Ends directory read operation
-----------------------------------------
-.. index:: closedir
-.. index:: ends directory read operation
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <dirent.h>
- int closedir(
- DIR \*dirp
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-**DESCRIPTION:**
-
-The directory stream associated with ``dirp`` is closed.
-The value in ``dirp`` may not be usable after a call to``closedir()``.
-
-**NOTES:**
-
-NONE
-
-The argument to ``closedir()`` must be a pointer returned by``opendir()``. If it is not, the results are not portable and
-most likely unpleasant.
-
-The routine is implemented in Cygnus newlib.
-
-chdir - Changes the current working directory
----------------------------------------------
-.. index:: chdir
-.. index:: changes the current working directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int chdir(
- const char \*path
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets ``errno`` to one of
-the following:
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when directory
- was expected.
-
-**DESCRIPTION:**
-
-The ``chdir()`` function causes the directory named by ``path`` to
-become the current working directory; that is, the starting point for
-searches of pathnames not beginning with a slash.
-
-If ``chdir()`` detects an error, the current working directory is not
-changed.
-
-**NOTES:**
-
-NONE
-
-fchdir - Changes the current working directory
-----------------------------------------------
-.. index:: fchdir
-.. index:: changes the current working directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int fchdir(
- int fd
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets ``errno`` to one of
-the following:
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when directory
- was expected.
-
-**DESCRIPTION:**
-
-The ``fchdir()`` function causes the directory named by ``fd`` to
-become the current working directory; that is, the starting point for
-searches of pathnames not beginning with a slash.
-
-If ``fchdir()`` detects an error, the current working directory is not
-changed.
-
-**NOTES:**
-
-NONE
-
-getcwd - Gets current working directory
----------------------------------------
-.. index:: getcwd
-.. index:: gets current working directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int getcwd( void );
-
-**STATUS CODES:**
-
-*EINVAL*
- Invalid argument
-
-*ERANGE*
- Result is too large
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-**DESCRIPTION:**
-
-The ``getcwd()`` function copies the absolute pathname of the current
-working directory to the character array pointed to by ``buf``. The``size`` argument is the number of bytes available in ``buf``
-
-**NOTES:**
-
-There is no way to determine the maximum string length that ``fetcwd()``
-may need to return. Applications should tolerate getting ``ERANGE``
-and allocate a larger buffer.
-
-It is possible for ``getcwd()`` to return EACCES if, say, ``login``
-puts the process into a directory without read access.
-
-The 1988 standard uses ``int`` instead of ``size_t`` for the second
-parameter.
-
-open - Opens a file
--------------------
-.. index:: open
-.. index:: opens a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- #include <fcntl.h>
- int open(
- const char \*path,
- int oflag,
- mode_t mode
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-*EEXIST*
- The named file already exists.
-
-*EINTR*
- Function was interrupted by a signal.
-
-*EISDIR*
- Attempt to open a directory for writing or to rename a file to be a
- directory.
-
-*EMFILE*
- Too many file descriptors are in use by this process.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENFILE*
- Too many files are currently open in the system.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*ENXIO*
- No such device. This error may also occur when a device is not ready, for
- example, a tape drive is off-line.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-The ``open`` function establishes a connection between a file and a file
-descriptor. The file descriptor is a small integer that is used by I/O
-functions to reference the file. The ``path`` argument points to the
-pathname for the file.
-
-The ``oflag`` argument is the bitwise inclusive OR of the values of
-symbolic constants. The programmer must specify exactly one of the following
-three symbols:
-
-*O_RDONLY*
- Open for reading only.
-
-*O_WRONLY*
- Open for writing only.
-
-*O_RDWR*
- Open for reading and writing.
-
-Any combination of the following symbols may also be used.
-
-*O_APPEND*
- Set the file offset to the end-of-file prior to each write.
-
-*O_CREAT*
- If the file does not exist, allow it to be created. This flag indicates
- that the ``mode`` argument is present in the call to ``open``.
-
-*O_EXCL*
- This flag may be used only if O_CREAT is also set. It causes the call
- to ``open`` to fail if the file already exists.
-
-*O_NOCTTY*
- If ``path`` identifies a terminal, this flag prevents that teminal from
- becoming the controlling terminal for thi9s process. See Chapter 8 for a
- description of terminal I/O.
-
-*O_NONBLOCK*
- Do no wait for the device or file to be ready or available. After the file
- is open, the ``read`` and ``write`` calls return immediately. If the
- process would be delayed in the read or write opermation, -1 is returned and``errno`` is set to ``EAGAIN`` instead of blocking the caller.
-
-*O_TRUNC*
- This flag should be used only on ordinary files opened for writing. It
- causes the file to be tuncated to zero length..
-
-Upon successful completion, ``open`` returns a non-negative file
-descriptor.
-
-**NOTES:**
-
-NONE
-
-creat - Create a new file or rewrite an existing one
-----------------------------------------------------
-.. index:: creat
-.. index:: create a new file or rewrite an existing one
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- #include <fcntl.h>
- int creat(
- const char \*path,
- mode_t mode
- );
-
-**STATUS CODES:**
-
-*EEXIST*
- ``path`` already exists and O_CREAT and O_EXCL were used.
-
-*EISDIR*
- ``path`` refers to a directory and the access requested involved
- writing
-
-*ETXTBSY*
- ``path`` refers to an executable image which is currently being
- executed and write access was requested
-
-*EFAULT*
- ``path`` points outside your accessible address space
-
-*EACCES*
- The requested access to the file is not allowed, or one of the
- directories in ``path`` did not allow search (execute) permission.
-
-*ENAMETOOLONG*
- ``path`` was too long.
-
-*ENOENT*
- A directory component in ``path`` does not exist or is a dangling
- symbolic link.
-
-*ENOTDIR*
- A component used as a directory in ``path`` is not, in fact, a
- directory.
-
-*EMFILE*
- The process alreadyh has the maximum number of files open.
-
-*ENFILE*
- The limit on the total number of files open on the system has been
- reached.
-
-*ENOMEM*
- Insufficient kernel memory was available.
-
-*EROFS*
- ``path`` refers to a file on a read-only filesystem and write access
- was requested
-
-**DESCRIPTION:**
-
-``creat`` attempts to create a file and return a file descriptor for
-use in read, write, etc.
-
-**NOTES:**
-
-NONE
-
-The routine is implemented in Cygnus newlib.
-
-umask - Sets a file creation mask.
-----------------------------------
-.. index:: umask
-.. index:: sets a file creation mask.
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- mode_t umask(
- mode_t cmask
- );
-
-**STATUS CODES:**
-
-**DESCRIPTION:**
-
-The ``umask()`` function sets the process file creation mask to ``cmask``.
-The file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,``mkfifo()`` calls to turn off permission bits in the ``mode`` argument.
-Bit positions that are set in ``cmask`` are cleared in the mode of the
-created file.
-
-**NOTES:**
-
-NONE
-
-The ``cmask`` argument should have only permission bits set. All other
-bits should be zero.
-
-In a system which supports multiple processes, the file creation mask is inherited
-across ``fork()`` and ``exec()`` calls. This makes it possible to alter the
-default permission bits of created files. RTEMS does not support multiple processes
-so this behavior is not possible.
-
-link - Creates a link to a file
--------------------------------
-.. index:: link
-.. index:: creates a link to a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int link(
- const char \*existing,
- const char \*new
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*EEXIST*
- The named file already exists.
-
-*EMLINK*
- The number of links would exceed ``LINK_MAX``.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
-
-*EXDEV*
- Attempt to link a file to another file system.
-
-**DESCRIPTION:**
-
-The ``link()`` function atomically creates a new link for an existing file
-and increments the link count for the file.
-
-If the ``link()`` function fails, no directories are modified.
-
-The ``existing`` argument should not be a directory.
-
-The caller may (or may not) need permission to access the existing file.
-
-**NOTES:**
-
-NONE
-
-symlink - Creates a symbolic link to a file
--------------------------------------------
-.. index:: symlink
-.. index:: creates a symbolic link to a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int symlink(
- const char \*topath,
- const char \*frompath
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*EEXIST*
- The named file already exists.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-The ``symlink()`` function creates a symbolic link from the frombath to the
-topath. The symbolic link will be interpreted at run-time.
-
-If the ``symlink()`` function fails, no directories are modified.
-
-The caller may (or may not) need permission to access the existing file.
-
-**NOTES:**
-
-NONE
-
-readlink - Obtain the name of a symbolic link destination
----------------------------------------------------------
-.. index:: readlink
-.. index:: obtain the name of a symbolic link destination
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int readlink(
- const char \*path,
- char \*buf,
- size_t bufsize
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the prefix pathname was not a directory when a directory
- was expected.
-
-*ELOOP*
- Too many symbolic links were encountered in the pathname.
-
-*EINVAL*
- The pathname does not refer to a symbolic link
-
-*EFAULT*
- An invalid pointer was passed into the ``readlink()`` routine.
-
-**DESCRIPTION:**
-
-The ``readlink()`` function places the symbolic link destination into``buf`` argument and returns the number of characters copied.
-
-If the symbolic link destination is longer than bufsize characters the
-name will be truncated.
-
-**NOTES:**
-
-NONE
-
-mkdir - Makes a directory
--------------------------
-.. index:: mkdir
-.. index:: makes a directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int mkdir(
- const char \*path,
- mode_t mode
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*EEXIST*
- The name file already exist.
-
-*EMLINK*
- The number of links would exceed LINK_MAX
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-The ``mkdir()`` function creates a new diectory named ``path``. The
-permission bits (modified by the file creation mask) are set from ``mode``.
-The owner and group IDs for the directory are set from the effective user ID
-and group ID.
-
-The new directory may (or may not) contain entries for.. and .. but is otherwise
-empty.
-
-**NOTES:**
-
-NONE
-
-mkfifo - Makes a FIFO special file
-----------------------------------
-.. index:: mkfifo
-.. index:: makes a fifo special file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int mkfifo(
- const char \*path,
- mode_t mode
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*EEXIST*
- The named file already exists.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory when a directory
- was expected.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-The ``mkfifo()`` function creates a new FIFO special file named ``path``.
-The permission bits (modified by the file creation mask) are set from``mode``. The owner and group IDs for the FIFO are set from the efective
-user ID and group ID.
-
-**NOTES:**
-
-NONE
-
-unlink - Removes a directory entry
-----------------------------------
-.. index:: unlink
-.. index:: removes a directory entry
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int unlink(
- const char path
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*EBUSY*
- The directory is in use.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-The ``unlink`` function removes the link named by ``path`` and decrements the
-link count of the file referenced by the link. When the link count goes to zero
-and no process has the file open, the space occupied by the file is freed and the
-file is no longer accessible.
-
-**NOTES:**
-
-NONE
-
-rmdir - Delete a directory
---------------------------
-.. index:: rmdir
-.. index:: delete a directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int rmdir(
- const char \*pathname
- );
-
-**STATUS CODES:**
-
-*EPERM*
- The filesystem containing ``pathname`` does not support the removal
- of directories.
-
-*EFAULT*
- ``pathname`` points ouside your accessible address space.
-
-*EACCES*
- Write access to the directory containing ``pathname`` was not
- allowed for the process’s effective uid, or one of the directories in``pathname`` did not allow search (execute) permission.
-
-*EPERM*
- The directory containing ``pathname`` has the stickybit (S_ISVTX)
- set and the process’s effective uid is neither the uid of the file to
- be delected nor that of the director containing it.
-
-*ENAMETOOLONG*
- ``pathname`` was too long.
-
-*ENOENT*
- A dirctory component in ``pathname`` does not exist or is a
- dangling symbolic link.
-
-*ENOTDIR*
- ``pathname``, or a component used as a directory in ``pathname``,
- is not, in fact, a directory.
-
-*ENOTEMPTY*
- ``pathname`` contains entries other than . and .. .
-
-*EBUSY*
- ``pathname`` is the current working directory or root directory of
- some process
-
-*EBUSY*
- ``pathname`` is the current directory or root directory of some
- process.
-
-*ENOMEM*
- Insufficient kernel memory was available
-
-*EROGS*
- ``pathname`` refers to a file on a read-only filesystem.
-
-*ELOOP*
- ``pathname`` contains a reference to a circular symbolic link
-
-**DESCRIPTION:**
-
-``rmdir`` deletes a directory, which must be empty
-
-**NOTES:**
-
-NONE
-
-rename - Renames a file
------------------------
-.. index:: rename
-.. index:: renames a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int rename(
- const char \*old,
- const char \*new
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-*EBUSY*
- The directory is in use.
-
-*EEXIST*
- The named file already exists.
-
-*EINVAL*
- Invalid argument.
-
-*EISDIR*
- Attempt to open a directory for writing or to rename a file to be a
- directory.
-
-*EMLINK*
- The number of links would exceed LINK_MAX.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does no exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a
- directory was expected.
-
-*ENOTEMPTY*
- Attempt to delete or rename a non-empty directory.
-
-*EROFS*
- Read-only file system
-
-*EXDEV*
- Attempt to link a file to another file system.
-
-**DESCRIPTION:**
-
-The ``rename()`` function causes the file known bo ``old`` to
-now be known as ``new``.
-
-Ordinary files may be renamed to ordinary files, and directories may be
-renamed to directories; however, files cannot be converted using``rename()``. The ``new`` pathname may not contain a path prefix
-of ``old``.
-
-**NOTES:**
-
-If a file already exists by the name ``new``, it is removed. The``rename()`` function is atomic. If the ``rename()`` detects an
-error, no files are removed. This guarantees that the``rename("x", "x")`` does not remove ``x``.
-
-You may not rename dot or dot-dot.
-
-The routine is implemented in Cygnus newlib using ``link()`` and``unlink()``.
-
-stat - Gets information about a file
-------------------------------------
-.. index:: stat
-.. index:: gets information about a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int stat(
- const char \*path,
- struct stat \*buf
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-*EBADF*
- Invalid file descriptor.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a
- directory was expected.
-
-**DESCRIPTION:**
-
-The ``path`` argument points to a pathname for a file. Read, write, or
-execute permission for the file is not required, but all directories listed
-in ``path`` must be searchable. The ``stat()`` function obtains
-information about the named file and writes it to the area pointed to by``buf``.
-
-**NOTES:**
-
-NONE
-
-fstat - Gets file status
-------------------------
-.. index:: fstat
-.. index:: gets file status
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int fstat(
- int fildes,
- struct stat \*buf
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-**DESCRIPTION:**
-
-The ``fstat()`` function obtains information about the file
-associated with ``fildes`` and writes it to the area pointed
-to by the ``buf`` argument.
-
-**NOTES:**
-
-If the filesystem object referred to by ``fildes`` is a
-link, then the information returned in ``buf`` refers
-to the destination of that link. This is in contrast to``lstat()`` which does not follow the link.
-
-lstat - Gets file status
-------------------------
-.. index:: lstat
-.. index:: gets file status
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int lstat(
- int fildes,
- struct stat \*buf
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-**DESCRIPTION:**
-
-The ``lstat()`` function obtains information about the file
-associated with ``fildes`` and writes it to the area pointed
-to by the ``buf`` argument.
-
-**NOTES:**
-
-If the filesystem object referred to by ``fildes`` is a
-link, then the information returned in ``buf`` refers
-to the link itself. This is in contrast to ``fstat()``
-which follows the link.
-
-The ``lstat()`` routine is defined by BSD 4.3 and SVR4
-and not included in POSIX 1003.1b-1996.
-
-access - Check permissions for a file
--------------------------------------
-.. index:: access
-.. index:: check permissions for a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int access(
- const char \*pathname,
- int mode
- );
-
-**STATUS CODES:**
-
-*EACCES*
- The requested access would be denied, either to the file itself or
- one of the directories in ``pathname``.
-
-*EFAULT*
- ``pathname`` points outside your accessible address space.
-
-*EINVAL*
- ``Mode`` was incorrectly specified.
-
-*ENAMETOOLONG*
- ``pathname`` is too long.
-
-*ENOENT*
- A directory component in ``pathname`` would have been accessible but
- does not exist or was a dangling symbolic link.
-
-*ENOTDIR*
- A component used as a directory in ``pathname`` is not, in fact,
- a directory.
-
-*ENOMEM*
- Insufficient kernel memory was available.
-
-**DESCRIPTION:**
-
-``Access`` checks whether the process would be allowed to read, write or
-test for existence of the file (or other file system object) whose name is``pathname``. If ``pathname`` is a symbolic link permissions of the
-file referred by this symbolic link are tested.
-
-``Mode`` is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
-
-**NOTES:**
-
-NONE
-
-chmod - Changes file mode.
---------------------------
-.. index:: chmod
-.. index:: changes file mode.
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int chmod(
- const char \*path,
- mode_t mode
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-Set the file permission bits, the set user ID bit, and the set group ID bit
-for the file named by ``path`` to ``mode``. If the effective user ID
-does not match the owner of the file and the calling process does not have
-the appropriate privileges, ``chmod()`` returns -1 and sets ``errno`` to``EPERM``.
-
-**NOTES:**
-
-NONE
-
-fchmod - Changes permissions of a file
---------------------------------------
-.. index:: fchmod
-.. index:: changes permissions of a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <sys/stat.h>
- int fchmod(
- int fildes,
- mode_t mode
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix.
-
-*EBADF*
- The descriptor is not valid.
-
-*EFAULT*
- ``path`` points outside your accessible address space.
-
-*EIO*
- A low-level I/o error occurred while modifying the inode.
-
-*ELOOP*
- ``path`` contains a circular reference
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does no exist.
-
-*ENOMEM*
- Insufficient kernel memory was avaliable.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a
- directory was expected.
-
-*EPERM*
- The effective UID does not match the owner of the file, and is not
- zero
-
-*EROFS*
- Read-only file system
-
-**DESCRIPTION:**
-
-The mode of the file given by ``path`` or referenced by``filedes`` is changed.
-
-**NOTES:**
-
-NONE
-
-getdents - Get directory entries
---------------------------------
-.. index:: getdents
-.. index:: get directory entries
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- #include <linux/dirent.h>
- #include <linux/unistd.h>
- long getdents(
- int dd_fd,
- char \*dd_buf,
- int dd_len
- );
-
-**STATUS CODES:**
-
-A successful call to ``getdents`` returns th the number of bytes read.
-On end of directory, 0 is returned. When an error occurs, -1 is returned,
-and ``errno`` is set appropriately.
-
-*EBADF*
- Invalid file descriptor ``fd``.
-
-*EFAULT*
- Argument points outside the calling process’s address space.
-
-*EINVAL*
- Result buffer is too small.
-
-*ENOENT*
- No such directory.
-
-*ENOTDIR*
- File descriptor does not refer to a directory.
-
-**DESCRIPTION:**
-
-``getdents`` reads several ``dirent`` structures from the directory
-pointed by ``fd`` into the memory area pointed to by ``dirp``. The
-parameter ``count`` is the size of the memory area.
-
-**NOTES:**
-
-NONE
-
-chown - Changes the owner and/or group of a file.
--------------------------------------------------
-.. index:: chown
-.. index:: changes the owner and/or group of a file.
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <unistd.h>
- int chown(
- const char \*path,
- uid_t owner,
- gid_t group
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Search permission is denied for a directory in a file’s path prefix
-
-*EINVAL*
- Invalid argument
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
-
-**DESCRIPTION:**
-
-The user ID and group ID of the file named by ``path`` are set to``owner`` and ``path``, respectively.
-
-For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
-bits are cleared.
-
-Some systems consider it a security violation to allow the owner of a file to
-be changed, If users are billed for disk space usage, loaning a file to
-another user could result in incorrect billing. The ``chown()`` function
-may be restricted to privileged users for some or all files. The group ID can
-still be changed to one of the supplementary group IDs.
-
-**NOTES:**
-
-This function may be restricted for some file. The ``pathconf`` function
-can be used to test the ``_PC_CHOWN_RESTRICTED`` flag.
-
-utime - Change access and/or modification times of an inode
------------------------------------------------------------
-.. index:: utime
-.. index:: change access and/or modification times of an inode
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- int utime(
- const char \*filename,
- struct utimbuf \*buf
- );
-
-**STATUS CODES:**
-
-*EACCES*
- Permission to write the file is denied
-
-*ENOENT*
- ``Filename`` does not exist
-
-**DESCRIPTION:**
-
-``Utime`` changes the access and modification times of the inode
-specified by ``filename`` to the ``actime`` and ``modtime``
-fields of ``buf`` respectively. If ``buf`` is NULL, then the
-access and modification times of the file are set to the current time.
-
-**NOTES:**
-
-NONE
-
-ftruncate - truncate a file to a specified length
--------------------------------------------------
-.. index:: ftruncate
-.. index:: truncate a file to a specified length
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int ftrunctate(
- int fd,
- size_t length
- );
-
-**STATUS CODES:**
-
-*ENOTDIR*
- A component of the path prefix is not a directory.
-
-*EINVAL*
- The pathname contains a character with the high-order bit set.
-
-*ENAMETOOLONG*
- A component of a pathname exceeded 255 characters, or an entire
- path name exceeded 1023 characters.
-
-*ENOENT*
- The named file does not exist.
-
-*EACCES*
- The named file is not writable by the user.
-
-*EACCES*
- Search permission is denied for a component of the path prefix.
-
-*ELOOP*
- Too many symbolic links were encountered in translating the
- pathname
-
-*EISDIR*
- The named file is a directory.
-
-*EROFS*
- The named file resides on a read-only file system
-
-*ETXTBSY*
- The file is a pure procedure (shared text) file that is being
- executed
-
-*EIO*
- An I/O error occurred updating the inode.
-
-*EFAULT*
- ``Path`` points outside the process’s allocated address space.
-
-*EBADF*
- The ``fd`` is not a valid descriptor.
-
-**DESCRIPTION:**
-
-``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
-file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
-
-**NOTES:**
-
-NONE
-
-truncate - truncate a file to a specified length
-------------------------------------------------
-.. index:: truncate
-.. index:: truncate a file to a specified length
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int trunctate(
- const char \*path,
- size_t length
- );
-
-**STATUS CODES:**
-
-*ENOTDIR*
- A component of the path prefix is not a directory.
-
-*EINVAL*
- The pathname contains a character with the high-order bit set.
-
-*ENAMETOOLONG*
- A component of a pathname exceeded 255 characters, or an entire
- path name exceeded 1023 characters.
-
-*ENOENT*
- The named file does not exist.
-
-*EACCES*
- The named file is not writable by the user.
-
-*EACCES*
- Search permission is denied for a component of the path prefix.
-
-*ELOOP*
- Too many symbolic links were encountered in translating the
- pathname
-
-*EISDIR*
- The named file is a directory.
-
-*EROFS*
- The named file resides on a read-only file system
-
-*ETXTBSY*
- The file is a pure procedure (shared text) file that is being
- executed
-
-*EIO*
- An I/O error occurred updating the inode.
-
-*EFAULT*
- ``Path`` points outside the process’s allocated address space.
-
-*EBADF*
- The ``fd`` is not a valid descriptor.
-
-**DESCRIPTION:**
-
-``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
-file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
-
-**NOTES:**
-
-NONE
-
-pathconf - Gets configuration values for files
-----------------------------------------------
-.. index:: pathconf
-.. index:: gets configuration values for files
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int pathconf(
- const char \*path,
- int name
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- Invalid argument
-
-*EACCES*
- Permission to write the file is denied
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
- is in effect.
-
-*ENOENT*
- A file or directory does not exist
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory whan a
- directory was expected.
-
-**DESCRIPTION:**
-
-``pathconf()`` gets a value for the configuration option ``name``
-for the open file descriptor ``filedes``.
-
-The possible values for ``name`` are:
-
-*_PC_LINK_MAX*
- returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
- directory. The corresponding macro is ``_POSIX_LINK_MAX``.
-
-*_PC_MAX_CANON*
- returns the maximum length of a formatted input line, where ``filedes``
- or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
-
-*_PC_MAX_INPUT*
- returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
-
-*_PC_NAME_MAX*
- returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
- is ``_POSIX_NAME_MAX``.
-
-*_PC_PATH_MAX*
- returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
- is ``_POSIX_PATH_MAX``.
-
-*_PC_PIPE_BUF*
- returns the size of the pipe buffer, where ``filedes`` must refer to a
- pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
- is ``_POSIX_PIPE_BUF``.
-
-*_PC_CHOWN_RESTRICTED*
- returns nonzero if the chown(2) call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
- files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
-
-**NOTES:**
-
-Files with name lengths longer than the value returned for ``name`` equal``_PC_NAME_MAX`` may exist in the given directory.
-
-fpathconf - Gets configuration values for files
------------------------------------------------
-.. index:: fpathconf
-.. index:: gets configuration values for files
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int fpathconf(
- int filedes,
- int name
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- Invalid argument
-
-*EACCES*
- Permission to write the file is denied
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
- is in effect.
-
-*ENOENT*
- A file or directory does not exist
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory whan a
- directory was expected.
-
-**DESCRIPTION:**
-
-``pathconf()`` gets a value for the configuration option ``name``
-for the open file descriptor ``filedes``.
-
-The possible values for name are:
-
-*_PC_LINK_MAX*
- returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
- directory. The corresponding macro is _POSIX_LINK_MAX.
-
-*_PC_MAX_CANON*
- returns the maximum length of a formatted input line, where ``filedes``
- or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
-
-*_PC_MAX_INPUT*
- returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
-
-*_PC_NAME_MAX*
- returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
- is ``_POSIX_NAME_MAX``.
-
-*_PC_PATH_MAX*
- returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
- is ``_POSIX_PATH_MAX``.
-
-*_PC_PIPE_BUF*
- returns the size of the pipe buffer, where ``filedes`` must refer to a
- pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
- is ``_POSIX_PIPE_BUF``.
-
-*_PC_CHOWN_RESTRICTED*
- returns nonzero if the ``chown()`` call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
- files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
-
-**NOTES:**
-
-NONE
-
-mknod - create a directory
---------------------------
-.. index:: mknod
-.. index:: create a directory
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- #include <fcntl.h>
- #include <sys/types.h>
- #include <sys/stat.h>
- long mknod(
- const char \*pathname,
- mode_t mode,
- dev_t dev
- );
-
-**STATUS CODES:**
-
-``mknod`` returns zero on success, or -1 if an error occurred (in which case,
-errno is set appropriately).
-
-*ENAMETOOLONG*
- ``pathname`` was too long.
-
-*ENOENT*
- A directory component in ``pathname`` does not exist or is a dangling symbolic
- link.
-
-*ENOTDIR*
- A component used in the directory ``pathname`` is not, in fact, a directory.
-
-*ENOMEM*
- Insufficient kernel memory was available
-
-*EROFS*
- ``pathname`` refers to a file on a read-only filesystem.
-
-*ELOOP*
- ``pathname`` contains a reference to a circular symbolic link, ie a symbolic
- link whose expansion contains a reference to itself.
-
-*ENOSPC*
- The device containing ``pathname`` has no room for the new node.
-
-**DESCRIPTION:**
-
-``mknod`` attempts to create a filesystem node (file, device special file or
-named pipe) named ``pathname``, specified by ``mode`` and ``dev``.
-
-``mode`` specifies both the permissions to use and the type of node to be created.
-
-It should be a combination (using bitwise OR) of one of the file types listed
-below and the permissions for the new node.
-
-The permissions are modified by the process’s ``umask`` in the usual way: the
-permissions of the created node are ``(mode & ~umask)``.
-
-The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and``S_IFIFO`` to specify a normal file (which will be created empty), character
-special file, block special file or FIFO (named pipe), respectively, or zero, which
-will create a normal file.
-
-If the file type is ``S_IFCHR`` or ``S_IFBLK`` then ``dev`` specifies the major
-and minor numbers of the newly created device special file; otherwise it is ignored.
-
-The newly created node will be owned by the effective uid of the process. If the
-directory containing the node has the set group id bit set, or if the filesystem
-is mounted with BSD group semantics, the new node will inherit the group ownership
-from its parent directory; otherwise it will be owned by the effective gid of the
-process.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Input and Output Primitives Manager
-###################################
-
-Introduction
-============
-
-The input and output primitives manager is ...
-
-The directives provided by the input and output primitives manager are:
-
-- ``pipe`` - Create an Inter-Process Channel
-
-- ``dup`` - Duplicates an open file descriptor
-
-- ``dup2`` - Duplicates an open file descriptor
-
-- ``close`` - Closes a file
-
-- ``read`` - Reads from a file
-
-- ``write`` - Writes to a file
-
-- ``fcntl`` - Manipulates an open file descriptor
-
-- ``lseek`` - Reposition read/write file offset
-
-- ``fsync`` - Synchronize file complete in-core state with that on disk
-
-- ``fdatasync`` - Synchronize file in-core data with that on disk
-
-- ``sync`` - Schedule file system updates
-
-- ``mount`` - Mount a file system
-
-- ``unmount`` - Unmount file systems
-
-- ``readv`` - Vectored read from a file
-
-- ``writev`` - Vectored write to a file
-
-- ``aio_read`` - Asynchronous Read
-
-- ``aio_write`` - Asynchronous Write
-
-- ``lio_listio`` - List Directed I/O
-
-- ``aio_error`` - Retrieve Error Status of Asynchronous I/O Operation
-
-- ``aio_return`` - Retrieve Return Status Asynchronous I/O Operation
-
-- ``aio_cancel`` - Cancel Asynchronous I/O Request
-
-- ``aio_suspend`` - Wait for Asynchronous I/O Request
-
-- ``aio_fsync`` - Asynchronous File Synchronization
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the input and output primitives 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.
-
-pipe - Create an Inter-Process Channel
---------------------------------------
-.. index:: pipe
-.. index:: create an inter
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pipe(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-dup - Duplicates an open file descriptor
-----------------------------------------
-.. index:: dup
-.. index:: duplicates an open file descriptor
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int dup(
- int fildes
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor.
-
-*EINTR*
- Function was interrupted by a signal.
-
-*EMFILE*
- The process already has the maximum number of file descriptors open
- and tried to open a new one.
-
-**DESCRIPTION:**
-
-The ``dup`` function returns the lowest numbered available file
-descriptor. This new desciptor refers to the same open file as the
-original descriptor and shares any locks.
-
-**NOTES:**
-
-NONE
-
-dup2 - Duplicates an open file descriptor
------------------------------------------
-.. index:: dup2
-.. index:: duplicates an open file descriptor
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int dup2(
- int fildes,
- int fildes2
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor.
-
-*EINTR*
- Function was interrupted by a signal.
-
-*EMFILE*
- The process already has the maximum number of file descriptors open
- and tried to open a new one.
-
-**DESCRIPTION:**
-
-``dup2`` creates a copy of the file descriptor ``oldfd``.
-
-The old and new descriptors may be used interchangeably. They share locks, file
-position pointers and flags; for example, if the file position is modified by using``lseek`` on one of the descriptors, the position is also changed for the other.
-
-**NOTES:**
-
-NONE
-
-close - Closes a file
----------------------
-.. index:: close
-.. index:: closes a file.
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int close(
- int fildes
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-*EINTR*
- Function was interrupted by a signal.
-
-**DESCRIPTION:**
-
-The ``close()`` function deallocates the file descriptor named by``fildes`` and makes it available for reuse. All outstanding
-record locks owned by this process for the file are unlocked.
-
-**NOTES:**
-
-A signal can interrupt the ``close()`` function. In that case,``close()`` returns -1 with ``errno`` set to EINTR. The file
-may or may not be closed.
-
-read - Reads from a file
-------------------------
-.. index:: read
-.. index:: reads from a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int read(
- int fildes,
- void \*buf,
- unsigned int nbyte
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets ``errno`` to one of
-the following:
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EINTR*
- Function was interrupted by a signal.
-
-*EIO*
- Input or output error
-
-*EINVAL*
- Bad buffer pointer
-
-**DESCRIPTION:**
-
-The ``read()`` function reads ``nbyte`` bytes from the file
-associated with ``fildes`` into the buffer pointed to by ``buf``.
-
-The ``read()`` function returns the number of bytes actually read
-and placed in the buffer. This will be less than ``nbyte`` if:
-
-- The number of bytes left in the file is less than ``nbyte``.
-
-- The ``read()`` request was interrupted by a signal.
-
-- The file is a pipe or FIFO or special file with less than ``nbytes``
- immediately available for reading.
-
-When attempting to read from any empty pipe or FIFO:
-
-- If no process has the pipe open for writing, zero is returned to
- indicate end-of-file.
-
-- If some process has the pipe open for writing and O_NONBLOCK is set,
- -1 is returned and ``errno`` is set to EAGAIN.
-
-- If some process has the pipe open for writing and O_NONBLOCK is clear,``read()`` waits for some data to be written or the pipe to be closed.
-
-When attempting to read from a file other than a pipe or FIFO and no data
-is available.
-
-- If O_NONBLOCK is set, -1 is returned and ``errno`` is set to EAGAIN.
-
-- If O_NONBLOCK is clear, ``read()`` waits for some data to become
- available.
-
-- The O_NONBLOCK flag is ignored if data is available.
-
-**NOTES:**
-
-NONE
-
-write - Writes to a file
-------------------------
-.. index:: write
-.. index:: writes to a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- int write(
- int fildes,
- const void \*buf,
- unsigned int nbytes
- );
-
-**STATUS CODES:**
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EFBIG*
- An attempt was made to write to a file that exceeds the maximum file
- size
-
-*EINTR*
- The function was interrupted by a signal.
-
-*EIO*
- Input or output error.
-
-*ENOSPC*
- No space left on disk.
-
-*EPIPE*
- Attempt to write to a pope or FIFO with no reader.
-
-*EINVAL*
- Bad buffer pointer
-
-**DESCRIPTION:**
-
-The ``write()`` function writes ``nbyte`` from the array pointed
-to by ``buf`` into the file associated with ``fildes``.
-
-If ``nybte`` is zero and the file is a regular file, the ``write()``
-function returns zero and has no other effect. If ``nbyte`` is zero
-and the file is a special file, te results are not portable.
-
-The ``write()`` function returns the number of bytes written. This
-number will be less than ``nbytes`` if there is an error. It will never
-be greater than ``nbytes``.
-
-**NOTES:**
-
-NONE
-
-fcntl - Manipulates an open file descriptor
--------------------------------------------
-.. index:: fcntl
-.. index:: manipulates an open file descriptor
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <fcntl.h>
- #include <unistd.h>
- int fcntl(
- int fildes,
- int cmd
- );
-
-**STATUS CODES:**
-
-*EACCESS*
- Search permission is denied for a direcotry in a file’s path
- prefix.
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EDEADLK*
- An ``fcntl`` with function F_SETLKW would cause a deadlock.
-
-*EINTR*
- The functioin was interrupted by a signal.
-
-*EINVAL*
- Invalid argument
-
-*EMFILE*
- Too many file descriptor or in use by the process.
-
-*ENOLCK*
- No locks available
-
-**DESCRIPTION:**
-
-``fcntl()`` performs one of various miscellaneous operations on``fd``. The operation in question is determined by ``cmd``:
-
-*F_DUPFD*
- Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary.
- The same functionality can be more easily achieved by using ``dup2()``.
- The old and new descriptors may be used interchangeably. They share locks,
- file position pointers and flags; for example, if the file position is
- modified by using ``lseek()`` on one of the descriptors, the position is
- also changed for the other.
- The two descriptors do not share the close-on-exec flag, however. The
- close-on-exec flag of the copy is off, meaning that it will be closed on
- exec.
- On success, the new descriptor is returned.
-
-*F_GETFD*
- Read the close-on-exec flag. If the low-order bit is 0, the file will
- remain open across exec, otherwise it will be closed.
-
-*F_SETFD*
- Set the close-on-exec flag to the value specified by ``arg`` (only the least
- significant bit is used).
-
-*F_GETFL*
- Read the descriptor’s flags (all flags (as set by open()) are returned).
-
-*F_SETFL*
- Set the descriptor’s flags to the value specified by ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set.
- The flags are shared between copies (made with ``dup()`` etc.) of the same
- file descriptor.
- The flags and their semantics are described in ``open()``.
-
-*F_GETLK, F_SETLK and F_SETLKW*
- Manage discretionary file locks. The third argument ``arg`` is a pointer to a
- struct flock (that may be overwritten by this call).
-
-*F_GETLK*
- Return the flock structure that prevents us from obtaining the lock, or set the``l_type`` field of the lock to ``F_UNLCK`` if there is no obstruction.
-
-*F_SETLK*
- The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or
- cleared (when it is ``F_UNLCK``. If lock is held by someone else, this
- call returns -1 and sets ``errno`` to EACCES or EAGAIN.
-
-*F_SETLKW*
- Like ``F_SETLK``, but instead of returning an error we wait for the lock to
- be released.
-
-*F_GETOWN*
- Get the process ID (or process group) of the owner of a socket.
- Process groups are returned as negative values.
-
-*F_SETOWN*
- Set the process or process group that owns a socket.
- For these commands, ownership means receiving ``SIGIO`` or ``SIGURG``
- signals.
- Process groups are specified using negative values.
-
-**NOTES:**
-
-The errors returned by ``dup2`` are different from those returned by``F_DUPFD``.
-
-lseek - Reposition read/write file offset
------------------------------------------
-.. index:: lseek
-.. index:: reposition read/write file offset
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/types.h>
- #include <unistd.h>
- int lseek(
- int fildes,
- off_t offset,
- int whence
- );
-
-**STATUS CODES:**
-
-*EBADF*
- ``fildes`` is not an open file descriptor.
-
-*ESPIPE*
- ``fildes`` is associated with a pipe, socket or FIFO.
-
-*EINVAL*
- ``whence`` is not a proper value.
-
-**DESCRIPTION:**
-
-The ``lseek`` function repositions the offset of the file descriptor``fildes`` to the argument offset according to the directive whence.
-The argument ``fildes`` must be an open file descriptor. ``Lseek``
-repositions the file pointer fildes as follows:
-
-- If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes.
-
-- If ``whence`` is SEEK_CUR, the offset is set to its current location
- plus offset bytes.
-
-- If ``whence`` is SEEK_END, the offset is set to the size of the
- file plus ``offset`` bytes.
-
-The ``lseek`` function allows the file offset to be set beyond the end
-of the existing end-of-file of the file. If data is later written at this
-point, subsequent reads of the data in the gap return bytes of zeros
-(until data is actually written into the gap).
-
-Some devices are incapable of seeking. The value of the pointer associated
-with such a device is undefined.
-
-**NOTES:**
-
-NONE
-
-fsync - Synchronize file complete in-core state with that on disk
------------------------------------------------------------------
-.. index:: fsync
-.. index:: synchronize file complete in
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int fsync(
- int fd
- );
-
-**STATUS CODES:**
-
-On success, zero is returned. On error, -1 is returned, and ``errno``
-is set appropriately.
-
-*EBADF*
- ``fd`` is not a valid descriptor open for writing
-
-*EINVAL*
- ``fd`` is bound to a special file which does not support support synchronization
-
-*EROFS*
- ``fd`` is bound to a special file which does not support support synchronization
-
-*EIO*
- An error occurred during synchronization
-
-**DESCRIPTION:**
-
-``fsync`` copies all in-core parts of a file to disk.
-
-**NOTES:**
-
-NONE
-
-fdatasync - Synchronize file in-core data with that on disk
------------------------------------------------------------
-.. index:: fdatasync
-.. index:: synchronize file in
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int fdatasync(
- int fd
- );
-
-**STATUS CODES:**
-
-On success, zero is returned. On error, -1 is returned, and ``errno`` is
-set appropriately.
-
-*EBADF*
- ``fd`` is not a valid file descriptor open for writing.
-
-*EINVAL*
- ``fd`` is bound to a special file which does not support synchronization.
-
-*EIO*
- An error occurred during synchronization.
-
-*EROFS*
- ``fd`` is bound to a special file which dows not support synchronization.
-
-**DESCRIPTION:**
-
-``fdatasync`` flushes all data buffers of a file to disk (before the system call
-returns). It resembles ``fsync`` but is not required to update the metadata such
-as access time.
-
-Applications that access databases or log files often write a tiny data fragment
-(e.g., one line in a log file) and then call ``fsync`` immediately in order to
-ensure that the written data is physically stored on the harddisk. Unfortunately,
-fsync will always initiate two write operations: one for the newly written data and
-another one in order to update the modification time stored in the inode. If the
-modification time is not a part of the transaction concept ``fdatasync`` can be
-used to avoid unnecessary inode disk write operations.
-
-**NOTES:**
-
-NONE
-
-sync - Schedule file system updates
------------------------------------
-.. index:: sync
-.. index:: synchronize file systems
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- void sync(void);
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-The ``sync`` service causes all information in memory that updates
-file systems to be scheduled for writing out to all file systems.
-
-**NOTES:**
-
-The writing of data to the file systems is only guaranteed to be
-scheduled upon return. It is not necessarily complete upon return
-from ``sync``.
-
-mount - Mount a file system
----------------------------
-.. index:: mount
-.. index:: mount a file system
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <libio.h>
- int mount(
- rtems_filesystem_mount_table_entry_t \**mt_entry,
- rtems_filesystem_operations_table \*fs_ops,
- rtems_filesystem_options_t fsoptions,
- char \*device,
- char \*mount_point
- );
-
-**STATUS CODES:**
-
-*EXXX*
-
-**DESCRIPTION:**
-
-The ``mount`` routines mounts the filesystem class
-which uses the filesystem operations specified by ``fs_ops``
-and ``fsoptions``. The filesystem is mounted at the directory``mount_point`` and the mode of the mounted filesystem is
-specified by ``fsoptions``. If this filesystem class requires
-a device, then the name of the device must be specified by ``device``.
-
-If this operation succeeds, the mount table entry for the mounted
-filesystem is returned in ``mt_entry``.
-
-**NOTES:**
-
-NONE
-
-unmount - Unmount file systems
-------------------------------
-.. index:: unmount
-.. index:: unmount file systems
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <libio.h>
- int unmount(
- const char \*mount_path
- );
-
-**STATUS CODES:**
-
-*EXXX*
-
-**DESCRIPTION:**
-
-The ``unmount`` routine removes the attachment of the filesystem specified
-by ``mount_path``.
-
-**NOTES:**
-
-NONE
-
-readv - Vectored read from a file
----------------------------------
-.. index:: readv
-.. index:: vectored read from a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/uio.h>
- ssize_t readv(
- int fd,
- const struct iovec \*iov,
- int iovcnt
- );
-
-**STATUS CODES:**
-
-In addition to the errors detected by``Input and Output Primitives Manager read - Reads from a file, read()``,
-this routine may return -1 and sets ``errno`` based upon the following
-errors:
-
-*EINVAL*
- The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
-
-*EINVAL*
- The ``iovcnt`` argument was less than or equal to 0, or greater
- than ``IOV_MAX``.
-
-**DESCRIPTION:**
-
-The ``readv()`` function is equivalent to ``read()``
-except as described here. The ``readv()`` function shall place
-the input data into the ``iovcnt`` buffers specified by the
-members of the ``iov`` array: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
-
-Each ``iovec`` entry specifies the base address and length of an area
-in memory where data should be placed. The ``readv()`` function
-always fills an area completely before proceeding to the next.
-
-**NOTES:**
-
-NONE
-
-writev - Vectored write to a file
----------------------------------
-.. index:: writev
-.. index:: vectored write to a file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/uio.h>
- ssize_t writev(
- int fd,
- const struct iovec \*iov,
- int iovcnt
- );
-
-**STATUS CODES:**
-
-In addition to the errors detected by``Input and Output Primitives Manager write - Write to a file, write()``,
-this routine may return -1 and sets ``errno`` based upon the following
-errors:
-
-*EINVAL*
- The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
-
-*EINVAL*
- The ``iovcnt`` argument was less than or equal to 0, or greater
- than ``IOV_MAX``.
-
-**DESCRIPTION:**
-
-The ``writev()`` function is equivalent to ``write()``,
-except as noted here. The ``writev()`` function gathers output
-data from the ``iovcnt`` buffers specified by the members of
-the ``iov array``: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
-The ``iovcnt`` argument is valid if greater than 0 and less
-than or equal to ``IOV_MAX``.
-
-Each ``iovec`` entry specifies the base address and length of
-an area in memory from which data should be written. The ``writev()``
-function always writes a complete area before proceeding to the next.
-
-If ``fd`` refers to a regular file and all of the ``iov_len``
-members in the array pointed to by ``iov`` are 0, ``writev()``
-returns 0 and has no other effect. For other file types, the behavior
-is unspecified by POSIX.
-
-**NOTES:**
-
-NONE
-
-aio_read - Asynchronous Read
-----------------------------
-.. index:: aio_read
-.. index:: asynchronous read
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_read(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-aio_write - Asynchronous Write
-------------------------------
-.. index:: aio_write
-.. index:: asynchronous write
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_write(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-lio_listio - List Directed I/O
-------------------------------
-.. index:: lio_listio
-.. index:: list directed i/o
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int lio_listio(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-aio_error - Retrieve Error Status of Asynchronous I/O Operation
----------------------------------------------------------------
-.. index:: aio_error
-.. index:: retrieve error status of asynchronous i/o operation
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_error(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-aio_return - Retrieve Return Status Asynchronous I/O Operation
---------------------------------------------------------------
-.. index:: aio_return
-.. index:: retrieve return status asynchronous i/o operation
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_return(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-aio_cancel - Cancel Asynchronous I/O Request
---------------------------------------------
-.. index:: aio_cancel
-.. index:: cancel asynchronous i/o request
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_cancel(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-aio_suspend - Wait for Asynchronous I/O Request
------------------------------------------------
-.. index:: aio_suspend
-.. index:: wait for asynchronous i/o request
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_suspend(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-aio_fsync - Asynchronous File Synchronization
----------------------------------------------
-.. index:: aio_fsync
-.. index:: asynchronous file synchronization
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int aio_fsync(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Device- and Class- Specific Functions Manager
-#############################################
-
-Introduction
-============
-
-The device- and class- specific functions manager is ...
-
-The directives provided by the device- and class- specific functions
-manager are:
-
-- ``cfgetispeed`` - Reads terminal input baud rate
-
-- ``cfgetospeed`` - Reads terminal output baud rate
-
-- ``cfsetispeed`` - Sets terminal input baud rate
-
-- ``cfsetospeed`` - Set terminal output baud rate
-
-- ``tcgetattr`` - Gets terminal attributes
-
-- ``tcsetattr`` - Set terminal attributes
-
-- ``tcsendbreak`` - Sends a break to a terminal
-
-- ``tcdrain`` - Waits for all output to be transmitted to the terminal
-
-- ``tcflush`` - Discards terminal data
-
-- ``tcflow`` - Suspends/restarts terminal output
-
-- ``tcgetpgrp`` - Gets foreground process group ID
-
-- ``tcsetpgrp`` - Sets foreground process group ID
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the device- and class- specific functions 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.
-
-cfgetispeed - Reads terminal input baud rate
---------------------------------------------
-.. index:: cfgetispeed
-.. index:: reads terminal input baud rate
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- int cfgetispeed(
- const struct termios \*p
- );
-
-**STATUS CODES:**
-
-The ``cfgetispeed()`` function returns a code for baud rate.
-
-**DESCRIPTION:**
-
-The ``cfsetispeed()`` function stores a code for the terminal speed
-stored in a struct termios. The codes are defined in ``<termios.h>``
-by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
-B1800, B2400, B4800, B9600, B19200, and B38400.
-
-The ``cfsetispeed()`` function does not do anything to the hardware.
-It merely stores a value for use by ``tcsetattr()``.
-
-**NOTES:**
-
-Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
-number returned for any given speed may change from system to system.
-
-cfgetospeed - Reads terminal output baud rate
----------------------------------------------
-.. index:: cfgetospeed
-.. index:: reads terminal output baud rate
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- int cfgetospeed(
- const struct termios \*p
- );
-
-**STATUS CODES:**
-
-The ``cfgetospeed()`` function returns the termios code for the baud rate.
-
-**DESCRIPTION:**
-
-The ``cfgetospeed()`` function returns a code for the terminal speed
-stored in a ``struct termios``. The codes are defined in ``<termios.h>``
-by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800,
-B2400, B4800, B9600, B19200, and B38400.
-
-The ``cfgetospeed()`` function does not do anything to the hardware.
-It merely returns the value stored by a previous call to ``tcgetattr()``.
-
-**NOTES:**
-
-Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
-number returned for any given speed may change from system to system.
-
-cfsetispeed - Sets terminal input baud rate
--------------------------------------------
-.. index:: cfsetispeed
-.. index:: sets terminal input baud rate
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- int cfsetispeed(
- struct termios \*p,
- speed_t speed
- );
-
-**STATUS CODES:**
-
-The ``cfsetispeed()`` function returns a zero when successful and
-returns -1 when an error occurs.
-
-**DESCRIPTION:**
-
-The ``cfsetispeed()`` function stores a code for the terminal speed
-stored in a struct termios. The codes are defined in ``<termios.h>``
-by the macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
-B1800, B2400, B4800, B9600, B19200, and B38400.
-
-**NOTES:**
-
-This function merely stores a value in the ``termios`` structure. It
-does not change the terminal speed until a ``tcsetattr()`` is done.
-It does not detect impossible terminal speeds.
-
-cfsetospeed - Sets terminal output baud rate
---------------------------------------------
-.. index:: cfsetospeed
-.. index:: sets terminal output baud rate
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- int cfsetospeed(
- struct termios \*p,
- speed_t speed
- );
-
-**STATUS CODES:**
-
-The ``cfsetospeed()`` function returns a zero when successful and
-returns -1 when an error occurs.
-
-**DESCRIPTION:**
-
-The ``cfsetospeed()`` function stores a code for the terminal speed stored
-in a struct ``termios``. The codes are defiined in ``<termios.h>`` by the
-macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400,
-B4800, B9600, B19200, and B38400.
-
-The ``cfsetospeed()`` function does not do anything to the hardware. It
-merely stores a value for use by ``tcsetattr()``.
-
-**NOTES:**
-
-This function merely stores a value in the ``termios`` structure.
-It does not change the terminal speed until a ``tcsetattr()`` is done.
-It does not detect impossible terminal speeds.
-
-tcgetattr - Gets terminal attributes
-------------------------------------
-.. index:: tcgetattr
-.. index:: gets terminal attributes
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- #include <unistd.h>
- int tcgetattr(
- int fildes,
- struct termios \*p
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-*ENOOTY*
- Terminal control function attempted for a file that is not a terminal.
-
-**DESCRIPTION:**
-
-The ``tcgetattr()`` gets the parameters associated with the terminal
-referred to by ``fildes`` and stores them into the ``termios()``
-structure pointed to by ``termios_p``.
-
-**NOTES:**
-
-NONE
-
-tcsetattr - Set terminal attributes
------------------------------------
-.. index:: tcsetattr
-.. index:: set terminal attributes
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- #include <unistd.h>
- int tcsetattr(
- int fildes,
- int options,
- const struct termios \*tp
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-tcsendbreak - Sends a break to a terminal
------------------------------------------
-.. index:: tcsendbreak
-.. index:: sends a break to a terminal
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int tcsendbreak(
- int fd
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-tcdrain - Waits for all output to be transmitted to the terminal.
------------------------------------------------------------------
-.. index:: tcdrain
-.. index:: waits for all output to be transmitted to the terminal.
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <termios.h>
- #include <unistd.h>
- int tcdrain(
- int fildes
- );
-
-**STATUS CODES:**
-
-*EBADF*
- Invalid file descriptor
-
-*EINTR*
- Function was interrupted by a signal
-
-*ENOTTY*
- Terminal control function attempted for a file that is not a terminal.
-
-**DESCRIPTION:**
-
-The ``tcdrain()`` function waits until all output written to``fildes`` has been transmitted.
-
-**NOTES:**
-
-NONE
-
-tcflush - Discards terminal data
---------------------------------
-.. index:: tcflush
-.. index:: discards terminal data
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int tcflush(
- int fd
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-tcflow - Suspends/restarts terminal output.
--------------------------------------------
-.. index:: tcflow
-.. index:: suspends/restarts terminal output.
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int tcflow(
- int fd
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-tcgetpgrp - Gets foreground process group ID
---------------------------------------------
-.. index:: tcgetpgrp
-.. index:: gets foreground process group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int tcgetpgrp(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-tcsetpgrp - Sets foreground process group ID
---------------------------------------------
-.. index:: tcsetpgrp
-.. index:: sets foreground process group id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int tcsetpgrp(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Language-Specific Services for the C Programming Language Manager
-#################################################################
-
-Introduction
-============
-
-The
-language-specific services for the C programming language manager is ...
-
-The directives provided by the language-specific services for the C programming language manager are:
-
-- ``setlocale`` - Set the Current Locale
-
-- ``fileno`` - Obtain File Descriptor Number for this File
-
-- ``fdopen`` - Associate Stream with File Descriptor
-
-- ``flockfile`` - Acquire Ownership of File Stream
-
-- ``ftrylockfile`` - Poll to Acquire Ownership of File Stream
-
-- ``funlockfile`` - Release Ownership of File Stream
-
-- ``getc_unlocked`` - Get Character without Locking
-
-- ``getchar_unlocked`` - Get Character from stdin without Locking
-
-- ``putc_unlocked`` - Put Character without Locking
-
-- ``putchar_unlocked`` - Put Character to stdin without Locking
-
-- ``setjmp`` - Save Context for Non-Local Goto
-
-- ``longjmp`` - Non-Local Jump to a Saved Context
-
-- ``sigsetjmp`` - Save Context with Signal Status for Non-Local Goto
-
-- ``siglongjmp`` - Non-Local Jump with Signal Status to a Saved Context
-
-- ``tzset`` - Initialize Time Conversion Information
-
-- ``strtok_r`` - Reentrant Extract Token from String
-
-- ``asctime_r`` - Reentrant struct tm to ASCII Time Conversion
-
-- ``ctime_r`` - Reentrant time_t to ASCII Time Conversion
-
-- ``gmtime_r`` - Reentrant UTC Time Conversion
-
-- ``localtime_r`` - Reentrant Local Time Conversion
-
-- ``rand_r`` - Reentrant Random Number Generation
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the language-specific services for the C programming language 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.
-
-setlocale - Set the Current Locale
-----------------------------------
-.. index:: setlocale
-.. index:: set the current locale
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int setlocale(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-fileno - Obtain File Descriptor Number for this File
-----------------------------------------------------
-.. index:: fileno
-.. index:: obtain file descriptor number for this file
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int fileno(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-fdopen - Associate Stream with File Descriptor
-----------------------------------------------
-.. index:: fdopen
-.. index:: associate stream with file descriptor
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int fdopen(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-flockfile - Acquire Ownership of File Stream
---------------------------------------------
-.. index:: flockfile
-.. index:: acquire ownership of file stream
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int flockfile(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-ftrylockfile - Poll to Acquire Ownership of File Stream
--------------------------------------------------------
-.. index:: ftrylockfile
-.. index:: poll to acquire ownership of file stream
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int ftrylockfile(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-funlockfile - Release Ownership of File Stream
-----------------------------------------------
-.. index:: funlockfile
-.. index:: release ownership of file stream
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int funlockfile(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getc_unlocked - Get Character without Locking
----------------------------------------------
-.. index:: getc_unlocked
-.. index:: get character without locking
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getc_unlocked(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getchar_unlocked - Get Character from stdin without Locking
------------------------------------------------------------
-.. index:: getchar_unlocked
-.. index:: get character from stdin without locking
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getchar_unlocked(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-putc_unlocked - Put Character without Locking
----------------------------------------------
-.. index:: putc_unlocked
-.. index:: put character without locking
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int putc_unlocked(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-putchar_unlocked - Put Character to stdin without Locking
----------------------------------------------------------
-.. index:: putchar_unlocked
-.. index:: put character to stdin without locking
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int putchar_unlocked(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-setjmp - Save Context for Non-Local Goto
-----------------------------------------
-.. index:: setjmp
-.. index:: save context for non
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int setjmp(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-longjmp - Non-Local Jump to a Saved Context
--------------------------------------------
-.. index:: longjmp
-.. index:: non
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int longjmp(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-sigsetjmp - Save Context with Signal Status for Non-Local Goto
---------------------------------------------------------------
-.. index:: sigsetjmp
-.. index:: save context with signal status for non
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sigsetjmp(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-siglongjmp - Non-Local Jump with Signal Status to a Saved Context
------------------------------------------------------------------
-.. index:: siglongjmp
-.. index:: non
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int siglongjmp(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-tzset - Initialize Time Conversion Information
-----------------------------------------------
-.. index:: tzset
-.. index:: initialize time conversion information
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int tzset(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-strtok_r - Reentrant Extract Token from String
-----------------------------------------------
-.. index:: strtok_r
-.. index:: reentrant extract token from string
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int strtok_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-asctime_r - Reentrant struct tm to ASCII Time Conversion
---------------------------------------------------------
-.. index:: asctime_r
-.. index:: reentrant struct tm to ascii time conversion
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int asctime_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-ctime_r - Reentrant time_t to ASCII Time Conversion
----------------------------------------------------
-.. index:: ctime_r
-.. index:: reentrant time_t to ascii time conversion
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int ctime_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-gmtime_r - Reentrant UTC Time Conversion
-----------------------------------------
-.. index:: gmtime_r
-.. index:: reentrant utc time conversion
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int gmtime_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-localtime_r - Reentrant Local Time Conversion
----------------------------------------------
-.. index:: localtime_r
-.. index:: reentrant local time conversion
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int localtime_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-rand_r - Reentrant Random Number Generation
--------------------------------------------
-.. index:: rand_r
-.. index:: reentrant random number generation
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int rand_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-System Databases Manager
-########################
-
-Introduction
-============
-
-The
-system databases manager is ...
-
-The directives provided by the system databases manager are:
-
-- ``getgrgid`` - Get Group File Entry for ID
-
-- ``getgrgid_r`` - Reentrant Get Group File Entry
-
-- ``getgrnam`` - Get Group File Entry for Name
-
-- ``getgrnam_r`` - Reentrant Get Group File Entry for Name
-
-- ``getpwuid`` - Get Password File Entry for UID
-
-- ``getpwuid_r`` - Reentrant Get Password File Entry for UID
-
-- ``getpwnam`` - Get Password File Entry for Name
-
-- ``getpwnam_r`` - Reentrant Get Password File Entry for Name
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the system databases 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.
-
-getgrgid - Get Group File Entry for ID
---------------------------------------
-.. index:: getgrgid
-.. index:: get group file entry for id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getgrgid(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getgrgid_r - Reentrant Get Group File Entry
--------------------------------------------
-.. index:: getgrgid_r
-.. index:: reentrant get group file entry
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getgrgid_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getgrnam - Get Group File Entry for Name
-----------------------------------------
-.. index:: getgrnam
-.. index:: get group file entry for name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getgrnam(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getgrnam_r - Reentrant Get Group File Entry for Name
-----------------------------------------------------
-.. index:: getgrnam_r
-.. index:: reentrant get group file entry for name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getgrnam_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getpwuid - Get Password File Entry for UID
-------------------------------------------
-.. index:: getpwuid
-.. index:: get password file entry for uid
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getpwuid(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getpwuid_r - Reentrant Get Password File Entry for UID
-------------------------------------------------------
-.. index:: getpwuid_r
-.. index:: reentrant get password file entry for uid
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getpwuid_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getpwnam - Password File Entry for Name
----------------------------------------
-.. index:: getpwnam
-.. index:: password file entry for name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getpwnam(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-getpwnam_r - Reentrant Get Password File Entry for Name
--------------------------------------------------------
-.. index:: getpwnam_r
-.. index:: reentrant get password file entry for name
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int getpwnam_r(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT(c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation(OAR).
-
-.. COMMENT: All rights reserved.
-
-Semaphore Manager
-#################
-
-Introduction
-============
-
-The semaphore manager provides functions to allocate, delete, and control
-semaphores. This manager is based on the POSIX 1003.1 standard.
-
-The directives provided by the semaphore manager are:
-
-- ``sem_init`` - Initialize an unnamed semaphore
-
-- ``sem_destroy`` - Destroy an unnamed semaphore
-
-- ``sem_open`` - Open a named semaphore
-
-- ``sem_close`` - Close a named semaphore
-
-- ``sem_unlink`` - Remove a named semaphore
-
-- ``sem_wait`` - Lock a semaphore
-
-- ``sem_trywait`` - Lock a semaphore
-
-- ``sem_timedwait`` - Wait on a Semaphore for a Specified Time
-
-- ``sem_post`` - Unlock a semaphore
-
-- ``sem_getvalue`` - Get the value of a semeaphore
-
-Background
-==========
-
-Theory
-------
-
-Semaphores are used for synchronization and mutual exclusion by indicating the
-availability and number of resources. The task (the task which is returning
-resources) notifying other tasks of an event increases the number of resources
-held by the semaphore by one. The task (the task which will obtain resources)
-waiting for the event decreases the number of resources held by the semaphore
-by one. If the number of resources held by a semaphore is insufficient (namely
-0), the task requiring resources will wait until the next time resources are
-returned to the semaphore. If there is more than one task waiting for a
-semaphore, the tasks will be placed in the queue.
-
-"sem_t" Structure
------------------
-.. index:: sem_t
-
-The ``sem_t`` structure is used to represent semaphores. It is passed as an
-argument to the semaphore directives and is defined as follows:
-.. code:: c
-
- typedef int sem_t;
-
-Building a Semaphore Attribute Set
-----------------------------------
-
-Operations
-==========
-
-Using as a Binary Semaphore
----------------------------
-
-Although POSIX supports mutexes, they are only visible between threads. To work
-between processes, a binary semaphore must be used.
-
-Creating a semaphore with a limit on the count of 1 effectively restricts the
-semaphore to being a binary semaphore. When the binary semaphore is available,
-the count is 1. When the binary semaphore is unavailable, the count is 0.
-
-Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available.
-
-There is currently no text in this section.
-
-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.
-
-sem_init - Initialize an unnamed semaphore
-------------------------------------------
-.. index:: sem_init
-.. index:: initialize an unnamed semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_init(
- sem_t \*sem,
- int pshared,
- unsigned int value
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The value argument exceeds SEM_VALUE_MAX
-
-*ENOSPC*
- A resource required to initialize the semaphore has been exhausted
- The limit on semaphores (SEM_VALUE_MAX) has been reached
-
-*ENOSYS*
- The function sem_init is not supported by this implementation
-
-*EPERM*
- The process lacks appropriate privileges to initialize the semaphore
-
-**DESCRIPTION:**
-
-The sem_init function is used to initialize the unnamed semaphore referred to
-by "sem". The value of the initialized semaphore is the parameter "value". The
-semaphore remains valid until it is destroyed.
-
-ADD MORE HERE XXX
-
-**NOTES:**
-
-If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
-that occurred.
-
-Multiprocessing is currently not supported in this implementation.
-
-sem_destroy - Destroy an unnamed semaphore
-------------------------------------------
-.. index:: sem_destroy
-.. index:: destroy an unnamed semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_destroy(
- sem_t \*sem
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The value argument exceeds SEM_VALUE_MAX
-
-*ENOSYS*
- The function sem_init is not supported by this implementation
-
-*EBUSY*
- There are currently processes blocked on the semaphore
-
-**DESCRIPTION:**
-
-The sem_destroy function is used to destroy an unnamed semaphore refered to by
-"sem". sem_destroy can only be used on a semaphore that was created using
-sem_init.
-
-**NOTES:**
-
-If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
-that occurred.
-
-Multiprocessing is currently not supported in this implementation.
-
-sem_open - Open a named semaphore
----------------------------------
-.. index:: sem_open
-.. index:: open a named semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_open(
- const char \*name,
- int oflag
- );
-
-**ARGUMENTS:**
-
-The following flag bit may be set in oflag:
-
-``O_CREAT`` - Creates the semaphore if it does not already exist. If O_CREAT
-is set and the semaphore already exists then O_CREAT has no effect. Otherwise,
-sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth
-argument: mode and value of type mode_t and unsigned int, respectively.
-
-``O_EXCL`` - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail
-if the semaphore name exists
-
-**STATUS CODES:**
-
-*EACCES*
- Valid name specified but oflag permissions are denied, or the semaphore name
- specified does not exist and permission to create the named semaphore is denied.
-
-*EEXIST*
- O_CREAT and O_EXCL are set and the named semaphore already exists.
-
-*EINTR*
- The sem_open() operation was interrupted by a signal.
-
-*EINVAL*
- The sem_open() operation is not supported for the given name.
-
-*EMFILE*
- Too many semaphore descriptors or file descriptors in use by this process.
-
-*ENAMETOOLONG*
- The length of the name exceed PATH_MAX or name component is longer than NAME_MAX
- while POSIX_NO_TRUNC is in effect.
-
-*ENOENT*
- O_CREAT is not set and the named semaphore does not exist.
-
-*ENOSPC*
- There is insufficient space for the creation of a new named semaphore.
-
-*ENOSYS*
- The function sem_open() is not supported by this implementation.
-
-**DESCRIPTION:**
-
-The sem_open() function establishes a connection between a specified semaphore and
-a process. After a call to sem_open with a specified semaphore name, a process
-can reference to semaphore by the associated name using the address returned by
-the call. The oflag arguments listed above control the state of the semaphore by
-determining if the semaphore is created or accessed by a call to sem_open().
-
-**NOTES:**
-
-sem_close - Close a named semaphore
------------------------------------
-.. index:: sem_close
-.. index:: close a named semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_close(
- sem_t \*sem_close
- );
-
-**STATUS CODES:**
-
-*EACCES*
- The semaphore argument is not a valid semaphore descriptor.
-
-*ENOSYS*
- The function sem_close is not supported by this implementation.
-
-**DESCRIPTION:**
-
-The sem_close() function is used to indicate that the calling process is finished
-using the named semaphore indicated by sem. The function sem_close deallocates
-any system resources that were previously allocated by a sem_open system call. If
-sem_close() completes successfully it returns a 1, otherwise a value of -1 is
-return and errno is set.
-
-**NOTES:**
-
-sem_unlink - Unlink a semaphore
--------------------------------
-.. index:: sem_unlink
-.. index:: unlink a semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_unlink(
- const char \*name
- );
-
-**STATUS CODES:**
-
-*EACCESS*
- Permission is denied to unlink a semaphore.
-
-*ENAMETOOLONG*
- The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect.
-
-*ENOENT*
- The name of the semaphore does not exist.
-
-*ENOSPC*
- There is insufficient space for the creation of a new named semaphore.
-
-*ENOSYS*
- The function sem_unlink is not supported by this implementation.
-
-**DESCRIPTION:**
-
-The sem_unlink() function shall remove the semaphore name by the string name. If
-a process is currently accessing the name semaphore, the sem_unlink command has
-no effect. If one or more processes have the semaphore open when the sem_unlink
-function is called, the destruction of semaphores shall be postponed until all
-reference to semaphore are destroyed by calls to sem_close, _exit(), or exec.
-After all references have been destroyed, it returns immediately.
-
-If the termination is successful, the function shall return 0. Otherwise, a -1
-is returned and the errno is set.
-
-**NOTES:**
-
-sem_wait - Wait on a Semaphore
-------------------------------
-.. index:: sem_wait
-.. index:: wait on a semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_wait(
- sem_t \*sem
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The "sem" argument does not refer to a valid semaphore
-
-**DESCRIPTION:**
-
-This function attempts to lock a semaphore specified by ``sem``. If the
-semaphore is available, then the semaphore is locked (i.e., the semaphore
-value is decremented). If the semaphore is unavailable (i.e., the semaphore
-value is zero), then the function will block until the semaphore becomes
-available. It will then successfully lock the semaphore. The semaphore
-remains locked until released by a ``sem_post()`` call.
-
-If the call is unsuccessful, then the function returns -1 and sets errno to the
-appropriate error code.
-
-**NOTES:**
-
-Multiprocessing is not supported in this implementation.
-
-sem_trywait - Non-blocking Wait on a Semaphore
-----------------------------------------------
-.. index:: sem_trywait
-.. index:: non
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_trywait(
- sem_t \*sem
- );
-
-**STATUS CODES:**
-
-*EAGAIN*
- The semaphore is not available (i.e., the semaphore value is zero), so the
- semaphore could not be locked.
-
-*EINVAL*
- The ``sem`` argument does not refewr to a valid semaphore
-
-**DESCRIPTION:**
-
-This function attempts to lock a semaphore specified by ``sem``. If the
-semaphore is available, then the semaphore is locked (i.e., the semaphore
-value is decremented) and the function returns a value of 0. The semaphore
-remains locked until released by a ``sem_post()`` call. If the semaphore
-is unavailable (i.e., the semaphore value is zero), then the function will
-return a value of -1 immediately and set ``errno`` to EAGAIN.
-
-If the call is unsuccessful, then the function returns -1 and sets``errno`` to the appropriate error code.
-
-**NOTES:**
-
-Multiprocessing is not supported in this implementation.
-
-sem_timedwait - Wait on a Semaphore for a Specified Time
---------------------------------------------------------
-.. index:: sem_timedwait
-.. index:: wait on a semaphore for a specified time
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_timedwait(
- sem_t \*sem,
- const struct timespec \*abstime
- );
-
-**STATUS CODES:**
-
-*EAGAIN*
- The semaphore is not available (i.e., the semaphore value is zero), so the
- semaphore could not be locked.
-
-*EINVAL*
- The ``sem`` argument does not refewr to a valid semaphore
-
-**DESCRIPTION:**
-
-This function attemtps to lock a semaphore specified by ``sem``,
-and will wait for the semaphore until the absolute time specified by``abstime``. If the semaphore is available, then the semaphore is
-locked (i.e., the semaphore value is decremented) and the function
-returns a value of 0. The semaphore remains locked until released by
-a ``sem_post()`` call. If the semaphore is unavailable, then the
-function will wait for the semaphore to become available for the amount
-of time specified by ``timeout``.
-
-If the semaphore does not become available within the interval specified by``timeout``, then the function returns -1 and sets ``errno`` to EAGAIN.
-If any other error occurs, the function returns -1 and sets ``errno`` to
-the appropriate error code.
-
-**NOTES:**
-
-Multiprocessing is not supported in this implementation.
-
-sem_post - Unlock a Semaphore
------------------------------
-.. index:: sem_post
-.. index:: unlock a semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_post(
- sem_t \*sem
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The ``sem`` argument does not refer to a valid semaphore
-
-**DESCRIPTION:**
-
-This function attempts to release the semaphore specified by ``sem``. If
-other tasks are waiting on the semaphore, then one of those tasks (which one
-depends on the scheduler being used) is allowed to lock the semaphore and
-return from its ``sem_wait()``, ``sem_trywait()``, or``sem_timedwait()`` call. If there are no other tasks waiting on the
-semaphore, then the semaphore value is simply incremented. ``sem_post()``
-returns 0 upon successful completion.
-
-If an error occurs, the function returns -1 and sets ``errno`` to the
-appropriate error code.
-
-**NOTES:**
-
-Multiprocessing is not supported in this implementation.
-
-sem_getvalue - Get the value of a semaphore
--------------------------------------------
-.. index:: sem_getvalue
-.. index:: get the value of a semaphore
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int sem_getvalue(
- sem_t \*sem,
- int \*sval
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The "sem" argument does not refer to a valid semaphore
-
-*ENOSYS*
- The function sem_getvalue is not supported by this implementation
-
-**DESCRIPTION:**
-
-The sem_getvalue functions sets the location referenced by the "sval" argument
-to the value of the semaphore without affecting the state of the semaphore. The
-updated value represents a semaphore value that occurred at some point during
-the call, but is not necessarily the actual value of the semaphore when it
-returns to the calling process.
-
-If "sem" is locked, the value returned by sem_getvalue will be zero or a
-negative number whose absolute value is the number of processes waiting for the
-semaphore at some point during the call.
-
-**NOTES:**
-
-If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
-that occurred.
-
-.. COMMENT: COPYRIGHT (c) 1989-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Mutex Manager
-#############
-
-Introduction
-============
-
-The mutex manager implements the functionality required of the mutex
-manager as defined by POSIX 1003.1b-1996. This standard requires that
-a compliant operating system provide the facilties to ensure that
-threads can operate with mutual exclusion from one another and
-defines the API that must be provided.
-
-The services provided by the mutex manager are:
-
-- ``pthread_mutexattr_init`` - Initialize a Mutex Attribute Set
-
-- ``pthread_mutexattr_destroy`` - Destroy a Mutex Attribute Set
-
-- ``pthread_mutexattr_setprotocol`` - Set the Blocking Protocol
-
-- ``pthread_mutexattr_getprotocol`` - Get the Blocking Protocol
-
-- ``pthread_mutexattr_setprioceiling`` - Set the Priority Ceiling
-
-- ``pthread_mutexattr_getprioceiling`` - Get the Priority Ceiling
-
-- ``pthread_mutexattr_setpshared`` - Set the Visibility
-
-- ``pthread_mutexattr_getpshared`` - Get the Visibility
-
-- ``pthread_mutex_init`` - Initialize a Mutex
-
-- ``pthread_mutex_destroy`` - Destroy a Mutex
-
-- ``pthread_mutex_lock`` - Lock a Mutex
-
-- ``pthread_mutex_trylock`` - Poll to Lock a Mutex
-
-- ``pthread_mutex_timedlock`` - Lock a Mutex with Timeout
-
-- ``pthread_mutex_unlock`` - Unlock a Mutex
-
-- ``pthread_mutex_setprioceiling`` - Dynamically Set the Priority Ceiling
-
-- ``pthread_mutex_getprioceiling`` - Dynamically Get the Priority Ceiling
-
-Background
-==========
-
-Mutex Attributes
-----------------
-
-Mutex attributes are utilized only at mutex creation time. A mutex
-attribute structure may be initialized and passed as an argument to
-the ``mutex_init`` routine. Note that the priority ceiling of
-a mutex may be set at run-time.
-
-*blocking protcol*
- is the XXX
-
-*priority ceiling*
- is the XXX
-
-*pshared*
- is the XXX
-
-PTHREAD_MUTEX_INITIALIZER
--------------------------
-
-This is a special value that a variable of type ``pthread_mutex_t``
-may be statically initialized to as shown below:
-.. code:: c
-
- pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
-
-This indicates that ``my_mutex`` will be automatically initialized
-by an implicit call to ``pthread_mutex_init`` the first time
-the mutex is used.
-
-Note that the mutex will be initialized with default attributes.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Services
-========
-
-This section details the mutex manager’s services.
-A subsection is dedicated to each of this manager’s services
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-pthread_mutexattr_init - Initialize a Mutex Attribute Set
----------------------------------------------------------
-.. index:: pthread_mutexattr_init
-.. index:: initialize a mutex attribute set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_init(
- pthread_mutexattr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_mutexattr_init`` routine initializes the mutex attributes
-object specified by ``attr`` with the default value for all of the
-individual attributes.
-
-**NOTES:**
-
-XXX insert list of default attributes here.
-
-pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
----------------------------------------------------------
-.. index:: pthread_mutexattr_destroy
-.. index:: destroy a mutex attribute set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_destroy(
- pthread_mutexattr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-**DESCRIPTION:**
-
-The ``pthread_mutex_attr_destroy`` routine is used to destroy a mutex
-attributes object. The behavior of using an attributes object after
-it is destroyed is implementation dependent.
-
-**NOTES:**
-
-NONE
-
-pthread_mutexattr_setprotocol - Set the Blocking Protocol
----------------------------------------------------------
-.. index:: pthread_mutexattr_setprotocol
-.. index:: set the blocking protocol
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_setprotocol(
- pthread_mutexattr_t \*attr,
- int protocol
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The protocol argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_mutexattr_setprotocol`` routine is used to set value of the``protocol`` attribute. This attribute controls the order in which
-threads waiting on this mutex will receive it.
-
-The ``protocol`` can be one of the following:
-
-*``PTHREAD_PRIO_NONE``*
- in which case blocking order is FIFO.
-
-*``PTHREAD_PRIO_INHERIT``*
- in which case blocking order is priority with the priority inheritance
- protocol in effect.
-
-*``PTHREAD_PRIO_PROTECT``*
- in which case blocking order is priority with the priority ceiling
- protocol in effect.
-
-**NOTES:**
-
-There is currently no way to get simple priority blocking ordering
-with POSIX mutexes even though this could easily by supported by RTEMS.
-
-pthread_mutexattr_getprotocol - Get the Blocking Protocol
----------------------------------------------------------
-.. index:: pthread_mutexattr_getprotocol
-.. index:: get the blocking protocol
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_getprotocol(
- pthread_mutexattr_t \*attr,
- int \*protocol
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The protocol pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_mutexattr_getprotocol`` routine is used to obtain
-the value of the ``protocol`` attribute. This attribute controls
-the order in which threads waiting on this mutex will receive it.
-
-**NOTES:**
-
-NONE
-
-pthread_mutexattr_setprioceiling - Set the Priority Ceiling
------------------------------------------------------------
-.. index:: pthread_mutexattr_setprioceiling
-.. index:: set the priority ceiling
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_setprioceiling(
- pthread_mutexattr_t \*attr,
- int prioceiling
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The prioceiling argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_mutexattr_setprioceiling`` routine is used to set value of the``prioceiling`` attribute. This attribute specifies the priority that
-is the ceiling for threads obtaining this mutex. Any task obtaining this
-mutex may not be of greater priority that the ceiling. If it is of lower
-priority, then its priority will be elevated to ``prioceiling``.
-
-**NOTES:**
-
-NONE
-
-pthread_mutexattr_getprioceiling - Get the Priority Ceiling
------------------------------------------------------------
-.. index:: pthread_mutexattr_getprioceiling
-.. index:: get the priority ceiling
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_getprioceiling(
- const pthread_mutexattr_t \*attr,
- int \*prioceiling
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The prioceiling pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_mutexattr_getprioceiling`` routine is used to obtain the
-value of the ``prioceiling`` attribute. This attribute specifies the
-priority ceiling for this mutex.
-
-**NOTES:**
-
-NONE
-
-pthread_mutexattr_setpshared - Set the Visibility
--------------------------------------------------
-.. index:: pthread_mutexattr_setpshared
-.. index:: set the visibility
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_setpshared(
- pthread_mutexattr_t \*attr,
- int pshared
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The pshared argument is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutexattr_getpshared - Get the Visibility
--------------------------------------------------
-.. index:: pthread_mutexattr_getpshared
-.. index:: get the visibility
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutexattr_getpshared(
- const pthread_mutexattr_t \*attr,
- int \*pshared
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The pshared pointer argument is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_init - Initialize a Mutex
----------------------------------------
-.. index:: pthread_mutex_init
-.. index:: initialize a mutex
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_init(
- pthread_mutex_t \*mutex,
- const pthread_mutexattr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The specified protocol is invalid.
-
-*EAGAIN*
- The system lacked the necessary resources to initialize another mutex.
-
-*ENOMEM*
- Insufficient memory exists to initialize the mutex.
-
-*EBUSY*
- Attempted to reinialize the object reference by mutex, a previously
- initialized, but not yet destroyed.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_destroy - Destroy a Mutex
----------------------------------------
-.. index:: pthread_mutex_destroy
-.. index:: destroy a mutex
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_destroy(
- pthread_mutex_t \*mutex
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified mutex is invalid.
-
-*EBUSY*
- Attempted to destroy the object reference by mutex, while it is locked or
- referenced by another thread.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_lock - Lock a Mutex
----------------------------------
-.. index:: pthread_mutex_lock
-.. index:: lock a mutex
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_lock(
- pthread_mutex_t \*mutex
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified mutex is invalid.
-
-*EINVAL*
- The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
- priority of the calling thread is higher than the current priority
- ceiling.
-
-*EDEADLK*
- The current thread already owns the mutex.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_trylock - Poll to Lock a Mutex
---------------------------------------------
-.. index:: pthread_mutex_trylock
-.. index:: poll to lock a mutex
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_trylock(
- pthread_mutex_t \*mutex
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified mutex is invalid.
-
-*EINVAL*
- The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
- priority of the calling thread is higher than the current priority
- ceiling.
-
-*EBUSY*
- The mutex is already locked.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_timedlock - Lock a Mutex with Timeout
----------------------------------------------------
-.. index:: pthread_mutex_timedlock
-.. index:: lock a mutex with timeout
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- #include <time.h>
- int pthread_mutex_timedlock(
- pthread_mutex_t \*mutex,
- const struct timespec \*timeout
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified mutex is invalid.
-
-*EINVAL*
- The nanoseconds field of timeout is invalid.
-
-*EINVAL*
- The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
- priority of the calling thread is higher than the current priority
- ceiling.
-
-*EDEADLK*
- The current thread already owns the mutex.
-
-*ETIMEDOUT*
- The calling thread was unable to obtain the mutex within the specified
- timeout period.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_unlock - Unlock a Mutex
--------------------------------------
-.. index:: pthread_mutex_unlock
-.. index:: unlock a mutex
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_unlock(
- pthread_mutex_t \*mutex
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified mutex is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
--------------------------------------------------------------------
-.. index:: pthread_mutex_setprioceiling
-.. index:: dynamically set the priority ceiling
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_setprioceiling(
- pthread_mutex_t \*mutex,
- int prioceiling,
- int \*oldceiling
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The oldceiling pointer parameter is invalid.
-
-*EINVAL*
- The prioceiling parameter is an invalid priority.
-
-*EINVAL*
- The specified mutex is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_mutex_getprioceiling - Get the Current Priority Ceiling
----------------------------------------------------------------
-.. index:: pthread_mutex_getprioceiling
-.. index:: get the current priority ceiling
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_mutex_getprioceiling(
- pthread_mutex_t \*mutex,
- int \*prioceiling
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The prioceiling pointer parameter is invalid.
-
-*EINVAL*
- The specified mutex is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Condition Variable Manager
-##########################
-
-Introduction
-============
-
-The condition variable manager ...
-
-The directives provided by the condition variable manager are:
-
-- ``pthread_condattr_init`` - Initialize a Condition Variable Attribute Set
-
-- ``pthread_condattr_destroy`` - Destroy a Condition Variable Attribute Set
-
-- ``pthread_condattr_setpshared`` - Set Process Shared Attribute
-
-- ``pthread_condattr_getpshared`` - Get Process Shared Attribute
-
-- ``pthread_cond_init`` - Initialize a Condition Variable
-
-- ``pthread_cond_destroy`` - Destroy a Condition Variable
-
-- ``pthread_cond_signal`` - Signal a Condition Variable
-
-- ``pthread_cond_broadcast`` - Broadcast a Condition Variable
-
-- ``pthread_cond_wait`` - Wait on a Condition Variable
-
-- ``pthread_cond_timedwait`` - With with Timeout a Condition Variable
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the condition variable 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.
-
-pthread_condattr_init - Initialize a Condition Variable Attribute Set
----------------------------------------------------------------------
-.. index:: pthread_condattr_init
-.. index:: initialize a condition variable attribute set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_condattr_init(
- pthread_condattr_t \*attr
- );
-
-**STATUS CODES:**
-
-*ENOMEM*
- Insufficient memory is available to initialize the condition variable
- attributes object.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_condattr_destroy - Destroy a Condition Variable Attribute Set
----------------------------------------------------------------------
-.. index:: pthread_condattr_destroy
-.. index:: destroy a condition variable attribute set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_condattr_destroy(
- pthread_condattr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute object specified is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_condattr_setpshared - Set Process Shared Attribute
-----------------------------------------------------------
-.. index:: pthread_condattr_setpshared
-.. index:: set process shared attribute
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_condattr_setpshared(
- pthread_condattr_t \*attr,
- int pshared
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_condattr_getpshared - Get Process Shared Attribute
-----------------------------------------------------------
-.. index:: pthread_condattr_getpshared
-.. index:: get process shared attribute
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_condattr_getpshared(
- const pthread_condattr_t \*attr,
- int \*pshared
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_cond_init - Initialize a Condition Variable
----------------------------------------------------
-.. index:: pthread_cond_init
-.. index:: initialize a condition variable
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_cond_init(
- pthread_cond_t \*cond,
- const pthread_condattr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EAGAIN*
- The system lacked a resource other than memory necessary to create the
- initialize the condition variable object.
-
-*ENOMEM*
- Insufficient memory is available to initialize the condition variable object.
-
-*EBUSY*
- The specified condition variable has already been initialized.
-
-*EINVAL*
- The specified attribute value is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_cond_destroy - Destroy a Condition Variable
----------------------------------------------------
-.. index:: pthread_cond_destroy
-.. index:: destroy a condition variable
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_cond_destroy(
- pthread_cond_t \*cond
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified condition variable is invalid.
-
-*EBUSY*
- The specified condition variable is currently in use.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_cond_signal - Signal a Condition Variable
--------------------------------------------------
-.. index:: pthread_cond_signal
-.. index:: signal a condition variable
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_cond_signal(
- pthread_cond_t \*cond
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified condition variable is not valid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine should not be invoked from a handler from an asynchronous signal
-handler or an interrupt service routine.
-
-pthread_cond_broadcast - Broadcast a Condition Variable
--------------------------------------------------------
-.. index:: pthread_cond_broadcast
-.. index:: broadcast a condition variable
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_cond_broadcast(
- pthread_cond_t \*cond
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified condition variable is not valid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This routine should not be invoked from a handler from an asynchronous signal
-handler or an interrupt service routine.
-
-pthread_cond_wait - Wait on a Condition Variable
-------------------------------------------------
-.. index:: pthread_cond_wait
-.. index:: wait on a condition variable
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_cond_wait(
- pthread_cond_t \*cond,
- pthread_mutex_t \*mutex
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified condition variable or mutex is not initialized OR different
- mutexes were specified for concurrent pthread_cond_wait() and
- pthread_cond_timedwait() operations on the same condition variable OR
- the mutex was not owned by the current thread at the time of the call.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_cond_timedwait - Wait with Timeout a Condition Variable
----------------------------------------------------------------
-.. index:: pthread_cond_timedwait
-.. index:: wait with timeout a condition variable
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_cond_timedwait(
- pthread_cond_t \*cond,
- pthread_mutex_t \*mutex,
- const struct timespec \*abstime
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified condition variable or mutex is not initialized OR different
- mutexes were specified for concurrent pthread_cond_wait() and
- pthread_cond_timedwait() operations on the same condition variable OR
- the mutex was not owned by the current thread at the time of the call.
-
-*ETIMEDOUT*
- The specified time has elapsed without the condition variable being
- satisfied.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Memory Management Manager
-#########################
-
-Introduction
-============
-
-The
-memory management manager is ...
-
-The directives provided by the memory management manager are:
-
-- ``mlockall`` - Lock the Address Space of a Process
-
-- ``munlockall`` - Unlock the Address Space of a Process
-
-- ``mlock`` - Lock a Range of the Process Address Space
-
-- ``munlock`` - Unlock a Range of the Process Address Space
-
-- ``mmap`` - Map Process Addresses to a Memory Object
-
-- ``munmap`` - Unmap Previously Mapped Addresses
-
-- ``mprotect`` - Change Memory Protection
-
-- ``msync`` - Memory Object Synchronization
-
-- ``shm_open`` - Open a Shared Memory Object
-
-- ``shm_unlink`` - Remove a Shared Memory Object
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the memory management 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.
-
-mlockall - Lock the Address Space of a Process
-----------------------------------------------
-.. index:: mlockall
-.. index:: lock the address space of a process
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int mlockall(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-munlockall - Unlock the Address Space of a Process
---------------------------------------------------
-.. index:: munlockall
-.. index:: unlock the address space of a process
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int munlockall(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-mlock - Lock a Range of the Process Address Space
--------------------------------------------------
-.. index:: mlock
-.. index:: lock a range of the process address space
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int mlock(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-munlock - Unlock a Range of the Process Address Space
------------------------------------------------------
-.. index:: munlock
-.. index:: unlock a range of the process address space
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int munlock(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-mmap - Map Process Addresses to a Memory Object
------------------------------------------------
-.. index:: mmap
-.. index:: map process addresses to a memory object
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int mmap(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-munmap - Unmap Previously Mapped Addresses
-------------------------------------------
-.. index:: munmap
-.. index:: unmap previously mapped addresses
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int munmap(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-mprotect - Change Memory Protection
------------------------------------
-.. index:: mprotect
-.. index:: change memory protection
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int mprotect(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-msync - Memory Object Synchronization
--------------------------------------
-.. index:: msync
-.. index:: memory object synchronization
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int msync(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-shm_open - Open a Shared Memory Object
---------------------------------------
-.. index:: shm_open
-.. index:: open a shared memory object
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int shm_open(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-shm_unlink - Remove a Shared Memory Object
-------------------------------------------
-.. index:: shm_unlink
-.. index:: remove a shared memory object
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int shm_unlink(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Scheduler Manager
-#################
-
-Introduction
-============
-
-The scheduler manager ...
-
-The directives provided by the scheduler manager are:
-
-- ``sched_get_priority_min`` - Get Minimum Priority Value
-
-- ``sched_get_priority_max`` - Get Maximum Priority Value
-
-- ``sched_rr_get_interval`` - Get Timeslicing Quantum
-
-- ``sched_yield`` - Yield the Processor
-
-Background
-==========
-
-Priority
---------
-
-In the RTEMS implementation of the POSIX API, the priorities range from
-the low priority of ``sched_get_priority_min()`` to the highest priority of``sched_get_priority_max()``. Numerically higher values represent higher
-priorities.
-
-Scheduling Policies
--------------------
-
-The following scheduling policies are available:
-
-*SCHED_FIFO*
- Priority-based, preemptive scheduling with no timeslicing. This is equivalent
- to what is called "manual round-robin" scheduling.
-
-*SCHED_RR*
- Priority-based, preemptive scheduling with timeslicing. Time quantums are
- maintained on a per-thread basis and are not reset at each context switch.
- Thus, a thread which is preempted and subsequently resumes execution will
- attempt to complete the unused portion of its time quantum.
-
-*SCHED_OTHER*
- Priority-based, preemptive scheduling with timeslicing. Time quantums are
- maintained on a per-thread basis and are reset at each context switch.
-
-*SCHED_SPORADIC*
- Priority-based, preemptive scheduling utilizing three additional parameters:
- budget, replenishment period, and low priority. Under this policy, the
- thread is allowed to execute for "budget" amount of time before its priority
- is lowered to "low priority". At the end of each replenishment period,
- the thread resumes its initial priority and has its budget replenished.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the scheduler 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.
-
-sched_get_priority_min - Get Minimum Priority Value
----------------------------------------------------
-.. index:: sched_get_priority_min
-.. index:: get minimum priority value
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sched.h>
- int sched_get_priority_min(
- int policy
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*EINVAL*
- The indicated policy is invalid.
-
-**DESCRIPTION:**
-
-This routine return the minimum (numerically and logically lowest) priority
-for the specified ``policy``.
-
-**NOTES:**
-
-NONE
-
-sched_get_priority_max - Get Maximum Priority Value
----------------------------------------------------
-.. index:: sched_get_priority_max
-.. index:: get maximum priority value
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sched.h>
- int sched_get_priority_max(
- int policy
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*EINVAL*
- The indicated policy is invalid.
-
-**DESCRIPTION:**
-
-This routine return the maximum (numerically and logically highest) priority
-for the specified ``policy``.
-
-**NOTES:**
-
-NONE
-
-sched_rr_get_interval - Get Timeslicing Quantum
------------------------------------------------
-.. index:: sched_rr_get_interval
-.. index:: get timeslicing quantum
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sched.h>
- int sched_rr_get_interval(
- pid_t pid,
- struct timespec \*interval
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*ESRCH*
- The indicated process id is invalid.
-
-*EINVAL*
- The specified interval pointer parameter is invalid.
-
-**DESCRIPTION:**
-
-This routine returns the length of the timeslice quantum in the``interval`` parameter for the specified ``pid``.
-
-**NOTES:**
-
-The ``pid`` argument should be 0 to indicate the calling process.
-
-sched_yield - Yield the Processor
----------------------------------
-.. index:: sched_yield
-.. index:: yield the processor
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sched.h>
- int sched_yield( void );
-
-**STATUS CODES:**
-
-This routine always returns zero to indicate success.
-
-**DESCRIPTION:**
-
-This call forces the calling thread to yield the processor to another
-thread. Normally this is used to implement voluntary round-robin
-task scheduling.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Clock Manager
-#############
-
-Introduction
-============
-
-The clock manager provides services two primary classes
-of services. The first focuses on obtaining and setting
-the current date and time. The other category of services
-focus on allowing a thread to delay for a specific length
-of time.
-
-The directives provided by the clock manager are:
-
-- ``clock_gettime`` - Obtain Time of Day
-
-- ``clock_settime`` - Set Time of Day
-
-- ``clock_getres`` - Get Clock Resolution
-
-- ``sleep`` - Delay Process Execution
-
-- ``usleep`` - Delay Process Execution in Microseconds
-
-- ``nanosleep`` - Delay with High Resolution
-
-- ``gettimeofday`` - Get the Time of Day
-
-- ``time`` - Get time in seconds
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-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_gettime - Obtain Time of Day
-----------------------------------
-.. index:: clock_gettime
-.. index:: obtain time of day
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int clock_gettime(
- clockid_t clock_id,
- struct timespec \*tp
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*EINVAL*
- The tp pointer parameter is invalid.
-
-*EINVAL*
- The clock_id specified is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-NONE
-
-clock_settime - Set Time of Day
--------------------------------
-.. index:: clock_settime
-.. index:: set time of day
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int clock_settime(
- clockid_t clock_id,
- const struct timespec \*tp
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*EINVAL*
- The tp pointer parameter is invalid.
-
-*EINVAL*
- The clock_id specified is invalid.
-
-*EINVAL*
- The contents of the tp structure are invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-NONE
-
-clock_getres - Get Clock Resolution
------------------------------------
-.. index:: clock_getres
-.. index:: get clock resolution
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int clock_getres(
- clockid_t clock_id,
- struct timespec \*res
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*EINVAL*
- The res pointer parameter is invalid.
-
-*EINVAL*
- The clock_id specified is invalid.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-If res is NULL, then the resolution is not returned.
-
-sleep - Delay Process Execution
--------------------------------
-.. index:: sleep
-.. index:: delay process execution
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <unistd.h>
- unsigned int sleep(
- unsigned int seconds
- );
-
-**STATUS CODES:**
-
-This routine returns the number of unslept seconds.
-
-**DESCRIPTION:**
-
-The ``sleep()`` function delays the calling thread by the specified
-number of ``seconds``.
-
-**NOTES:**
-
-This call is interruptible by a signal.
-
-usleep - Delay Process Execution in Microseconds
-------------------------------------------------
-.. index:: usleep
-.. index:: delay process execution
-.. index:: delay process execution
-.. index:: usecs delay process execution
-.. index:: microsecond delay process execution
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- useconds_t usleep(
- useconds_t useconds
- );
-
-**STATUS CODES:**
-
-This routine returns the number of unslept seconds.
-
-**DESCRIPTION:**
-
-The ``sleep()`` function delays the calling thread by the specified
-number of ``seconds``.
-
-The ``usleep()`` function suspends the calling thread from execution
-until either the number of microseconds specified by the``useconds`` argument has elapsed or a signal is delivered to the
-calling thread and its action is to invoke a signal-catching function
-or to terminate the process.
-
-Because of other activity, or because of the time spent in
-processing the call, the actual length of time the thread is
-blocked may be longer than
-the amount of time specified.
-
-**NOTES:**
-
-This call is interruptible by a signal.
-
-The Single UNIX Specification allows this service to be implemented using
-the same timer as that used by the ``alarm()`` service. This is*NOT* the case for *RTEMS* and this call has no interaction with
-the ``SIGALRM`` signal.
-
-nanosleep - Delay with High Resolution
---------------------------------------
-.. index:: nanosleep
-.. index:: delay with high resolution
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int nanosleep(
- const struct timespec \*rqtp,
- struct timespec \*rmtp
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets errno to one of the following:
-
-*EINTR*
- The routine was interrupted by a signal.
-
-*EAGAIN*
- The requested sleep period specified negative seconds or nanoseconds.
-
-*EINVAL*
- The requested sleep period specified an invalid number for the nanoseconds
- field.
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-This call is interruptible by a signal.
-
-gettimeofday - Get the Time of Day
-----------------------------------
-.. index:: gettimeofday
-.. index:: get the time of day
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <sys/time.h>
- #include <unistd.h>
- int gettimeofday(
- struct timeval \*tp,
- struct timezone \*tzp
- );
-
-**STATUS CODES:**
-
-On error, this routine returns -1 and sets ``errno`` as appropriate.
-
-*EPERM*
- ``settimeofdat`` is called by someone other than the superuser.
-
-*EINVAL*
- Timezone (or something else) is invalid.
-
-*EFAULT*
- One of ``tv`` or ``tz`` pointed outside your accessible address
- space
-
-**DESCRIPTION:**
-
-This routine returns the current time of day in the ``tp`` structure.
-
-**NOTES:**
-
-Currently, the timezone information is not supported. The ``tzp``
-argument is ignored.
-
-time - Get time in seconds
---------------------------
-.. index:: time
-.. index:: get time in seconds
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int time(
- time_t \*tloc
- );
-
-**STATUS CODES:**
-
-This routine returns the number of seconds since the Epoch.
-
-**DESCRIPTION:**
-
-``time`` returns the time since 00:00:00 GMT, January 1, 1970,
-measured in seconds
-
-If ``tloc`` in non null, the return value is also stored in the
-memory pointed to by ``t``.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that
-
-.. COMMENT: documents the services provided by the timer @c manager.
-
-Timer Manager
-#############
-
-Introduction
-============
-
-The timer manager is ...
-
-The services provided by the timer manager are:
-
-- ``timer_create`` - Create a Per-Process Timer
-
-- ``timer_delete`` - Delete a Per-Process Timer
-
-- ``timer_settime`` - Set Next Timer Expiration
-
-- ``timer_gettime`` - Get Time Remaining on Timer
-
-- ``timer_getoverrun`` - Get Timer Overrun Count
-
-Background
-==========
-
-Operations
-==========
-
-System Calls
-============
-
-This section details the timer manager’s services.
-A subsection is dedicated to each of this manager’s services
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-.. COMMENT: timer_create
-
-timer_create - Create a Per-Process Timer
------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- #include <signal.h>
- int timer_create(
- clockid_t clock_id,
- struct sigevent \*evp,
- timer_t \*timerid
- );
-
-**STATUS CODES:**
-
-``EXXX`` -
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: timer_delete
-
-timer_delete - Delete a Per-Process Timer
------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int timer_delete(
- timer_t timerid
- );
-
-**STATUS CODES:**
-
-``EXXX`` -
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: timer_settime
-
-timer_settime - Set Next Timer Expiration
------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int timer_settime(
- timer_t timerid,
- int flags,
- const struct itimerspec \*value,
- struct itimerspec \*ovalue
- );
-
-**STATUS CODES:**
-
-``EXXX`` -
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: timer_gettime
-
-timer_gettime - Get Time Remaining on Timer
--------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int timer_gettime(
- timer_t timerid,
- struct itimerspec \*value
- );
-
-**STATUS CODES:**
-
-``EXXX`` -
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: timer_getoverrun
-
-timer_getoverrun - Get Timer Overrun Count
-------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <time.h>
- int timer_getoverrun(
- timer_t timerid
- );
-
-**STATUS CODES:**
-
-``EXXX`` -
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT(c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation(OAR).
-
-.. COMMENT: All rights reserved.
-
-Message Passing Manager
-#######################
-
-Introduction
-============
-
-The message passing manager is the means to provide communication and
-synchronization capabilities using POSIX message queues.
-
-The directives provided by the message passing manager are:
-
-- ``mq_open`` - Open a Message Queue
-
-- ``mq_close`` - Close a Message Queue
-
-- ``mq_unlink`` - Remove a Message Queue
-
-- ``mq_send`` - Send a Message to a Message Queue
-
-- ``mq_receive`` - Receive a Message from a Message Queue
-
-- ``mq_notify`` - Notify Process that a Message is Available
-
-- ``mq_setattr`` - Set Message Queue Attributes
-
-- ``mq_getattr`` - Get Message Queue Attributes
-
-Background
-==========
-
-Theory
-------
-
-Message queues are named objects that operate with readers and writers.
-In addition, a message queue is a priority queue of discrete messages.
-POSIX message queues offer a certain, basic amount of application access
-to, and control over, the message queue geometry that can be changed.
-
-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. There is a maximum acceptable length for a message
-that is associated with each message queue.
-
-Message Queues
---------------
-
-Message queues are named objects similar to the pipes of POSIX. They are
-a means of communicating data between multiple processes and for passing
-messages among tasks and ISRs. Message queues can contain a variable
-number of messages from 0 to an upper limit that is user defined. The
-maximum length of the message can be set on a per message queue basis.
-Normally messages are sent and received from the message queue in FIFO
-order. However, messages can also be prioritized and a priority queue
-established for the passing of messages. Synchronization is needed when a
-task waits for a message to arrive at a queue. Also, a task may poll a
-queue for the arrival of a message... index:: mqd_t
-
-The message queue descriptor ``mqd_t`` represents the message queue. It is
-passed as an argument to all of the message queue functions.
-
-Building a Message Queue Attribute Set
---------------------------------------
-
-The mq_attr structure is used to define the characteristics of the message
-queue... index:: mq_attr
-
-.. code:: c
-
- typedef struct mq_attr{
- long mq_flags;
- long mq_maxmsg;
- long mq_msgsize;
- long mq_curmsgs;
- };
-
-All of these attributes are set when the message queue is created using
-mq_open. The mq_flags field is not used in the creation of a message
-queue, it is only used by mq_setattr and mq_getattr. The structure
-mq_attr is passed as an argument to mq_setattr and mq_getattr.
-
-The mq_flags contain information affecting the behavior of the message
-queue. The O_NONBLOCK mq_flag is the only flag that is defined. In
-mq_setattr, the mq_flag can be set to dynamically change the blocking and
-non-blocking behavior of the message queue. If the non-block flag is set
-then the message queue is non-blocking, and requests to send and receive
-messages do not block waiting for resources. For a blocking message
-queue, a request to send might have to wait for an empty message queue,
-and a request to receive might have to wait for a message to arrive on the
-queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message
-queue. mq_maxmsg specifies how many messages the queue can hold at any
-one time. mq_msgsize specifies the size of any one message on the queue.
-If either of these limits is exceeded, an error message results.
-
-Upon return from mq_getattr, the mq_curmsgs is set according to the
-current state of the message queue. This specifies the number of messages
-currently on the queue.
-
-Notification of a Message on the Queue
---------------------------------------
-
-Every message queue has the ability to notify one (and only one) process
-whenever the queue’s state changes from empty (0 messages) to nonempty.
-This means that the process does not have to block or constantly poll
-while it waits for a message. By calling mq_notify, you can attach a
-notification request to a message queue. When a message is received by an
-empty queue, if there are no processes blocked and waiting for the
-message, then the queue notifies the requesting process of a message
-arrival. There is only one signal sent by the message queue, after that
-the notification request is de-registered and another process can attach
-its notification request. After receipt of a notification, a process must
-re-register if it wishes to be notified again.
-
-If there is a process blocked and waiting for the message, that process
-gets the message, and notification is not sent. It is also possible for
-another process to receive the message after the notification is sent but
-before the notified process has sent its receive request.
-
-Only one process can have a notification request attached to a message
-queue at any one time. If another process attempts to register a
-notification request, it fails. You can de-register for a message queue
-by passing a NULL to mq_notify, this removes any notification request
-attached to the queue. Whenever the message queue is closed, all
-notification attachments are removed.
-
-POSIX Interpretation Issues
----------------------------
-
-There is one significant point of interpretation related to
-the RTEMS implementation of POSIX message queues:
-
-*What happens to threads already blocked on a message queue when the
-mode of that same message queue is changed from blocking to non-blocking?*
-
-The RTEMS POSIX implementation decided to unblock all waiting tasks
-with an ``EAGAIN`` status just as if a non-blocking version of
-the same operation had returned unsatisfied. This case is not
-discussed in the POSIX standard and other implementations may have
-chosen alternative behaviors.
-
-Operations
-==========
-
-Opening or Creating a Message Queue
------------------------------------
-
-If the message queue already exists, mq_open() opens it, if the message
-queue does not exist, mq_open() creates it. When a message queue is
-created, the geometry of the message queue is contained in the attribute
-structure that is passed in as an argument. This includes mq_msgsize that
-dictates the maximum size of a single message, and the mq_maxmsg that
-dictates the maximum number of messages the queue can hold at one time.
-The blocking or non-blocking behavior of the queue can also specified.
-
-Closing a Message Queue
------------------------
-
-The mq_close() function is used to close the connection made to a message
-queue that was made during mq_open. The message queue itself and the
-messages on the queue are persistent and remain after the queue is closed.
-
-Removing a Message Queue
-------------------------
-
-The mq_unlink() function removes the named message queue. If the message
-queue is not open when mq_unlink is called, then the queue is immediately
-eliminated. Any messages that were on the queue are lost, and the queue
-can not be opened again. If processes have the queue open when mq_unlink
-is called, the removal of the queue is delayed until the last process
-using the queue has finished. However, the name of the message queue is
-removed so that no other process can open it.
-
-Sending a Message to a Message Queue
-------------------------------------
-
-The mq_send() function adds the message in priority order to the message
-queue. Each message has an assigned a priority. The highest priority
-message is be at the front of the queue.
-
-The maximum number of messages that a message queue may accept is
-specified at creation by the mq_maxmsg field of the attribute structure.
-If this amount is exceeded, the behavior of the process is determined
-according to what oflag was used when the message queue was opened. If
-the queue was opened with O_NONBLOCK flag set, the process does not block,
-and an error is returned. If the O_NONBLOCK flag was not set, the process
-does block and wait for space on the queue.
-
-Receiving a Message from a Message Queue
-----------------------------------------
-
-The mq_receive() function is used to receive the oldest of the highest
-priority message(s) from the message queue specified by mqdes. The
-messages are received in FIFO order within the priorities. The received
-message’s priority is stored in the location referenced by the msg_prio.
-If the msg_prio is a NULL, the priority is discarded. The message is
-removed and stored in an area pointed to by msg_ptr whose length is of
-msg_len. The msg_len must be at least equal to the mq_msgsize attribute
-of the message queue.
-
-The blocking behavior of the message queue is set by O_NONBLOCK at mq_open
-or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is
-a blocking queue, the process does block and wait on an empty queue. If
-this a non-blocking queue, the process does not block. Upon successful
-completion, mq_receive returns the length of the selected message in bytes
-and the message is removed from the queue.
-
-Notification of Receipt of a Message on an Empty Queue
-------------------------------------------------------
-
-The mq_notify() function registers the calling process to be notified of
-message arrival at an empty message queue. Every message queue has the
-ability to notify one (and only one) process whenever the queue’s state
-changes from empty (0 messages) to nonempty. This means that the process
-does not have to block or constantly poll while it waits for a message.
-By calling mq_notify, a notification request is attached to a message
-queue. When a message is received by an empty queue, if there are no
-processes blocked and waiting for the message, then the queue notifies the
-requesting process of a message arrival. There is only one signal sent by
-the message queue, after that the notification request is de-registered
-and another process can attach its notification request. After receipt of
-a notification, a process must re-register if it wishes to be notified
-again.
-
-If there is a process blocked and waiting for the message, that process
-gets the message, and notification is not sent. Only one process can have
-a notification request attached to a message queue at any one time. If
-another process attempts to register a notification request, it fails.
-You can de-register for a message queue by passing a NULL to mq_notify,
-this removes any notification request attached to the queue. Whenever the
-message queue is closed, all notification attachments are removed.
-
-Setting the Attributes of a Message Queue
------------------------------------------
-
-The mq_setattr() function is used to set attributes associated with the
-open message queue description referenced by the message queue descriptor
-specified by mqdes. The \*omqstat represents the old or previous
-attributes. If omqstat is non-NULL, the function mq_setattr() stores, in
-the location referenced by omqstat, the previous message queue attributes
-and the current queue status. These values are the same as would be
-returned by a call to mq_getattr() at that point.
-
-There is only one mq_attr.mq_flag that can be altered by this call. This
-is the flag that deals with the blocking and non-blocking behavior of the
-message queue. If the flag is set then the message queue is non-blocking,
-and requests to send or receive do not block while waiting for resources.
-If the flag is not set, then message send and receive may involve waiting
-for an empty queue or waiting for a message to arrive.
-
-Getting the Attributes of a Message Queue
------------------------------------------
-
-The mq_getattr() function is used to get status information and attributes
-of the message queue associated with the message queue descriptor. The
-results are returned in the mq_attr structure referenced by the mqstat
-argument. All of these attributes are set at create time, except the
-blocking/non-blocking behavior of the message queue which can be
-dynamically set by using mq_setattr. The attribute mq_curmsg is set to
-reflect the number of messages on the queue at the time that mq_getattr
-was called.
-
-Directives
-==========
-
-This section details the message passing 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.
-
-mq_open - Open a Message Queue
-------------------------------
-.. index:: mq_open
-.. index:: open a message queue
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- mqd_t mq_open(
- const char \*name,
- int oflag,
- mode_t mode,
- struct mq_attr \*attr
- );
-
-**STATUS CODES:**
-
-``EACCES`` - Either the message queue exists and the permissions
-requested in oflags were denied, or the message does not exist and
-permission to create one is denied.
-
-``EEXIST`` - You tried to create a message queue that already exists.
-
-``EINVAL`` - An inappropriate name was given for the message queue, or
-the values of mq-maxmsg or mq_msgsize were less than 0.
-
-``ENOENT`` - The message queue does not exist, and you did not specify
-to create it.
-
-``EINTR`` - The call to mq_open was interrupted by a signal.
-
-``EMFILE`` - The process has too many files or message queues open.
-This is a process limit error.
-
-``ENFILE`` - The system has run out of resources to support more open
-message queues. This is a system error.
-
-``ENAMETOOLONG`` - mq_name is too long.
-
-**DESCRIPTION:**
-
-The mq_open () function establishes the connection between a process and a
-message queue with a message queue descriptor. If the message queue
-already exists, mq_open opens it, if the message queue does not exist,
-mq_open creates it. Message queues can have multiple senders and
-receivers. If mq_open is successful, the function returns a message queue
-descriptor. Otherwise, the function returns a -1 and sets ’errno’ to
-indicate the error.
-
-The name of the message queue is used as an argument. For the best of
-portability, the name of the message queue should begin with a "/" and no
-other "/" should be in the name. Different systems interpret the name in
-different ways.
-
-The oflags contain information on how the message is opened if the queue
-already exists. This may be O_RDONLY for read only, O_WRONLY for write
-only, of O_RDWR, for read and write.
-
-In addition, the oflags contain information needed in the creation of a
-message queue. ``O_NONBLOCK`` - If the non-block flag is set then the
-message queue is non-blocking, and requests to send and receive messages
-do not block waiting for resources. If the flag is not set then the
-message queue is blocking, and a request to send might have to wait for an
-empty message queue. Similarly, a request to receive might have to wait
-for a message to arrive on the queue. ``O_CREAT`` - This call specifies
-that the call the mq_open is to create a new message queue. In this case
-the mode and attribute arguments of the function call are utilized. The
-message queue is created with a mode similar to the creation of a file,
-read and write permission creator, group, and others.
-
-The geometry of the message queue is contained in the attribute structure.
-This includes mq_msgsize that dictates the maximum size of a single
-message, and the mq_maxmsg that dictates the maximum number of messages
-the queue can hold at one time. If a NULL is used in the mq_attr
-argument, then the message queue is created with implementation defined
-defaults. ``O_EXCL`` - is always set if O_CREAT flag is set. If the
-message queue already exists, O_EXCL causes an error message to be
-returned, otherwise, the new message queue fails and appends to the
-existing one.
-
-**NOTES:**
-
-The mq_open () function does not add or remove messages from the queue.
-When a new message queue is being created, the mq_flag field of the
-attribute structure is not used.
-
-mq_close - Close a Message Queue
---------------------------------
-.. index:: mq_close
-.. index:: close a message queue
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- int mq_close(
- mqd_t mqdes
- );
-
-**STATUS CODES:**
-
-``EINVAL`` - The descriptor does not represent a valid open message
-queue
-
-**DESCRIPTION:**
-
-The mq_close function removes the association between the message queue
-descriptor, mqdes, and its message queue. If mq_close() is successfully
-completed, the function returns a value of zero; otherwise, the function
-returns a value of -1 and sets errno to indicate the error.
-
-**NOTES:**
-
-If the process had successfully attached a notification request to the
-message queue via mq_notify, this attachment is removed, and the message
-queue is available for another process to attach for notification.
-mq_close has no effect on the contents of the message queue, all the
-messages that were in the queue remain in the queue.
-
-mq_unlink - Remove a Message Queue
-----------------------------------
-.. index:: mq_unlink
-.. index:: remove a message queue
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- int mq_unlink(
- const char \*name
- );
-
-**STATUS CODES:**
-
-``EINVAL`` - The descriptor does not represent a valid message queue
-
-**DESCRIPTION:**
-
-The mq_unlink() function removes the named message queue. If the message
-queue is not open when mq_unlink is called, then the queue is immediately
-eliminated. Any messages that were on the queue are lost, and the queue
-can not be opened again. If processes have the queue open when mq_unlink
-is called, the removal of the queue is delayed until the last process
-using the queue has finished. However, the name of the message queue is
-removed so that no other process can open it. Upon successful completion,
-the function returns a value of zero. Otherwise, the named message queue
-is not changed by this function call, and the function returns a value of
--1 and sets errno to indicate the error.
-
-**NOTES:**
-
-Calls to mq_open() to re-create the message queue may fail until the
-message queue is actually removed. However, the mq_unlink() call need not
-block until all references have been closed; it may return immediately.
-
-mq_send - Send a Message to a Message Queue
--------------------------------------------
-.. index:: mq_send
-.. index:: send a message to a message queue
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include<mqueue.h>
- int mq_send(
- mqd_t mqdes,
- const char \*msg_ptr,
- size_t msg_len,
- unsigned int msg_prio
- );
-
-**STATUS CODES:**
-
-``EBADF`` - The descriptor does not represent a valid message queue, or the queue was opened for read only O_RDONLY``EINVAL`` - The value of msg_prio was greater than the MQ_PRIO_MAX.``EMSGSIZE`` - The msg_len is greater than the mq_msgsize attribute of the message queue``EAGAIN`` - The message queue is non-blocking, and there is no room on the queue for another message as specified by the mq_maxmsg.``EINTR`` - The message queue is blocking. While the process was waiting for free space on the queue, a signal arrived that interrupted the wait.
-
-**DESCRIPTION:**
-
-The mq_send() function adds the message pointed to by the argument msg_ptr
-to the message queue specified by mqdes. Each message is assigned a
-priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and
-must be at least 32. Messages are added to the queue in order of their
-priority. The highest priority message is at the front of the queue.
-
-The maximum number of messages that a message queue may accept is
-specified at creation by the mq_maxmsg field of the attribute structure.
-If this amount is exceeded, the behavior of the process is determined
-according to what oflag was used when the message queue was opened. If
-the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is
-returned. If the O_NONBLOCK flag was not set, the process blocks and
-waits for space on the queue, unless it is interrupted by a signal.
-
-Upon successful completion, the mq_send () function returns a value of
-zero. Otherwise, no message is enqueued, the function returns -1, and
-errno is set to indicate the error.
-
-**NOTES:**
-
-If the specified message queue is not full, mq_send inserts the message at
-the position indicated by the msg_prio argument.
-
-mq_receive - Receive a Message from a Message Queue
----------------------------------------------------
-.. index:: mq_receive
-.. index:: receive a message from a message queue
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- size_t mq_receive(
- mqd_t mqdes,
- char \*msg_ptr,
- size_t msg_len,
- unsigned int \*msg_prio
- );
-
-**STATUS CODES:**
-
-``EBADF`` - The descriptor does not represent a valid message queue, or the queue was opened for write only O_WRONLY``EMSGSIZE`` - The msg_len is less than the mq_msgsize attribute of the message queue``EAGAIN`` - The message queue is non-blocking, and the queue is empty``EINTR`` - The message queue is blocking. While the process was waiting for a message to arrive on the queue, a signal arrived that interrupted the wait.
-
-**DESCRIPTION:**
-
-The mq_receive function is used to receive the oldest of the highest
-priority message(s) from the message queue specified by mqdes. The
-messages are received in FIFO order within the priorities. The received
-message’s priority is stored in the location referenced by the msg_prio.
-If the msg_prio is a NULL, the priority is discarded. The message is
-removed and stored in an area pointed to by msg_ptr whose length is of
-msg_len. The msg_len must be at least equal to the mq_msgsize attribute
-of the message queue.
-
-The blocking behavior of the message queue is set by O_NONBLOCK at mq_open
-or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is
-a blocking queue, the process blocks and waits on an empty queue. If this
-a non-blocking queue, the process does not block.
-
-Upon successful completion, mq_receive returns the length of the selected
-message in bytes and the message is removed from the queue. Otherwise, no
-message is removed from the queue, the function returns a value of -1, and
-sets errno to indicate the error.
-
-**NOTES:**
-
-If the size of the buffer in bytes, specified by the msg_len argument, is
-less than the mq_msgsize attribute of the message queue, the function
-fails and returns an error
-
-mq_notify - Notify Process that a Message is Available
-------------------------------------------------------
-.. index:: mq_notify
-.. index:: notify process that a message is available
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- int mq_notify(
- mqd_t mqdes,
- const struct sigevent \*notification
- );
-
-**STATUS CODES:**
-
-``EBADF`` - The descriptor does not refer to a valid message queue``EBUSY`` - A notification request is already attached to the queue
-
-**DESCRIPTION:**
-
-If the argument notification is not NULL, this function registers the
-calling process to be notified of message arrival at an empty message
-queue associated with the specified message queue descriptor, mqdes.
-
-Every message queue has the ability to notify one (and only one) process
-whenever the queue’s state changes from empty (0 messages) to nonempty.
-This means that the process does not have to block or constantly poll
-while it waits for a message. By calling mq_notify, a notification
-request is attached to a message queue. When a message is received by an
-empty queue, if there are no processes blocked and waiting for the
-message, then the queue notifies the requesting process of a message
-arrival. There is only one signal sent by the message queue, after that
-the notification request is de-registered and another process can attach
-its notification request. After receipt of a notification, a process must
-re-register if it wishes to be notified again.
-
-If there is a process blocked and waiting for the message, that process
-gets the message, and notification is not be sent. Only one process can
-have a notification request attached to a message queue at any one time.
-If another process attempts to register a notification request, it fails.
-You can de-register for a message queue by passing a NULL to mq_notify;
-this removes any notification request attached to the queue. Whenever the
-message queue is closed, all notification attachments are removed.
-
-Upon successful completion, mq_notify returns a value of zero; otherwise,
-the function returns a value of -1 and sets errno to indicate the error.
-
-**NOTES:**
-
-It is possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request.
-
-mq_setattr - Set Message Queue Attributes
------------------------------------------
-.. index:: mq_setattr
-.. index:: set message queue attributes
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- int mq_setattr(
- mqd_t mqdes,
- const struct mq_attr \*mqstat,
- struct mq_attr \*omqstat
- );
-
-**STATUS CODES:**
-
-``EBADF`` - The message queue descriptor does not refer to a valid, open queue.``EINVAL`` - The mq_flag value is invalid.
-
-**DESCRIPTION:**
-
-The mq_setattr function is used to set attributes associated with the open
-message queue description referenced by the message queue descriptor
-specified by mqdes. The \*omqstat represents the old or previous
-attributes. If omqstat is non-NULL, the function mq_setattr() stores, in
-the location referenced by omqstat, the previous message queue attributes
-and the current queue status. These values are the same as would be
-returned by a call to mq_getattr() at that point.
-
-There is only one mq_attr.mq_flag which can be altered by this call.
-This is the flag that deals with the blocking and non-blocking behavior of
-the message queue. If the flag is set then the message queue is
-non-blocking, and requests to send or receive do not block while waiting
-for resources. If the flag is not set, then message send and receive may
-involve waiting for an empty queue or waiting for a message to arrive.
-
-Upon successful completion, the function returns a value of zero and the
-attributes of the message queue have been changed as specified.
-Otherwise, the message queue attributes is unchanged, and the function
-returns a value of -1 and sets errno to indicate the error.
-
-**NOTES:**
-
-All other fields in the mq_attr are ignored by this call.
-
-mq_getattr - Get Message Queue Attributes
------------------------------------------
-.. index:: mq_getattr
-.. index:: get message queue attributes
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <mqueue.h>
- int mq_getattr(
- mqd_t mqdes,
- struct mq_attr \*mqstat
- );
-
-**STATUS CODES:**
-
-``EBADF`` - The message queue descriptor does not refer to a valid,
-open message queue.
-
-**DESCRIPTION:**
-
-The mqdes argument specifies a message queue descriptor. The mq_getattr
-function is used to get status information and attributes of the message
-queue associated with the message queue descriptor. The results are
-returned in the mq_attr structure referenced by the mqstat argument. All
-of these attributes are set at create time, except the
-blocking/non-blocking behavior of the message queue which can be
-dynamically set by using mq_setattr. The attribute mq_curmsg is set to
-reflect the number of messages on the queue at the time that mq_getattr
-was called.
-
-Upon successful completion, the mq_getattr function returns zero.
-Otherwise, the function returns -1 and sets errno to indicate the error.
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2014.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Thread Manager
-##############
-
-Introduction
-============
-
-The thread manager implements the functionality required of the thread
-manager as defined by POSIX 1003.1b. This standard requires that
-a compliant operating system provide the facilties to manage multiple
-threads of control and defines the API that must be provided.
-
-The services provided by the thread manager are:
-
-- ``pthread_attr_init`` - Initialize a Thread Attribute Set
-
-- ``pthread_attr_destroy`` - Destroy a Thread Attribute Set
-
-- ``pthread_attr_setdetachstate`` - Set Detach State
-
-- ``pthread_attr_getdetachstate`` - Get Detach State
-
-- ``pthread_attr_setstacksize`` - Set Thread Stack Size
-
-- ``pthread_attr_getstacksize`` - Get Thread Stack Size
-
-- ``pthread_attr_setstackaddr`` - Set Thread Stack Address
-
-- ``pthread_attr_getstackaddr`` - Get Thread Stack Address
-
-- ``pthread_attr_setscope`` - Set Thread Scheduling Scope
-
-- ``pthread_attr_getscope`` - Get Thread Scheduling Scope
-
-- ``pthread_attr_setinheritsched`` - Set Inherit Scheduler Flag
-
-- ``pthread_attr_getinheritsched`` - Get Inherit Scheduler Flag
-
-- ``pthread_attr_setschedpolicy`` - Set Scheduling Policy
-
-- ``pthread_attr_getschedpolicy`` - Get Scheduling Policy
-
-- ``pthread_attr_setschedparam`` - Set Scheduling Parameters
-
-- ``pthread_attr_getschedparam`` - Get Scheduling Parameters
-
-- ``pthread_attr_getaffinity_np`` - Get Thread Affinity Attribute
-
-- ``pthread_attr_setaffinity_np`` - Set Thread Affinity Attribute
-
-- ``pthread_create`` - Create a Thread
-
-- ``pthread_exit`` - Terminate the Current Thread
-
-- ``pthread_detach`` - Detach a Thread
-
-- ``pthread_getattr_np`` - Get Thread Attributes
-
-- ``pthread_join`` - Wait for Thread Termination
-
-- ``pthread_self`` - Get Thread ID
-
-- ``pthread_equal`` - Compare Thread IDs
-
-- ``pthread_once`` - Dynamic Package Initialization
-
-- ``pthread_setschedparam`` - Set Thread Scheduling Parameters
-
-- ``pthread_getschedparam`` - Get Thread Scheduling Parameters
-
-- ``pthread_getaffinity_np`` - Get Thread Affinity
-
-- ``pthread_setaffinity_np`` - Set Thread Affinity
-
-Background
-==========
-
-Thread Attributes
------------------
-
-Thread attributes are utilized only at thread creation time. A thread
-attribute structure may be initialized and passed as an argument to
-the ``pthread_create`` routine.
-
-*stack address*
- is the address of the optionally user specified stack area for this thread.
- If this value is NULL, then RTEMS allocates the memory for the thread stack
- from the RTEMS Workspace Area. Otherwise, this is the user specified
- address for the memory to be used for the thread’s stack. Each thread must
- have a distinct stack area. Each processor family has different alignment
- rules which should be followed.
-
-*stack size*
- is the minimum desired size for this thread’s stack area.
- If the size of this area as specified by the stack size attribute
- is smaller than the minimum for this processor family and the stack
- is not user specified, then RTEMS will automatically allocate a
- stack of the minimum size for this processor family.
-
-*contention scope*
- specifies the scheduling contention scope. RTEMS only supports the
- PTHREAD_SCOPE_PROCESS scheduling contention scope.
-
-*scheduling inheritance*
- specifies whether a user specified or the scheduling policy and
- parameters of the currently executing thread are to be used. When
- this is PTHREAD_INHERIT_SCHED, then the scheduling policy and
- parameters of the currently executing thread are inherited by
- the newly created thread.
-
-*scheduling policy and parameters*
- specify the manner in which the thread will contend for the processor.
- The scheduling parameters are interpreted based on the specified policy.
- All policies utilize the thread priority parameter.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Services
-========
-
-This section details the thread manager’s services.
-A subsection is dedicated to each of this manager’s services
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-pthread_attr_init - Initialize a Thread Attribute Set
------------------------------------------------------
-.. index:: pthread_attr_init
-.. index:: initialize a thread attribute set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_init(
- pthread_attr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_init`` routine initializes the thread attributes
-object specified by ``attr`` with the default value for all of the
-individual attributes.
-
-**NOTES:**
-
-The settings in the default attributes are implementation defined. For
-RTEMS, the default attributes are as follows:
-
-- stackadr
- is not set to indicate that RTEMS is to allocate the stack memory.
-
-- stacksize
- is set to ``PTHREAD_MINIMUM_STACK_SIZE``.
-
-- contentionscope
- is set to ``PTHREAD_SCOPE_PROCESS``.
-
-- inheritsched
- is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created
- thread inherits its scheduling attributes from its parent.
-
-- detachstate
- is set to ``PTHREAD_CREATE_JOINABLE``.
-
-pthread_attr_destroy - Destroy a Thread Attribute Set
------------------------------------------------------
-.. index:: pthread_attr_destroy
-.. index:: destroy a thread attribute set
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_destroy(
- pthread_attr_t \*attr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_destroy`` routine is used to destroy a thread
-attributes object. The behavior of using an attributes object after
-it is destroyed is implementation dependent.
-
-**NOTES:**
-
-NONE
-
-pthread_attr_setdetachstate - Set Detach State
-----------------------------------------------
-.. index:: pthread_attr_setdetachstate
-.. index:: set detach state
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setdetachstate(
- pthread_attr_t \*attr,
- int detachstate
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The detachstate argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setdetachstate`` routine is used to value of the``detachstate`` attribute. This attribute controls whether the
-thread is created in a detached state.
-
-The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or``PTHREAD_CREATE_JOINABLE``. The default value for all threads is``PTHREAD_CREATE_JOINABLE``.
-
-**NOTES:**
-
-If a thread is in a detached state,
-then the use of the ID with the ``pthread_detach`` or``pthread_join`` routines is an error.
-
-pthread_attr_getdetachstate - Get Detach State
-----------------------------------------------
-.. index:: pthread_attr_getdetachstate
-.. index:: get detach state
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getdetachstate(
- const pthread_attr_t \*attr,
- int \*detachstate
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The detatchstate pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getdetachstate`` routine is used to obtain the
-current value of the ``detachstate`` attribute as specified
-by the ``attr`` thread attribute object.
-
-**NOTES:**
-
-NONE
-
-pthread_attr_setstacksize - Set Thread Stack Size
--------------------------------------------------
-.. index:: pthread_attr_setstacksize
-.. index:: set thread stack size
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setstacksize(
- pthread_attr_t \*attr,
- size_t stacksize
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setstacksize`` routine is used to set the``stacksize`` attribute in the ``attr`` thread attribute
-object.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this
-routine is supported.
-
-If the specified stacksize is below the minimum required for this CPU
-(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum
-for this CPU.
-
-pthread_attr_getstacksize - Get Thread Stack Size
--------------------------------------------------
-.. index:: pthread_attr_getstacksize
-.. index:: get thread stack size
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getstacksize(
- const pthread_attr_t \*attr,
- size_t \*stacksize
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The stacksize pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getstacksize`` routine is used to obtain the``stacksize`` attribute in the ``attr`` thread attribute
-object.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this
-routine is supported.
-
-pthread_attr_setstackaddr - Set Thread Stack Address
-----------------------------------------------------
-.. index:: pthread_attr_setstackaddr
-.. index:: set thread stack address
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setstackaddr(
- pthread_attr_t \*attr,
- void \*stackaddr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setstackaddr`` routine is used to set the``stackaddr`` attribute in the ``attr`` thread attribute
-object.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this
-routine is supported.
-
-It is imperative to the proper operation of the system that
-each thread have sufficient stack space.
-
-pthread_attr_getstackaddr - Get Thread Stack Address
-----------------------------------------------------
-.. index:: pthread_attr_getstackaddr
-.. index:: get thread stack address
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getstackaddr(
- const pthread_attr_t \*attr,
- void \**stackaddr
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The stackaddr pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getstackaddr`` routine is used to obtain the``stackaddr`` attribute in the ``attr`` thread attribute
-object.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this
-routine is supported.
-
-pthread_attr_setscope - Set Thread Scheduling Scope
----------------------------------------------------
-.. index:: pthread_attr_setscope
-.. index:: set thread scheduling scope
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setscope(
- pthread_attr_t \*attr,
- int contentionscope
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The contention scope specified is not valid.
-
-*ENOTSUP*
- The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setscope`` routine is used to set the contention
-scope field in the thread attribute object ``attr`` to the value
-specified by ``contentionscope``.
-
-The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM``
-to indicate that the thread is to be within system scheduling contention
-or ``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be
-within the process scheduling contention scope.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_getscope - Get Thread Scheduling Scope
----------------------------------------------------
-.. index:: pthread_attr_getscope
-.. index:: get thread scheduling scope
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getscope(
- const pthread_attr_t \*attr,
- int \*contentionscope
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The contentionscope pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getscope`` routine is used to obtain the
-value of the contention scope field in the thread attributes
-object ``attr``. The current value is returned in``contentionscope``.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_setinheritsched - Set Inherit Scheduler Flag
----------------------------------------------------------
-.. index:: pthread_attr_setinheritsched
-.. index:: set inherit scheduler flag
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setinheritsched(
- pthread_attr_t \*attr,
- int inheritsched
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The specified scheduler inheritance argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setinheritsched`` routine is used to set the
-inherit scheduler field in the thread attribute object ``attr`` to
-the value specified by ``inheritsched``.
-
-The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED``
-to indicate that the thread is to inherit the scheduling policy
-and parameters fromthe creating thread, or ``PTHREAD_EXPLICIT_SCHED``
-to indicate that the scheduling policy and parameters for this thread
-are to be set from the corresponding values in the attributes object.
-If ``contentionscope`` is ``PTHREAD_INHERIT_SCHED``, then the
-scheduling attributes in the ``attr`` structure will be ignored
-at thread creation time.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_getinheritsched - Get Inherit Scheduler Flag
----------------------------------------------------------
-.. index:: pthread_attr_getinheritsched
-.. index:: get inherit scheduler flag
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getinheritsched(
- const pthread_attr_t \*attr,
- int \*inheritsched
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The inheritsched pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getinheritsched`` routine is used to
-object the current value of the inherit scheduler field in
-the thread attribute object ``attr``.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_setschedpolicy - Set Scheduling Policy
----------------------------------------------------
-.. index:: pthread_attr_setschedpolicy
-.. index:: set scheduling policy
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setschedpolicy(
- pthread_attr_t \*attr,
- int policy
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*ENOTSUP*
- The specified scheduler policy argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setschedpolicy`` routine is used to set the
-scheduler policy field in the thread attribute object ``attr`` to
-the value specified by ``policy``.
-
-Scheduling policies may be one of the following:
-
-- ``SCHED_DEFAULT``
-
-- ``SCHED_FIFO``
-
-- ``SCHED_RR``
-
-- ``SCHED_SPORADIC``
-
-- ``SCHED_OTHER``
-
-The precise meaning of each of these is discussed elsewhere in this
-manual.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_getschedpolicy - Get Scheduling Policy
----------------------------------------------------
-.. index:: pthread_attr_getschedpolicy
-.. index:: get scheduling policy
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getschedpolicy(
- const pthread_attr_t \*attr,
- int \*policy
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The specified scheduler policy argument pointer is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getschedpolicy`` routine is used to obtain the
-scheduler policy field from the thread attribute object ``attr``.
-The value of this field is returned in ``policy``.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_setschedparam - Set Scheduling Parameters
-------------------------------------------------------
-.. index:: pthread_attr_setschedparam
-.. index:: set scheduling parameters
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_setschedparam(
- pthread_attr_t \*attr,
- const struct sched_param param
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The specified scheduler parameter argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setschedparam`` routine is used to set the
-scheduler parameters field in the thread attribute object ``attr`` to
-the value specified by ``param``.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_getschedparam - Get Scheduling Parameters
-------------------------------------------------------
-.. index:: pthread_attr_getschedparam
-.. index:: get scheduling parameters
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_attr_getschedparam(
- const pthread_attr_t \*attr,
- struct sched_param \*param
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The specified scheduler parameter argument pointer is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getschedparam`` routine is used to obtain the
-scheduler parameters field from the thread attribute object ``attr``.
-The value of this field is returned in ``param``.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_attr_getaffinity_np - Get Thread Affinity Attribute
------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #define _GNU_SOURCE
- #include <pthread.h>
- int pthread_attr_getaffinity_np(
- const pthread_attr_t \*attr,
- size_t cpusetsize,
- cpu_set_t \*cpuset
- );
-
-**STATUS CODES:**
-
-*EFAULT*
- The attribute pointer argument is invalid.
-
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_getaffinity_np`` routine is used to obtain the``affinityset`` field from the thread attribute object ``attr``.
-The value of this field is returned in ``cpuset``.
-
-**NOTES:**
-
-NONE
-
-pthread_attr_setaffinity_np - Set Thread Affinity Attribute
------------------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #define _GNU_SOURCE
- #include <pthread.h>
- int pthread_attr_setaffinity_np(
- pthread_attr_t \*attr,
- size_t cpusetsize,
- const cpu_set_t \*cpuset
- );
-
-**STATUS CODES:**
-
-*EFAULT*
- The attribute pointer argument is invalid.
-
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
-
-*EINVAL*
- The ``cpuset`` did not select a valid cpu.
-
-*EINVAL*
- The ``cpuset`` selected a cpu that was invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_attr_setaffinity_np`` routine is used to set the``affinityset`` field in the thread attribute object ``attr``.
-The value of this field is returned in ``cpuset``.
-
-**NOTES:**
-
-NONE
-
-pthread_create - Create a Thread
---------------------------------
-.. index:: pthread_create
-.. index:: create a thread
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_create(
- pthread_t \*thread,
- const pthread_attr_t \*attr,
- void (\*start_routine)( void \*),
- void \*arg
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The user specified a stack address and the size of the area was not
- large enough to meet this processor’s minimum stack requirements.
-
-*EINVAL*
- The specified scheduler inheritance policy was invalid.
-
-*ENOTSUP*
- The specified contention scope was PTHREAD_SCOPE_PROCESS.
-
-*EINVAL*
- The specified thread priority was invalid.
-
-*EINVAL*
- The specified scheduling policy was invalid.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified replenishment
- period is less than the initial budget.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified low priority
- is invalid.
-
-*EAGAIN*
- The system lacked the necessary resources to create another thread, or the
- self imposed limit on the total number of threads in a process
- PTHREAD_THREAD_MAX would be exceeded.
-
-*EINVAL*
- Invalid argument passed.
-
-**DESCRIPTION:**
-
-The ``pthread_create`` routine is used to create a new thread with
-the attributes specified by ``attr``. If the ``attr`` argument
-is ``NULL``, then the default attribute set will be used. Modification
-of the contents of ``attr`` after this thread is created does not
-have an impact on this thread.
-
-The thread begins execution at the address specified by ``start_routine``
-with ``arg`` as its only argument. If ``start_routine`` returns,
-then it is functionally equivalent to the thread executing the``pthread_exit`` service.
-
-Upon successful completion, the ID of the created thread is returned in the``thread`` argument.
-
-**NOTES:**
-
-There is no concept of a single main thread in RTEMS as there is in
-a tradition UNIX system. POSIX requires that the implicit return of
-the main thread results in the same effects as if there were a call
-to ``exit``. This does not occur in RTEMS.
-
-The signal mask of the newly created thread is inherited from its
-creator and the set of pending signals for this thread is empty.
-
-pthread_exit - Terminate the Current Thread
--------------------------------------------
-.. index:: pthread_exit
-.. index:: terminate the current thread
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- void pthread_exit(
- void \*status
- );
-
-**STATUS CODES:**
-
-*NONE*
-
-**DESCRIPTION:**
-
-The ``pthread_exit`` routine is used to terminate the calling thread.
-The ``status`` is made available to any successful join with the
-terminating thread.
-
-When a thread returns from its start routine, it results in an
-implicit call to the ``pthread_exit`` routine with the return
-value of the function serving as the argument to ``pthread_exit``.
-
-**NOTES:**
-
-Any cancellation cleanup handlers that hace been pushed and not yet popped
-shall be popped in reverse of the order that they were pushed. After
-all cancellation cleanup handlers have been executed, if the
-thread has any thread-specific data, destructors for that data will
-be invoked.
-
-Thread termination does not release or free any application visible
-resources including byt not limited to mutexes, file descriptors, allocated
-memory, etc.. Similarly, exitting a thread does not result in any
-process-oriented cleanup activity.
-
-There is no concept of a single main thread in RTEMS as there is in
-a tradition UNIX system. POSIX requires that the implicit return of
-the main thread results in the same effects as if there were a call
-to ``exit``. This does not occur in RTEMS.
-
-All access to any automatic variables allocated by the threads is lost
-when the thread exits. Thus references (i.e. pointers) to local variables
-of a thread should not be used in a global manner without care. As
-a specific example, a pointer to a local variable should NOT be used
-as the return value.
-
-pthread_detach - Detach a Thread
---------------------------------
-.. index:: pthread_detach
-.. index:: detach a thread
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_detach(
- pthread_t thread
- );
-
-**STATUS CODES:**
-
-*ESRCH*
- The thread specified is invalid.
-
-*EINVAL*
- The thread specified is not a joinable thread.
-
-**DESCRIPTION:**
-
-The ``pthread_detach`` routine is used to to indicate that storage
-for ``thread`` can be reclaimed when the thread terminates without
-another thread joinging with it.
-
-**NOTES:**
-
-If any threads have previously joined with the specified thread, then they
-will remain joined with that thread. Any subsequent calls to``pthread_join`` on the specified thread will fail.
-
-.. COMMENT: pthread_getattr_np
-
-pthread_getattr_np - Get Thread Attributes
-------------------------------------------
-.. index:: pthread_getattr_np
-.. index:: get thread attributes
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #define _GNU_SOURCE
- #include <pthread.h>
- int pthread_getattr_np(
- pthread_t thread,
- pthread_attr_t \*attr
- );
-
-**STATUS CODES:**
-
-*ESRCH*
- The thread specified is invalid.
-
-*EINVAL*
- The attribute pointer argument is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_getattr_np`` routine is used to obtain the
-attributes associated with ``thread``.
-
-**NOTES:**
-
-Modification of the execution modes and priority through the Classic API
-may result in a combination that is not representable in the POSIX API.
-
-pthread_join - Wait for Thread Termination
-------------------------------------------
-.. index:: pthread_join
-.. index:: wait for thread termination
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_join(
- pthread_t thread,
- void \**value_ptr
- );
-
-**STATUS CODES:**
-
-*ESRCH*
- The thread specified is invalid.
-
-*EINVAL*
- The thread specified is not a joinable thread.
-
-*EDEADLK*
- A deadlock was detected or thread is the calling thread.
-
-**DESCRIPTION:**
-
-The ``pthread_join`` routine suspends execution of the calling thread
-until ``thread`` terminates. If ``thread`` has already terminated,
-then this routine returns immediately. The value returned by ``thread``
-(i.e. passed to ``pthread_exit`` is returned in ``value_ptr``.
-
-When this routine returns, then ``thread`` has been terminated.
-
-**NOTES:**
-
-The results of multiple simultaneous joins on the same thread is undefined.
-
-If any threads have previously joined with the specified thread, then they
-will remain joined with that thread. Any subsequent calls to``pthread_join`` on the specified thread will fail.
-
-If value_ptr is NULL, then no value is returned.
-
-pthread_self - Get Thread ID
-----------------------------
-.. index:: pthread_self
-.. index:: get thread id
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- pthread_t pthread_self( void );
-
-**STATUS CODES:**
-
-The value returned is the ID of the calling thread.
-
-**DESCRIPTION:**
-
-This routine returns the ID of the calling thread.
-
-**NOTES:**
-
-NONE
-
-pthread_equal - Compare Thread IDs
-----------------------------------
-.. index:: pthread_equal
-.. index:: compare thread ids
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_equal(
- pthread_t t1,
- pthread_t t2
- );
-
-**STATUS CODES:**
-
-*zero*
- The thread ids are not equal.
-
-*non-zero*
- The thread ids are equal.
-
-**DESCRIPTION:**
-
-The ``pthread_equal`` routine is used to compare two thread
-IDs and determine if they are equal.
-
-**NOTES:**
-
-The behavior is undefined if the thread IDs are not valid.
-
-pthread_once - Dynamic Package Initialization
----------------------------------------------
-.. index:: pthread_once
-.. index:: dynamic package initialization
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- pthread_once_t once_control = PTHREAD_ONCE_INIT;
- int pthread_once(
- pthread_once_t \*once_control,
- void (\*init_routine)(void)
- );
-
-**STATUS CODES:**
-
-NONE
-
-**DESCRIPTION:**
-
-The ``pthread_once`` routine is used to provide controlled initialization
-of variables. The first call to ``pthread_once`` by any thread with the
-same ``once_control`` will result in the ``init_routine`` being
-invoked with no arguments. Subsequent calls to ``pthread_once`` with
-the same ``once_control`` will have no effect.
-
-The ``init_routine`` is guaranteed to have run to completion when
-this routine returns to the caller.
-
-**NOTES:**
-
-The behavior of ``pthread_once`` is undefined if ``once_control``
-is automatic storage (i.e. on a task stack) or is not initialized using``PTHREAD_ONCE_INIT``.
-
-pthread_setschedparam - Set Thread Scheduling Parameters
---------------------------------------------------------
-.. index:: pthread_setschedparam
-.. index:: set thread scheduling parameters
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_setschedparam(
- pthread_t thread,
- int policy,
- struct sched_param \*param
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The scheduling parameters indicated by the parameter param is invalid.
-
-*EINVAL*
- The value specified by policy is invalid.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified replenishment
- period is less than the initial budget.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified low priority
- is invalid.
-
-*ESRCH*
- The thread indicated was invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_setschedparam`` routine is used to set the
-scheduler parameters currently associated with the thread specified
-by ``thread`` to the policy specified by ``policy``. The
-contents of ``param`` are interpreted based upon the ``policy``
-argument.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-pthread_getschedparam - Get Thread Scheduling Parameters
---------------------------------------------------------
-.. index:: pthread_getschedparam
-.. index:: get thread scheduling parameters
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_getschedparam(
- pthread_t thread,
- int \*policy,
- struct sched_param \*param
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The policy pointer argument is invalid.
-
-*EINVAL*
- The scheduling parameters pointer argument is invalid.
-
-*ESRCH*
- The thread indicated by the parameter thread is invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_getschedparam`` routine is used to obtain the
-scheduler policy and parameters associated with ``thread``.
-The current policy and associated parameters values returned in``policy`` and ``param``, respectively.
-
-**NOTES:**
-
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
-
-.. COMMENT: pthread_getaffinity_np
-
-pthread_getaffinity_np - Get Thread Affinity
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #define _GNU_SOURCE
- #include <pthread.h>
- int pthread_getaffinity_np(
- const pthread_t id,
- size_t cpusetsize,
- cpu_set_t \*cpuset
- );
-
-**STATUS CODES:**
-
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
-
-**DESCRIPTION:**
-
-The ``pthread_getaffinity_np`` routine is used to obtain the``affinity.set`` field from the thread control object associated
-with the ``id``. The value of this field is returned in ``cpuset``.
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: pthread_setaffinity_np
-
-pthread_setaffinity_np - Set Thread Affinity
---------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #define _GNU_SOURCE
- #include <pthread.h>
- int pthread_setaffinity_np(
- pthread_t id,
- size_t cpusetsize,
- const cpu_set_t \*cpuset
- );
-
-**STATUS CODES:**
-
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
-
-*EINVAL*
- The ``cpuset`` did not select a valid cpu.
-
-*EINVAL*
- The ``cpuset`` selected a cpu that was invalid.
-
-**DESCRIPTION:**
-
-The ``pthread_setaffinity_np`` routine is used to set the``affinityset`` field of the thread object ``id``.
-The value of this field is returned in ``cpuset``
-
-**NOTES:**
-
-NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Key Manager
-###########
-
-Introduction
-============
-
-The key manager allows for the creation and deletion of Data keys
-specific to threads.
-
-The directives provided by the key manager are:
-
-- ``pthread_key_create`` - Create Thread Specific Data Key
-
-- ``pthread_key_delete`` - Delete Thread Specific Data Key
-
-- ``pthread_setspecific`` - Set Thread Specific Key Value
-
-- ``pthread_getspecific`` - Get Thread Specific Key Value
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the key 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.
-
-pthread_key_create - Create Thread Specific Data Key
-----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_key_create(
- pthread_key_t \*key,
- void (\*destructor)( void )
- );
-
-**STATUS CODES:**
-
-*EAGAIN*
- There were not enough resources available to create another key.
-
-*ENOMEM*
- Insufficient memory exists to create the key.
-
-**DESCRIPTION**
-
-The pthread_key_create() function shall create a thread-specific data
-key visible to all threads in the process. Key values provided by
-pthread_key_create() are opaque objects used to locate thread-specific
-data. Although the same key value may be used by different threads, the
-values bound to the key by pthread_setspecific() are maintained on a
-per-thread basis and persist for the life of the calling thread.
-
-Upon key creation, the value NULL shall be associated with the new key
-in all active threads. Upon thread creation, the value NULL shall be
-associated with all defined keys in the new thread.
-
-**NOTES**
-
-An optional destructor function may be associated with each key value.
-At thread exit, if a key value has a non-NULL destructor pointer, and
-the thread has a non-NULL value associated with that key, the value of
-the key is set to NULL, and then the function pointed to is called with
-the previously associated value as its sole argument. The order of
-destructor calls is unspecified if more than one destructor exists for
-a thread when it exits.
-
-pthread_key_delete - Delete Thread Specific Data Key
-----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_key_delete(
- pthread_key_t key);
-
-**STATUS CODES:**
-
-*EINVAL*
- The key was invalid
-
-**DESCRIPTION:**
-
-The pthread_key_delete() function shall delete a thread-specific data key
-previously returned by pthread_key_create(). The thread-specific data
-values associated with key need not be NULL at the time pthread_key_delete()
-is called. It is the responsibility of the application to free any
-application storage or perform any cleanup actions for data structures related
-to the deleted key or associated thread-specific data in any
-threads; this cleanup can be done either before or after
-pthread_key_delete() is called. Any attempt to use key following the call to
-pthread_key_delete() results in undefined behavior.
-
-**NOTES:**
-
-The pthread_key_delete() function shall be callable from within
-destructor functions. No destructor functions shall be invoked by
-pthread_key_delete(). Any destructor function that may have been
-associated with key shall no longer be called upon thread exit.
-
-pthread_setspecific - Set Thread Specific Key Value
----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- int pthread_setspecific(
- pthread_key_t key,
- const void \*value
- );
-
-**STATUS CODES:**
-
-*EINVAL*
- The specified key is invalid.
-
-**DESCRIPTION:**
-
-The pthread_setspecific() function shall associate a thread-specific value
-with a key obtained via a previous call to pthread_key_create().
-Different threads may bind different values to the same key. These values
-are typically pointers to blocks of dynamically allocated memory that
-have been reserved for use by the calling thread.
-
-**NOTES:**
-
-The effect of calling pthread_setspecific() with a key value not obtained
-from pthread_key_create() or after key has
-been deleted with pthread_key_delete() is undefined.
-
-pthread_setspecific() may be called from a thread-specific data
-destructor function. Calling pthread_setspecific() from a thread-specific
-data destructor routine may result either in lost storage (after at least
-PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop.
-
-pthread_getspecific - Get Thread Specific Key Value
----------------------------------------------------
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- #include <pthread.h>
- void \*pthread_getspecific(
- pthread_key_t key
- );
-
-**STATUS CODES:**
-
-*NULL*
- There is no thread-specific data associated with the specified key.
-
-*non-NULL*
- The data associated with the specified key.
-
-**DESCRIPTION:**
-
-The pthread_getspecific() function shall return the value currently bound to
-the specified key on behalf of the calling thread.
-
-**NOTES:**
-
-The effect of calling pthread_getspecific() with a key value not obtained from
-pthread_key_create() or after key has
-been deleted with pthread_key_delete() is undefined.
-
-pthread_getspecific() may be called from a thread-specific data destructor
-function. A call to pthread_getspecific() for the thread-specific data key
-being destroyed shall return the value NULL, unless the value is changed
-(after the destructor starts) by a call to pthread_setspecific().
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Thread Cancellation Manager
-###########################
-
-Introduction
-============
-
-The
-thread cancellation manager is ...
-
-The directives provided by the thread cancellation manager are:
-
-- ``pthread_cancel`` - Cancel Execution of a Thread
-
-- ``pthread_setcancelstate`` - Set Cancelability State
-
-- ``pthread_setcanceltype`` - Set Cancelability Type
-
-- ``pthread_testcancel`` - Create Cancellation Point
-
-- ``pthread_cleanup_push`` - Establish Cancellation Handler
-
-- ``pthread_cleanup_pop`` - Remove Cancellation Handler
-
-Background
-==========
-
-There is currently no text in this section.
-
-Operations
-==========
-
-There is currently no text in this section.
-
-Directives
-==========
-
-This section details the thread cancellation 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.
-
-pthread_cancel - Cancel Execution of a Thread
----------------------------------------------
-.. index:: pthread_cancel
-.. index:: cancel execution of a thread
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pthread_cancel(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_setcancelstate - Set Cancelability State
-------------------------------------------------
-.. index:: pthread_setcancelstate
-.. index:: set cancelability state
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pthread_setcancelstate(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_setcanceltype - Set Cancelability Type
-----------------------------------------------
-.. index:: pthread_setcanceltype
-.. index:: set cancelability type
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pthread_setcanceltype(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_testcancel - Create Cancellation Point
-----------------------------------------------
-.. index:: pthread_testcancel
-.. index:: create cancellation point
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pthread_testcancel(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_cleanup_push - Establish Cancellation Handler
------------------------------------------------------
-.. index:: pthread_cleanup_push
-.. index:: establish cancellation handler
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pthread_cleanup_push(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-pthread_cleanup_pop - Remove Cancellation Handler
--------------------------------------------------
-.. index:: pthread_cleanup_pop
-.. index:: remove cancellation handler
-
-**CALLING SEQUENCE:**
-
-.. code:: c
-
- int pthread_cleanup_push(
- );
-
-**STATUS CODES:**
-
-*E*
- The
-
-**DESCRIPTION:**
-
-**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Services Provided by C Library (libc)
-#####################################
-
-Introduction
-============
-
-This section lists the routines that provided by the Newlib C Library.
-
-Standard Utility Functions (stdlib.h)
-=====================================
-
-- ``abort`` - Abnormal termination of a program
-
-- ``abs`` - Integer absolute value (magnitude)
-
-- ``assert`` - Macro for Debugging Diagnostics
-
-- ``atexit`` - Request execution of functions at program exit
-
-- ``atof`` - String to double or float
-
-- ``atoi`` - String to integer
-
-- ``bsearch`` - Binary search
-
-- ``calloc`` - Allocate space for arrays
-
-- ``div`` - Divide two integers
-
-- ``ecvtbuf`` - Double or float to string of digits
-
-- ``ecvt`` - Double or float to string of digits (malloc result)
-
-- ``__env_lock`` - Lock environment list for getenv and setenv
-
-- ``gvcvt`` - Format double or float as string
-
-- ``exit`` - End program execution
-
-- ``getenv`` - Look up environment variable
-
-- ``labs`` - Long integer absolute value (magnitude)
-
-- ``ldiv`` - Divide two long integers
-
-- ``malloc`` - Allocate memory
-
-- ``realloc`` - Reallocate memory
-
-- ``free`` - Free previously allocated memory
-
-- ``mallinfo`` - Get information about allocated memory
-
-- ``__malloc_lock`` - Lock memory pool for malloc and free
-
-- ``mbstowcs`` - Minimal multibyte string to wide string converter
-
-- ``mblen`` - Minimal multibyte length
-
-- ``mbtowc`` - Minimal multibyte to wide character converter
-
-- ``qsort`` - Sort an array
-
-- ``rand`` - Pseudo-random numbers
-
-- ``strtod`` - String to double or float
-
-- ``strtol`` - String to long
-
-- ``strtoul`` - String to unsigned long
-
-- ``system`` - Execute command string
-
-- ``wcstombs`` - Minimal wide string to multibyte string converter
-
-- ``wctomb`` - Minimal wide character to multibyte converter
-
-Character Type Macros and Functions (ctype.h)
-=============================================
-
-- ``isalnum`` - Alphanumeric character predicate
-
-- ``isalpha`` - Alphabetic character predicate
-
-- ``isascii`` - ASCII character predicate
-
-- ``iscntrl`` - Control character predicate
-
-- ``isdigit`` - Decimal digit predicate
-
-- ``islower`` - Lower-case character predicate
-
-- ``isprint`` - Printable character predicates (isprint, isgraph)
-
-- ``ispunct`` - Punctuation character predicate
-
-- ``isspace`` - Whitespace character predicate
-
-- ``isupper`` - Uppercase character predicate
-
-- ``isxdigit`` - Hexadecimal digit predicate
-
-- ``toascii`` - Force integers to ASCII range
-
-- ``tolower`` - Translate characters to lower case
-
-- ``toupper`` - Translate characters to upper case
-
-Input and Output (stdio.h)
-==========================
-
-- ``clearerr`` - Clear file or stream error indicator
-
-- ``fclose`` - Close a file
-
-- ``feof`` - Test for end of file
-
-- ``ferror`` - Test whether read/write error has occurred
-
-- ``fflush`` - Flush buffered file output
-
-- ``fgetc`` - Get a character from a file or stream
-
-- ``fgetpos`` - Record position in a stream or file
-
-- ``fgets`` - Get character string from a file or stream
-
-- ``fiprintf`` - Write formatted output to file (integer only)
-
-- ``fopen`` - Open a file
-
-- ``fdopen`` - Turn an open file into a stream
-
-- ``fputc`` - Write a character on a stream or file
-
-- ``fputs`` - Write a character string in a file or stream
-
-- ``fread`` - Read array elements from a file
-
-- ``freopen`` - Open a file using an existing file descriptor
-
-- ``fseek`` - Set file position
-
-- ``fsetpos`` - Restore position of a stream or file
-
-- ``ftell`` - Return position in a stream or file
-
-- ``fwrite`` - Write array elements from memory to a file or stream
-
-- ``getc`` - Get a character from a file or stream (macro)
-
-- ``getchar`` - Get a character from standard input (macro)
-
-- ``gets`` - Get character string from standard input (obsolete)
-
-- ``iprintf`` - Write formatted output (integer only)
-
-- ``mktemp`` - Generate unused file name
-
-- ``perror`` - Print an error message on standard error
-
-- ``putc`` - Write a character on a stream or file (macro)
-
-- ``putchar`` - Write a character on standard output (macro)
-
-- ``puts`` - Write a character string on standard output
-
-- ``remove`` - Delete a file’s name
-
-- ``rename`` - Rename a file
-
-- ``rewind`` - Reinitialize a file or stream
-
-- ``setbuf`` - Specify full buffering for a file or stream
-
-- ``setvbuf`` - Specify buffering for a file or stream
-
-- ``siprintf`` - Write formatted output (integer only)
-
-- ``printf`` - Write formatted output
-
-- ``scanf`` - Scan and format input
-
-- ``tmpfile`` - Create a temporary file
-
-- ``tmpnam`` - Generate name for a temporary file
-
-- ``vprintf`` - Format variable argument list
-
-Strings and Memory (string.h)
-=============================
-
-- ``bcmp`` - Compare two memory areas
-
-- ``bcopy`` - Copy memory regions
-
-- ``bzero`` - Initialize memory to zero
-
-- ``index`` - Search for character in string
-
-- ``memchr`` - Find character in memory
-
-- ``memcmp`` - Compare two memory areas
-
-- ``memcpy`` - Copy memory regions
-
-- ``memmove`` - Move possibly overlapping memory
-
-- ``memset`` - Set an area of memory
-
-- ``rindex`` - Reverse search for character in string
-
-- ``strcasecmp`` - Compare strings ignoring case
-
-- ``strcat`` - Concatenate strings
-
-- ``strchr`` - Search for character in string
-
-- ``strcmp`` - Character string compare
-
-- ``strcoll`` - Locale specific character string compare
-
-- ``strcpy`` - Copy string
-
-- ``strcspn`` - Count chars not in string
-
-- ``strerror`` - Convert error number to string
-
-- ``strlen`` - Character string length
-
-- ``strlwr`` - Convert string to lower case
-
-- ``strncasecmp`` - Compare strings ignoring case
-
-- ``strncat`` - Concatenate strings
-
-- ``strncmp`` - Character string compare
-
-- ``strncpy`` - Counted copy string
-
-- ``strpbrk`` - Find chars in string
-
-- ``strrchr`` - Reverse search for character in string
-
-- ``strspn`` - Find initial match
-
-- ``strstr`` - Find string segment
-
-- ``strtok`` - Get next token from a string
-
-- ``strupr`` - Convert string to upper case
-
-- ``strxfrm`` - Transform string
-
-Signal Handling (signal.h)
-==========================
-
-- ``raise`` - Send a signal
-
-- ``signal`` - Specify handler subroutine for a signal
-
-Time Functions (time.h)
-=======================
-
-- ``asctime`` - Format time as string
-
-- ``clock`` - Cumulative processor time
-
-- ``ctime`` - Convert time to local and format as string
-
-- ``difftime`` - Subtract two times
-
-- ``gmtime`` - Convert time to UTC (GMT) traditional representation
-
-- ``localtime`` - Convert time to local representation
-
-- ``mktime`` - Convert time to arithmetic representation
-
-- ``strftime`` - Flexible calendar time formatter
-
-- ``time`` - Get current calendar time (as single number)
-
-Locale (locale.h)
-=================
-
-- ``setlocale`` - Select or query locale
-
-Reentrant Versions of Functions
-===============================
-
-- Equivalent for errno variable:
- - ``errno_r`` - XXX
-
-- Locale functions:
- - ``localeconv_r`` - XXX
- - ``setlocale_r`` - XXX
-
-- Equivalents for stdio variables:
- - ``stdin_r`` - XXX
- - ``stdout_r`` - XXX
- - ``stderr_r`` - XXX
-
-- Stdio functions:
- - ``fdopen_r`` - XXX
- - ``perror_r`` - XXX
- - ``tempnam_r`` - XXX
- - ``fopen_r`` - XXX
- - ``putchar_r`` - XXX
- - ``tmpnam_r`` - XXX
- - ``getchar_r`` - XXX
- - ``puts_r`` - XXX
- - ``tmpfile_r`` - XXX
- - ``gets_r`` - XXX
- - ``remove_r`` - XXX
- - ``vfprintf_r`` - XXX
- - ``iprintf_r`` - XXX
- - ``rename_r`` - XXX
- - ``vsnprintf_r`` - XXX
- - ``mkstemp_r`` - XXX
- - ``snprintf_r`` - XXX
- - ``vsprintf_r`` - XXX
- - ``mktemp_t`` - XXX
- - ``sprintf_r`` - XXX
-
-- Signal functions:
- - ``init_signal_r`` - XXX
- - ``signal_r`` - XXX
- - ``kill_r`` - XXX
- - ``_sigtramp_r`` - XXX
- - ``raise_r`` - XXX
-
-- Stdlib functions:
- - ``calloc_r`` - XXX
- - ``mblen_r`` - XXX
- - ``srand_r`` - XXX
- - ``dtoa_r`` - XXX
- - ``mbstowcs_r`` - XXX
- - ``strtod_r`` - XXX
- - ``free_r`` - XXX
- - ``mbtowc_r`` - XXX
- - ``strtol_r`` - XXX
- - ``getenv_r`` - XXX
- - ``memalign_r`` - XXX
- - ``strtoul_r`` - XXX
- - ``mallinfo_r`` - XXX
- - ``mstats_r`` - XXX
- - ``system_r`` - XXX
- - ``malloc_r`` - XXX
- - ``rand_r`` - XXX
- - ``wcstombs_r`` - XXX
- - ``malloc_r`` - XXX
- - ``realloc_r`` - XXX
- - ``wctomb_r`` - XXX
- - ``malloc_stats_r`` - XXX
- - ``setenv_r`` - XXX
-
-- String functions:
- - ``strtok_r`` - XXX
-
-- System functions:
- - ``close_r`` - XXX
- - ``link_r`` - XXX
- - ``unlink_r`` - XXX
- - ``execve_r`` - XXX
- - ``lseek_r`` - XXX
- - ``wait_r`` - XXX
- - ``fcntl_r`` - XXX
- - ``open_r`` - XXX
- - ``write_r`` - XXX
- - ``fork_r`` - XXX
- - ``read_r`` - XXX
- - ``fstat_r`` - XXX
- - ``sbrk_r`` - XXX
- - ``gettimeofday_r`` - XXX
- - ``stat_r`` - XXX
- - ``getpid_r`` - XXX
- - ``times_r`` - XXX
-
-- Time function:
- - ``asctime_r`` - XXX
-
-Miscellaneous Macros and Functions
-==================================
-
-- ``unctrl`` - Return printable representation of a character
-
-Variable Argument Lists
-=======================
-
-- Stdarg (stdarg.h):
- - ``va_start`` - XXX
- - ``va_arg`` - XXX
- - ``va_end`` - XXX
-
-- Vararg (varargs.h):
- - ``va_alist`` - XXX
- - ``va_start-trad`` - XXX
- - ``va_arg-trad`` - XXX
- - ``va_end-trad`` - XXX
-
-Reentrant System Calls
-======================
-
-- ``open_r`` - XXX
-
-- ``close_r`` - XXX
-
-- ``lseek_r`` - XXX
-
-- ``read_r`` - XXX
-
-- ``write_r`` - XXX
-
-- ``fork_r`` - XXX
-
-- ``wait_r`` - XXX
-
-- ``stat_r`` - XXX
-
-- ``fstat_r`` - XXX
-
-- ``link_r`` - XXX
-
-- ``unlink_r`` - XXX
-
-- ``sbrk_r`` - XXX
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Services Provided by the Math Library (libm)
-############################################
-
-Introduction
-============
-
-This section lists the routines that provided by the Newlib Math Library
-(libm).
-
-Standard Math Functions (math.h)
-================================
-
-- ``acos`` - Arccosine
-
-- ``acosh`` - Inverse hyperbolic cosine
-
-- ``asin`` - Arcsine
-
-- ``asinh`` - Inverse hyperbolic sine
-
-- ``atan`` - Arctangent
-
-- ``atan2`` - Arctangent of y/x
-
-- ``atanh`` - Inverse hyperbolic tangent
-
-- ``jN`` - Bessel functions (jN and yN)
-
-- ``cbrt`` - Cube root
-
-- ``copysign`` - Sign of Y and magnitude of X
-
-- ``cosh`` - Hyperbolic cosine
-
-- ``erf`` - Error function (erf and erfc)
-
-- ``exp`` - Exponential
-
-- ``expm1`` - Exponential of x and - 1
-
-- ``fabs`` - Absolute value (magnitude)
-
-- ``floor`` - Floor and ceiling (floor and ceil)
-
-- ``fmod`` - Floating-point remainder (modulo)
-
-- ``frexp`` - Split floating-point number
-
-- ``gamma`` - Logarithmic gamma function
-
-- ``hypot`` - Distance from origin
-
-- ``ilogb`` - Get exponent
-
-- ``infinity`` - Floating infinity
-
-- ``isnan`` - Check type of number
-
-- ``ldexp`` - Load exponent
-
-- ``log`` - Natural logarithms
-
-- ``log10`` - Base 10 logarithms
-
-- ``log1p`` - Log of 1 + X
-
-- ``matherr`` - Modifiable math error handler
-
-- ``modf`` - Split fractional and integer parts
-
-- ``nan`` - Floating Not a Number
-
-- ``nextafter`` - Get next representable number
-
-- ``pow`` - X to the power Y
-
-- ``remainder`` - remainder of X divided by Y
-
-- ``scalbn`` - scalbn
-
-- ``sin`` - Sine or cosine (sin and cos)
-
-- ``sinh`` - Hyperbolic sine
-
-- ``sqrt`` - Positive square root
-
-- ``tan`` - Tangent
-
-- ``tanh`` - Hyperbolic tangent
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Status of Implementation
-########################
-
-This chapter provides an overview of the status of the implementation
-of the POSIX API for RTEMS. The *POSIX 1003.1b Compliance Guide*
-provides more detailed information regarding the implementation of
-each of the numerous functions, constants, and macros specified by
-the POSIX 1003.1b standard.
-
-RTEMS supports many of the process and user/group oriented services
-in a "single user/single process" manner. This means that although
-these services may be of limited usefulness or functionality, they
-are provided and do work in a coherent manner. This is significant
-when porting existing code from UNIX to RTEMS.
-
-- Implementation
- - The current implementation of ``dup()`` is insufficient.
- - FIFOs ``mkfifo()`` are not currently implemented.
- - Asynchronous IO is not implemented.
- - The ``flockfile()`` family is not implemented
- - getc/putc unlocked family is not implemented
- - Shared Memory is not implemented
- - Mapped Memory is not implemented
-
- - NOTES:
-
- - For Shared Memory and Mapped Memory services, it is unclear what
- level of support is appropriate and possible for RTEMS.
-
-- Functional Testing
- - Tests for unimplemented services
-
-- Performance Testing
- - There are no POSIX Performance Tests.
-
-- Documentation
-
- - Many of the service description pages are not complete in this
- manual. These need to be completed and information added to the
- background and operations sections.
-
- - Example programs (not just tests) would be very nice.
-
-Command and Variable Index
-##########################
-
-.. COMMENT: There are currently no Command and Variable Index entries.
-
-Concept Index
-#############
-
-.. COMMENT: There are currently no Concept Index entries.
-
diff --git a/shell/shell_old_reference_only.rst b/shell/shell_old_reference_only.rst
deleted file mode 100644
index 558e286..0000000
--- a/shell/shell_old_reference_only.rst
+++ /dev/null
@@ -1,6998 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-:orphan:
-
-.. COMMENT: COPYRIGHT (c) 1988-2013.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.
-.. COMMENT:
-.. COMMENT: Master file for the Shell User's Guide
-.. COMMENT:
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-========================
-RTEMS Shell User’s Guide
-========================
-
-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 at http://www.rtems.org/.
-
-RTEMS Shell User’s Guide
-########################
-
-Preface
-#######
-
-Real-time embedded systems vary widely based upon their operational and
-maintenance requirements. Some of these systems provide ways for the user or
-developer to interact with them. This interaction could be used for
-operational, diagnostic, or configuration purposes. The capabilities described
-in this manual are those provided with RTEMS to provide a command line
-interface for user access. Some of these commands will be familiar as standard
-POSIX utilities while others are RTEMS specific or helpful in debugging and
-analyzing an embedded system. As a simple example of the powerful and very
-familiar capabilities that the RTEMS Shell provides to an application, consider
-the following example which hints at some of the capabilities available:
-
-.. code-block:: shell
-
- Welcome to rtems-4.10.99.0(SPARC/w/FPU/sis)
- COPYRIGHT (c) 1989-2011.
- On-Line Applications Research Corporation (OAR).
- Login into RTEMS
- login: rtems
- Password:
- RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands.
- SHLL [/] $ cat /etc/passwd
- root:*:0:0:root::/:/bin/sh
- rtems:*:1:1:RTEMS Application::/:/bin/sh
- tty:!:2:2:tty owner::/:/bin/false
- SHLL [/] $ ls /dev
- -rwxr-xr-x 1 rtems root 0 Jan 01 00:00 console
- -rwxr-xr-x 1 root root 0 Jan 01 00:00 console_b
- 2 files 0 bytes occupied
- SHLL [/] $ stackuse
- Stack usage by thread
- ID NAME LOW HIGH CURRENT AVAILABLE USED
- 0x09010001 IDLE 0x023d89a0 - 0x023d99af 0x023d9760 4096 608
- 0x0a010001 UI1 0x023d9f30 - 0x023daf3f 0x023dad18 4096 1804
- 0x0a010002 SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0 16384 6204
- 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316
- SHLL [/] $ mount -L
- File systems: msdos
- SHLL [/] $
-
-In the above example, the user *rtems* logs into a SPARC based RTEMS system.
-The first command is ``cat /etc/passwd``. This simple command lets us know
-that this application is running the In Memory File System (IMFS) and that the
-infrastructure has provided dummy entries for */etc/passwd* and a few other
-files. The contents of */etc/passwd* let us know that the user could have
-logged in as ``root``. In fact, the ``root`` user has more permissions than
-``rtems`` who is not allowed to write into the filesystem.
-
-The second command is ``ls /dev`` which lets us know that RTEMS has POSIX-style
-device nodes which can be accesses through standard I/O function calls.
-
-The third command executed is the RTEMS specific ``stackuse`` which gives a
-report on the stack usage of each thread in the system. Since stack overflows
-are a common error in deeply embedded systems, this is a surprising simple, yet
-powerful debugging aid.
-
-Finally, the last command, ``mount -L`` hints that RTEMS supports a variety of
-mountable filesystems. With support for MS-DOS FAT on IDE/ATA and Flash devices
-as well as network-based filesystens such as NFS and TFTP, the standard free
-RTEMS provides a robuse infrastructure for embedded applications.
-
-This manual describes the RTEMS Shell and its command set. In our terminology,
-the Shell is just a loop reading user input and turning that input into
-commands with argument. The Shell provided with RTEMS is a simple command
-reading loop with limited scripting capabilities. It can be connected to via a
-standard serial port or connected to the RTEMS ``telnetd`` server for use across
-a network.
-
-Each command in the command set is implemented as a single subroutine which has
-a *main-style* prototype. The commands interpret their arguments and operate
-upon stdin, stdout, and stderr by default. This allows each command to be
-invoked independent of the shell.
-
-The described separation of shell from commands from communications mechanism
-was an important design goal. At one level, the RTEMS Shell is a complete
-shell environment providing access to multiple POSIX compliant filesystems and
-TCP/IP stack. The subset of capabilities available is easy to configure and
-the standard Shell can be logged into from either a serial port or via telnet.
-But at another level, the Shell is a large set of components which can be
-integrated into the user’s developed command interpreter. In either case, it
-is trivial to add custom commands to the command set available.
-
-Acknowledgements
-================
-
-.. COMMENT: The RTEMS Project has been granted permission from The Open Group
-.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents
-.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
-.. COMMENT: We have to include a specific acknowledgement paragraph in these
-.. COMMENT: documents (e.g. preface or copyright page) and another slightly
-.. COMMENT: different paragraph for each manual page that excerpts and uses
-.. COMMENT: text from the standards.
-.. COMMENT: This file should help ensure that the paragraphs are consistent
-.. COMMENT: and not duplicated
-
-The Institute of Electrical and Electronics Engineers, Inc and The Open Group,
-have given us permission to reprint portions of their documentation.
-
-.. pull-quote::
-
- Portions of this text are reprinted and reproduced in electronic form from
- IEEE Std 1003.1, 2004 Edition, Standard for Information Technology â
- Operating System Interface (POSIX), The Open Group Base Specifications
- Issue 6, Copyright © 2001-2004 by the Institute of Electrical and
- Electronics Engineers, Inc and The Open Group. In the event of any
- discrepancy between this version and the original IEEE and The Open Group
- Standard, the original IEEE and The Open Group Standard is the referee
- document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html. This notice shall appear on any
- product containing this material.
-
-Configuration and Initialization
-################################
-
-Introduction
-============
-
-This chapter provides information on how the application configures and
-initializes the RTEMS shell.
-
-Configuration
-=============
-
-The command set available to the application is user configurable. It is
-configured using a mechanism similar to the ``confdefs.h`` mechanism used to
-specify application configuration.
-
-In the simplest case, if the user wishes to configure a command set with all
-commands available that are neither filesystem management (e.g. mounting,
-formating, etc.) or network related, then the following is all that is
-required:
-
-.. code-block:: c
-
- #define CONFIGURE_SHELL_COMMANDS_INIT
- #define CONFIGURE_SHELL_COMMANDS_ALL
- #include <rtems/shellconfig.h>
-
-In a slightly more complex example, if the user wishes to include all
-networking commands as well as support for mounting MS-DOS and NFS filesystems,
-then the following is all that is required:
-
-.. code-block:: c
-
- #define CONFIGURE_SHELL_COMMANDS_INIT
- #define CONFIGURE_SHELL_COMMANDS_ALL
- #define CONFIGURE_SHELL_MOUNT_MSDOS
- #define CONFIGURE_SHELL_MOUNT_NFS
- #include <rtems/shellconfig.h>
-
-Customizing the Command Set
----------------------------
-
-The user can configure specific command sets by either building up the set from
-individual commands or starting with a complete set and disabling individual
-commands. Each command has two configuration macros associated with it.
-
-*CONFIGURE_SHELL_COMMAND_XXX*
- Each command has a constant of this form which is defined when
- building a command set by individually enabling specific
- commands.
-
-*CONFIGURE_SHELL_NO_COMMAND_XXX*
- In contrast, each command has a similar command which is
- defined when the application is configuring a command set
- by disabling specific commands in the set.
-
-Adding Custom Commands
-----------------------
-
-One of the design goals of the RTEMS Shell was to make it easy for a user to
-add custom commands specific to their application. We believe this design goal
-was accomplished. In order to add a custom command, the user is required to do
-the following:
-
-- Provide a *main-style* function which implements the command. If that
- command function uses a ``getopt`` related function to parse arguments, it
- *MUST* use the reentrant form.
-
-- Provide a command definition structure of type ``rtems_shell_cmd_t``.
-
-- Configure that command using the ``CONFIGURE_SHELL_USER_COMMANDS`` macro.
-
-Custom aliases are configured similarly but the user only provides an alias
-definition structure of type ``rtems_shell_alias_t`` and configures the alias
-via the ``CONFIGURE_SHELL_USER_ALIASES`` macro.
-
-In the following example, we have implemented a custom command named
-``usercmd`` which simply prints the arguments it was passed. We have also
-provided an alias for ``usercmd`` named ``userecho``.
-
-.. code-block:: c
-
- #include <rtems/shell.h>
- int main_usercmd(int argc, char **argv)
- {
- int i;
- printf( "UserCommand: argc=%d\n", argc );
- for (i=0 ; i<argc ; i++ )
- printf( "argv[%d]= %s\n", i, argv[i] );
- return 0;
- }
- rtems_shell_cmd_t Shell_USERCMD_Command = {
- "usercmd", /* name */
- "usercmd n1 \[n2 \[n3...]]", /* usage */
- "user", /* topic */
- main_usercmd, /* command */
- NULL, /* alias */
- NULL /* next */
- };
- rtems_shell_alias_t Shell_USERECHO_Alias = {
- "usercmd", /* command */
- "userecho" /* alias */
- };
- #define CONFIGURE_SHELL_USER_COMMANDS &Shell_USERCMD_Command
- #define CONFIGURE_SHELL_USER_ALIASES &Shell_USERECHO_Alias
- #define CONFIGURE_SHELL_COMMANDS_INIT
- #define CONFIGURE_SHELL_COMMANDS_ALL
- #define CONFIGURE_SHELL_MOUNT_MSDOS
- #include <rtems/shellconfig.h>
-
-Notice in the above example, that the user wrote the*main* for their command
-(e.g. ``main_usercmd``) which looks much like any other ``main()``. They then
-defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which
-describes that command. This command definition structure is registered into
-the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS``
-to ``&Shell_USERCMD_Command``.
-
-Similarly, to add the ``userecho`` alias, the user provides the alias
-definition structure named ``Shell_USERECHO_Alias`` and defines
-``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias.
-
-The user can configure any number of commands and aliases in this manner.
-
-Initialization
-==============
-
-The shell may be easily attached to a serial port or to the ``telnetd`` server.
-This section describes how that is accomplished.
-
-Attached to a Serial Port
--------------------------
-
-Starting the shell attached to the console or a serial port is very simple. The
-user invokes ``rtems_shell_init`` with parameters to indicate the
-characteristics of the task that will be executing the shell including name,
-stack size, and priority. The user also specifies the device that the shell is
-to be attached to.
-
-This example is taken from the ``fileio`` sample test. This shell portion of
-this test can be run on any target which provides a console with input and
-output capabilities. It does not include any commands which cannot be
-supported on all BSPs. The source code for this test is in
-``testsuites/samples/fileio`` with the shell configuration in the ``init.c``
-file.
-
-.. code-block:: c
-
- #include <rtems/shell.h>
- void start_shell(void)
- {
- printf(" =========================\n");
- printf(" starting shell\n");
- printf(" =========================\n");
- rtems_shell_init(
- "SHLL", /* task name */
- RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */
- 100, /* task priority */
- "/dev/console", /* device name */
- false, /* run forever */
- true, /* wait for shell to terminate */
- rtems_shell_login_check /* login check function,
- use NULL to disable a login check */
- );
- }
-
-In the above example, the call to ``rtems_shell_init`` spawns a task to run the
-RTEMS Shell attached to ``/dev/console`` and executing at priority 100. The
-caller suspends itself and lets the shell take over the console device. When
-the shell is exited by the user, then control returns to the caller.
-
-Attached to a Socket
---------------------
-
-TBD
-
-Access Control
-==============
-
-Login Checks
-------------
-
-Login checks are optional for the RTEMS shell and can be configured via a login
-check handler passed to ``rtems_shell_init()``. One login check handler
-is ``rtems_shell_login_check()``.
-
-Configuration Files
--------------------
-
-The following files are used by the login check handler
-``rtems_shell_login_check()`` to validate a passphrase for a user and to set up
-the user environment for the shell command execution.
-
-:file:`/etc/passwd`
- The format for each line is
-
- .. code:: c
-
- user_name:password:UID:GID:GECOS:directory:shell
-
- with colon separated fields. For more information refer to the Linux
- PASSWD(5) man page. Use a ``password`` of ``*`` to disable the login of the
- user. An empty password allows login without a password for this user. In
- contrast to standard UNIX systems, this file is only readable and writeable
- for the user with an UID of zero by default. The ``directory`` is used to
- perform a filesystem change root operation in ``rtems_shell_login_check()``
- in contrast to a normal usage as the HOME directory of the user.
- The *default* content is:
-
- .. code:: c
-
- root::0:0::::
-
- so there is *no password required* for the ``root`` user.
-
-:file:`/etc/group`
- The format for each line is:
-
- .. code:: c
-
- group_name:password:GID:user_list
-
- with colon separated fields. The ``user_list`` is comma separated. For
- more information refer to the Linux GROUP(5) man page. In contrast to
- standard UNIX systems, this file is only readable and writeable for the
- user with an UID of zero by default. The default content is
-
- .. code:: c
-
- root::0:
-
-Command Visibility and Execution Permission
--------------------------------------------
-
-Each command has:
-
-- an owner,
-
-- a group, and
-
-- a read permission flag for the owner, the group and all other users, and
-
-- an execution permission flag for the owner, the group and all other
- users.
-
-The read and write permission flags are stored in the command mode. The read
-permission flags determine the visibility of the command for the current user.
-The execution permission flags determine the ability to execute a command for
-the current user. These command properties can be displayed and changed with
-the:
-
-- ``cmdls``,
-
-- ``cmdchown``, and
-
-- ``cmdchmod``
-
-commands. The access is determined by the effective UID, the effective GID and
-the supplementary group IDs of the current user and follows the standard
-filesystem access procedure.
-
-Add CRYPT(3) Formats
---------------------
-
-By default the ``crypt_r()`` function used by ``rtems_shell_login_check()``
-supports only plain text passphrases. Use ``crypt_add_format()`` to add more
-formats. The following formats are available out of the box:
-
-- ``crypt_md5_format``,
-
-- ``crypt_sha256_format``, and
-
-- ``crypt_sha512_format``.
-
-An example follows:
-
-.. index:: crypt_add_format
-
-.. code:: c
-
- #include <crypt.h>
- void add_formats( void )
- {
- crypt_add_format( &crypt_md5_format );
- crypt_add_format( &crypt_sha512_format );
- }
-
-Functions
-=========
-
-This section describes the Shell related C functions which are publicly
-available related to initialization and configuration.
-
-rtems_shell_init - Initialize the shell
----------------------------------------
-.. index:: initialization
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_shell_init
-
-.. code-block:: c
-
- rtems_status_code rtems_shell_init(
- const char *task_name,
- size_t task_stacksize,
- rtems_task_priority task_priority,
- const char *devname,
- bool forever,
- bool wait,
- rtems_login_check login_check
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``RTEMS_SUCCESSFUL`` - Shell task spawned successfully
-
-others - to indicate a failure condition
-
-**DESCRIPTION:**
-
-This service creates a task with the specified characteristics to run the RTEMS
-Shell attached to the specified ``devname``.
-
-.. note::
-
- This method invokes the ``rtems_task_create`` and ``rtems_task_start``
- directives and as such may return any status code that those directives may
- return.
-
- There is one POSIX key necessary for all shell instances together and one
- POSIX key value pair per instance. You should make sure that your RTEMS
- configuration accounts for these resources.
-
-rtems_shell_login_check - Default login check handler
------------------------------------------------------
-.. index:: initialization
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_shell_login_check
-
-.. code:: c
-
- bool rtems_shell_login_check(
- const char \*user,
- const char \*passphrase
- );
-
-**DIRECTIVE STATUS CODES:**
-
-``true`` - login is allowed, and
-``false`` - otherwise.
-
-**DESCRIPTION:**
-
-This function checks if the specified passphrase is valid for the specified
-user.
-
-.. note::
-
- As a side-effect if the specified passphrase is valid for the specified
- user, this function:
-
- - performs a filesystem change root operation to the directory of the
- specified user if the directory path is non-empty,
-
- - changes the owner of the current shell device to the UID of the specified
- user,
-
- - sets the real and effective UID of the current user environment to the
- UID of the specified user,
-
- - sets the real and effective GID of the current user environment to the
- GID of the specified user, and
-
- - sets the supplementary group IDs of the current user environment to the
- supplementary group IDs of the specified user.
-
- In case the filesystem change root operation fails, then the environment
- setup is aborted and ``false`` is returned.
-
-General Commands
-################
-
-Introduction
-============
-
-The RTEMS shell has the following general commands:
-
-- ``help`` - Print command help
-
-- ``alias`` - Add alias for an existing command
-
-- ``cmdls`` - List commands
-
-- ``cmdchown`` - Change user or owner of commands
-
-- ``cmdchmod`` - Change mode of commands
-
-- ``date`` - Print or set current date and time
-
-- ``echo`` - Produce message in a shell script
-
-- ``sleep`` - Delay for a specified amount of time
-
-- ``id`` - show uid gid euid and egid
-
-- ``tty`` - show ttyname
-
-- ``whoami`` - print effective user id
-
-- ``getenv`` - print environment variable
-
-- ``setenv`` - set environment variable
-
-- ``unsetenv`` - unset environment variable
-
-- ``time`` - time command execution
-
-- ``logoff`` - logoff from the system
-
-- ``rtc`` - RTC driver configuration
-
-- ``exit`` - alias for logoff command
-
-Commands
-========
-
-This section details the General Commands available. A subsection is dedicated
-to each of the commands and describes the behavior and configuration of that
-command as well as providing an example usage.
-
-help - Print command help
--------------------------
-.. index:: help
-
-**SYNOPSYS:**
-
-.. code:: c
-
- help misc
-
-**DESCRIPTION:**
-
-This command prints the command help. Help without arguments prints a list of
-topics and help with a topic prints the help for that topic.
-
-**EXIT STATUS:**
-
-This command returns 0.
-
-**NOTES:**
-
-The help print will break the output up based on the environment variable
-SHELL_LINES. If this environment variable is not set the default is 16
-lines. If set the number of lines is set to that the value. If the shell lines
-is set 0 there will be no break.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``alias``:
-
-.. code-block:: shell
-
- SHLL [/] $ help
- help: ('r' repeat last cmd - 'e' edit last cmd)
- TOPIC? The topics are
- mem, misc, files, help, rtems, network, monitor
- SHLL [/] $ help misc
- help: list for the topic 'misc'
- alias - alias old new
- time - time command [arguments...]
- joel - joel [args] SCRIPT
- date - date [YYYY-MM-DD HH:MM:SS]
- echo - echo [args]
- sleep - sleep seconds [nanoseconds]
- id - show uid, gid, euid, and egid
- tty - show ttyname
- whoami - show current user
- logoff - logoff from the system
- setenv - setenv [var] [string]
- getenv - getenv [var]
- unsetenv - unsetenv [var]
- umask - umask [new_umask]
- Press any key to continue...
- rtc - real time clock read and set
- SHLL [/] $ setenv SHELL_ENV 0
- SHLL [/] $ help misc
- help: list for the topic 'misc'
- alias - alias old new
- time - time command [arguments...]
- joel - joel [args] SCRIPT
- date - date [YYYY-MM-DD HH:MM:SS]
- echo - echo [args]
- sleep - sleep seconds [nanoseconds]
- id - show uid, gid, euid, and egid
- tty - show ttyname
- whoami - show current user
- logoff - logoff from the system
- setenv - setenv [var] [string]
- getenv - getenv [var]
- unsetenv - unsetenv [var]
- umask - umask [new_umask]
- rtc - real time clock read and set
-
-**CONFIGURATION:**
-
-This command has no configuration.
-
-alias - add alias for an existing command
------------------------------------------
-.. index:: alias
-
-**SYNOPSYS:**
-
-.. code:: c
-
- alias oldCommand newCommand
-
-**DESCRIPTION:**
-
-This command adds an alternate name for an existing command to the command set.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``alias``:
-.. code:: c
-
- SHLL \[/] $ me
- shell:me command not found
- SHLL \[/] $ alias whoami me
- SHLL \[/] $ me
- rtems
- SHLL \[/] $ whoami
- rtems
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_ALIAS
-.. index:: CONFIGURE_SHELL_COMMAND_ALIAS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ALIAS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_ALIAS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_alias
-
-The ``alias`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_alias(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``alias`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_ALIAS_Command;
-
-cmdls - List commands
----------------------
-.. index:: cmdls
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cmdls COMMAND...
-
-**DESCRIPTION:**
-
-This command lists the visible commands of the command set.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The current user must have read permission to list a command.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cmdls``:
-.. code:: c
-
- SHLL \[/] # cmdls help shutdown
- r-xr-xr-x 0 0 help
- r-x------ 0 0 shutdown
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CMDLS
-.. index:: CONFIGURE_SHELL_COMMAND_CMDLS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CMDLS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CMDLS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-The configuration structure for the ``cmdls`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CMDLS_Command;
-
-cmdchown - Change user or owner of commands
--------------------------------------------
-.. index:: cmdchown
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cmdchown \[OWNER][:\[GROUP]] COMMAND...
-
-**DESCRIPTION:**
-
-This command changes the user or owner of a command.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The current user must have an UID of zero or be the command owner to change the
-owner or group.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cmdchown``:
-.. code:: c
-
- [/] # cmdls help
- r-xr-xr-x 0 0 help
- \[/] # cmdchown 1:1 help
- \[/] # cmdls help
- r--r--r-- 1 1 help
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN
-.. index:: CONFIGURE_SHELL_COMMAND_CMDCHOWN
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CMDCHOWN`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-The configuration structure for the ``cmdchown`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command;
-
-cmdchmod - Change mode of commands
-----------------------------------
-.. index:: cmdchmod
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cmdchmod OCTAL-MODE COMMAND...
-
-**DESCRIPTION:**
-
-This command changes the mode of a command.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The current user must have an UID of zero or be the command owner to change the
-mode.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cmdchmod``:
-.. code:: c
-
- [/] # cmdls help
- r-xr-xr-x 0 0 help
- \[/] # cmdchmod 544 help
- \[/] # cmdls help
- r-xr--r-- 0 0 help
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD
-.. index:: CONFIGURE_SHELL_COMMAND_CMDCHMOD
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CMDCHMOD`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-The configuration structure for the ``cmdchmod`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command;
-
-date - print or set current date and time
------------------------------------------
-.. index:: date
-
-**SYNOPSYS:**
-
-.. code:: c
-
- date
- date DATE TIME
-
-**DESCRIPTION:**
-
-This command operates one of two modes. When invoked with no
-arguments, it prints the current date and time. When invoked
-with both ``date`` and ``time`` arguments, it sets the
-current time.
-
-The ``date`` is specified in ``YYYY-MM-DD`` format.
-The ``time`` is specified in ``HH:MM:SS`` format.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-This comm
-
-**EXAMPLES:**
-
-The following is an example of how to use ``date``:
-.. code:: c
-
- SHLL \[/] $ date
- Fri Jan 1 00:00:09 1988
- SHLL \[/] $ date 2008-02-29 06:45:32
- SHLL \[/] $ date
- Fri Feb 29 06:45:35 2008
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DATE
-.. index:: CONFIGURE_SHELL_COMMAND_DATE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DATE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_DATE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_date
-
-The ``date`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_date(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``date`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DATE_Command;
-
-echo - produce message in a shell script
-----------------------------------------
-.. index:: echo
-
-**SYNOPSYS:**
-
-.. code:: c
-
- echo \[-n | -e] args ...
-
-**DESCRIPTION:**
-
-echo prints its arguments on the standard output, separated by spaces.
-Unless the *-n* option is present, a newline is output following the
-arguments. The *-e* option causes echo to treat the escape sequences
-specially, as described in the following paragraph. The *-e* option is the
-default, and is provided solely for compatibility with other systems.
-Only one of the options *-n* and *-e* may be given.
-
-If any of the following sequences of characters is encountered during
-output, the sequence is not output. Instead, the specified action is
-performed:
-
-*\\b*
- A backspace character is output.
-
-*\\c*
- Subsequent output is suppressed. This is normally used at the
- end of the last argument to suppress the trailing newline that
- echo would otherwise output.
-
-*\\f*
- Output a form feed.
-
-*\\n*
- Output a newline character.
-
-*\\r*
- Output a carriage return.
-
-*\\t*
- Output a (horizontal) tab character.
-
-*\\v*
- Output a vertical tab.
-
-*\\0digits*
- Output the character whose value is given by zero to three digits.
- If there are zero digits, a nul character is output.
-
-*\\\\*
- Output a backslash.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The octal character escape mechanism (\\0digits) differs from the C lan-
-guage mechanism.
-
-There is no way to force ``echo`` to treat its arguments literally, rather
-than interpreting them as options and escape sequences.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``echo``:
-.. code:: c
-
- SHLL \[/] $ echo a b c
- a b c
- SHLL \[/] $ echo
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_ECHO
-.. index:: CONFIGURE_SHELL_COMMAND_ECHO
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ECHO`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_ECHO`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_echo
-
-The ``echo`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_echo(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``echo`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_ECHO_Command;
-
-**ORIGIN:**
-
-The implementation and portions of the documentation for this
-command are from NetBSD 4.0.
-
-sleep - delay for a specified amount of time
---------------------------------------------
-.. index:: sleep
-
-**SYNOPSYS:**
-
-.. code:: c
-
- sleep seconds
- sleep seconds nanoseconds
-
-**DESCRIPTION:**
-
-This command causes the task executing the shell to block
-for the specified number of ``seconds`` and ``nanoseconds``.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-This command is implemented using the ``nanosleep()`` method.
-
-The command line interface is similar to the ``sleep`` command
-found on POSIX systems but the addition of the ``nanoseconds``
-parameter allows fine grained delays in shell scripts without
-adding another command such as ``usleep``.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``sleep``:
-.. code:: c
-
- SHLL \[/] $ sleep 10
- SHLL \[/] $ sleep 0 5000000
-
-It is not clear from the above but there is a ten second
-pause after executing the first command before the prompt
-is printed. The second command completes very quickly
-from a human perspective and there is no noticeable
-delay in the prompt being printed.
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_SLEEP
-.. index:: CONFIGURE_SHELL_COMMAND_SLEEP
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SLEEP`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_SLEEP`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_sleep
-
-The ``sleep`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_sleep(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``sleep`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_SLEEP_Command;
-
-id - show uid gid euid and egid
--------------------------------
-.. index:: id
-
-**SYNOPSYS:**
-
-.. code:: c
-
- id
-
-**DESCRIPTION:**
-
-This command prints the user identity. This includes the user id
-(uid), group id (gid), effective user id (euid), and effective
-group id (egid).
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-Remember there is only one POSIX process in a single processor RTEMS
-application. Each thread may have its own user identity and that
-identity is used by the filesystem to enforce permissions.
-
-**EXAMPLES:**
-
-The first example of the ``id`` command is from a session logged
-in as the normal user ``rtems``:
-.. code:: c
-
- SHLL \[/] # id
- uid=1(rtems),gid=1(rtems),euid=1(rtems),egid=1(rtems)
-
-The second example of the ``id`` command is from a session logged
-in as the ``root`` user:
-.. code:: c
-
- SHLL \[/] # id
- uid=0(root),gid=0(root),euid=0(root),egid=0(root)
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_ID
-.. index:: CONFIGURE_SHELL_COMMAND_ID
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ID`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_ID`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_id
-
-The ``id`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_id(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``id`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_ID_Command;
-
-tty - show ttyname
-------------------
-.. index:: tty
-
-**SYNOPSYS:**
-
-.. code:: c
-
- tty
-
-**DESCRIPTION:**
-
-This command prints the file name of the device connected
-to standard input.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``tty``:
-.. code:: c
-
- SHLL \[/] $ tty
- /dev/console
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_TTY
-.. index:: CONFIGURE_SHELL_COMMAND_TTY
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_TTY`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_TTY`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_tty
-
-The ``tty`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_tty(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``tty`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_TTY_Command;
-
-whoami - print effective user id
---------------------------------
-.. index:: whoami
-
-**SYNOPSYS:**
-
-.. code:: c
-
- whoami
-
-**DESCRIPTION:**
-
-This command displays the user name associated with the current
-effective user id.
-
-**EXIT STATUS:**
-
-This command always succeeds.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``whoami``:
-.. code:: c
-
- SHLL \[/] $ whoami
- rtems
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_WHOAMI
-.. index:: CONFIGURE_SHELL_COMMAND_WHOAMI
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WHOAMI`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_WHOAMI`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_whoami
-
-The ``whoami`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_whoami(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``whoami`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command;
-
-getenv - print environment variable
------------------------------------
-.. index:: getenv
-
-**SYNOPSYS:**
-
-.. code:: c
-
- getenv variable
-
-**DESCRIPTION:**
-
-This command is used to display the value of a ``variable`` in the set
-of environment variables.
-
-**EXIT STATUS:**
-
-This command will return 1 and print a diagnostic message if
-a failure occurs.
-
-**NOTES:**
-
-The entire RTEMS application shares a single set of environment variables.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``getenv``:
-.. code:: c
-
- SHLL \[/] $ getenv BASEPATH
- /mnt/hda1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_GETENV
-.. index:: CONFIGURE_SHELL_COMMAND_GETENV
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_GETENV`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_GETENV`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_getenv
-
-The ``getenv`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_getenv(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``getenv`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_GETENV_Command;
-
-setenv - set environment variable
----------------------------------
-.. index:: setenv
-
-**SYNOPSYS:**
-
-.. code:: c
-
- setenv variable \[value]
-
-**DESCRIPTION:**
-
-This command is used to add a new ``variable`` to the set of environment
-variables or to modify the variable of an already existing ``variable``.
-If the ``value`` is not provided, the ``variable`` will be set to the
-empty string.
-
-**EXIT STATUS:**
-
-This command will return 1 and print a diagnostic message if
-a failure occurs.
-
-**NOTES:**
-
-The entire RTEMS application shares a single set of environment variables.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``setenv``:
-.. code:: c
-
- SHLL \[/] $ setenv BASEPATH /mnt/hda1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_SETENV
-.. index:: CONFIGURE_SHELL_COMMAND_SETENV
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SETENV`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_SETENV`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_setenv
-
-The ``setenv`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_setenv(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``setenv`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_SETENV_Command;
-
-unsetenv - unset environment variable
--------------------------------------
-.. index:: unsetenv
-
-**SYNOPSYS:**
-
-.. code:: c
-
- unsetenv variable
-
-**DESCRIPTION:**
-
-This command is remove to a ``variable`` from the set of environment
-variables.
-
-**EXIT STATUS:**
-
-This command will return 1 and print a diagnostic message if
-a failure occurs.
-
-**NOTES:**
-
-The entire RTEMS application shares a single set of environment variables.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``unsetenv``:
-.. code:: c
-
- SHLL \[/] $ unsetenv BASEPATH
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_UNSETENV
-.. index:: CONFIGURE_SHELL_COMMAND_UNSETENV
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_UNSETENV`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_UNSETENV`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_unsetenv
-
-The ``unsetenv`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_unsetenv(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``unsetenv`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command;
-
-time - time command execution
------------------------------
-.. index:: time
-
-**SYNOPSYS:**
-
-.. code:: c
-
- time command \[argument ...]
-
-**DESCRIPTION:**
-
-The time command executes and times a command. After the command
-finishes, time writes the total time elapsed. Times are reported in
-seconds.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-None.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``time``:
-.. code:: c
-
- SHLL \[/] $ time cp -r /nfs/directory /c
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_TIME
-.. index:: CONFIGURE_SHELL_COMMAND_TIME
-
-This command is included in the default shell command set. When
-building a custom command set, define``CONFIGURE_SHELL_COMMAND_TIME`` to have this command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_TIME`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_time
-
-The ``time`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_time(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``time`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_TIME_Command;
-
-logoff - logoff from the system
--------------------------------
-.. index:: logoff
-
-**SYNOPSYS:**
-
-.. code:: c
-
- logoff
-
-**DESCRIPTION:**
-
-This command logs the user out of the shell.
-
-**EXIT STATUS:**
-
-This command does not return.
-
-**NOTES:**
-
-The system behavior when the shell is exited depends upon how the
-shell was initiated. The typical behavior is that a login prompt
-will be displayed for the next login attempt or that the connection
-will be dropped by the RTEMS system.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``logoff``:
-.. code:: c
-
- SHLL \[/] $ logoff
- logoff from the system...
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_LOGOFF
-.. index:: CONFIGURE_SHELL_COMMAND_LOGOFF
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LOGOFF`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_LOGOFF`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_logoff
-
-The ``logoff`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_logoff(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``logoff`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command;
-
-rtc - RTC driver configuration
-------------------------------
-.. index:: rtc
-
-**SYNOPSYS:**
-
-.. code:: c
-
- rtc
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_RTC
-.. index:: CONFIGURE_SHELL_COMMAND_RTC
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_RTC`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all
-shell commands have been configured.
-
-exit - exit the shell
----------------------
-.. index:: exit
-
-**SYNOPSYS:**
-
-.. code:: c
-
- exit
-
-**DESCRIPTION:**
-
-This command causes the shell interpreter to ``exit``.
-
-**EXIT STATUS:**
-
-This command does not return.
-
-**NOTES:**
-
-In contrast to `logoff - logoff from the system`_,
-this command is built into the shell interpreter loop.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``exit``:
-.. code:: c
-
- SHLL \[/] $ exit
- Shell exiting
-
-**CONFIGURATION:**
-
-This command is always present and cannot be disabled.
-
-**PROGRAMMING INFORMATION:**
-
-The ``exit`` is implemented directly in the shell interpreter.
-There is no C routine associated with it.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-File and Directory Commands
-###########################
-
-Introduction
-============
-
-The RTEMS shell has the following file and directory commands:
-
-- ``blksync`` - sync the block driver
-
-- ``cat`` - display file contents
-
-- ``cd`` - alias for chdir
-
-- ``chdir`` - change the current directory
-
-- ``chmod`` - change permissions of a file
-
-- ``chroot`` - change the root directory
-
-- ``cp`` - copy files
-
-- ``dd`` - format disks
-
-- ``debugrfs`` - debug RFS file system
-
-- ``df`` - display file system disk space usage
-
-- ``dir`` - alias for ls
-
-- ``fdisk`` - format disks
-
-- ``hexdump`` - format disks
-
-- ``ln`` - make links
-
-- ``ls`` - list files in the directory
-
-- ``md5`` - display file system disk space usage
-
-- ``mkdir`` - create a directory
-
-- ``mkdos`` - DOSFS disk format
-
-- ``mknod`` - make device special file
-
-- ``mkrfs`` - format RFS file system
-
-- ``mount`` - mount disk
-
-- ``mv`` - move files
-
-- ``pwd`` - print work directory
-
-- ``rmdir`` - remove empty directories
-
-- ``rm`` - remove files
-
-- ``umask`` - Set file mode creation mask
-
-- ``unmount`` - unmount disk
-
-Commands
-========
-
-This section details the File and Directory Commands available. A
-subsection is dedicated to each of the commands and
-describes the behavior and configuration of that
-command as well as providing an example usage.
-
-blksync - sync the block driver
--------------------------------
-.. index:: blksync
-
-**SYNOPSYS:**
-
-.. code:: c
-
- blksync driver
-
-**DESCRIPTION:**
-
-This command XXX
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``blksync``:
-.. code:: c
-
- EXAMPLE_TBD
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_BLKSYNC
-.. index:: CONFIGURE_SHELL_COMMAND_BLKSYNC
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_BLKSYNC`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_BLKSYNC`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_blksync
-
-The ``blksync`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_blksync(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``blksync`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command;
-
-cat - display file contents
----------------------------
-.. index:: cat
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cat file1 \[file2 .. fileN]
-
-**DESCRIPTION:**
-
-This command displays the contents of the specified files.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-It is possible to read the input from a device file using ``cat``.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cat``:
-.. code:: c
-
- SHLL \[/] # cat /etc/passwd
- root:\*:0:0:root::/:/bin/sh
- rtems:\*:1:1:RTEMS Application::/:/bin/sh
- tty:!:2:2:tty owner::/:/bin/false
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CAT
-.. index:: CONFIGURE_SHELL_COMMAND_CAT
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CAT`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CAT`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_cat
-
-The ``cat`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_cat(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``cat`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CAT_Command;
-
-cd - alias for chdir
---------------------
-.. index:: cd
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cd directory
-
-**DESCRIPTION:**
-
-This command is an alias or alternate name for the ``chdir``.
-See `ls - list files in the directory`_ for more information.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cd``:
-.. code:: c
-
- SHLL \[/] $ cd etc
- SHLL \[/etc] $ cd /
- SHLL \[/] $ cd /etc
- SHLL \[/etc] $ pwd
- /etc
- SHLL \[/etc] $ cd /
- SHLL \[/] $ pwd
- /
- SHLL \[/] $ cd etc
- SHLL \[/etc] $ cd ..
- SHLL \[/] $ pwd
- /
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CD
-.. index:: CONFIGURE_SHELL_COMMAND_CD
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CD`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CD`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_cd
-
-The ``cd`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_cd(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``cd`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CD_Command;
-
-
-chdir - change the current directory
-------------------------------------
-.. index:: chdir
-
-**SYNOPSYS:**
-
-.. code:: c
-
- chdir \[dir]
-
-**DESCRIPTION:**
-
-This command is used to change the current working directory to
-the specified directory. If no arguments are given, the current
-working directory will be changed to ``/``.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``chdir``:
-.. code:: c
-
- SHLL \[/] $ pwd
- /
- SHLL \[/] $ chdir etc
- SHLL \[/etc] $ pwd
- /etc
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CHDIR
-.. index:: CONFIGURE_SHELL_COMMAND_CHDIR
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CHDIR`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CHDIR`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_chdir
-
-The ``chdir`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_chdir(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``chdir`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CHDIR_Command;
-
-chmod - change permissions of a file
-------------------------------------
-.. index:: chmod
-
-**SYNOPSYS:**
-
-.. code:: c
-
- chmod permissions file1 \[file2...]
-
-**DESCRIPTION:**
-
-This command changes the permissions on the files specified to the
-indicated ``permissions``. The permission values are POSIX based
-with owner, group, and world having individual read, write, and
-executive permission bits.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The ``chmod`` command only takes numeric representations of
-the permissions.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``chmod``:
-.. code:: c
-
- SHLL \[/] # cd etc
- SHLL \[/etc] # ls
- -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd
- -rw-r--r-- 1 root root 42 Jan 01 00:00 group
- -rw-r--r-- 1 root root 30 Jan 01 00:00 issue
- -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net
- 4 files 202 bytes occupied
- SHLL \[/etc] # chmod 0777 passwd
- SHLL \[/etc] # ls
- -rwxrwxrwx 1 root root 102 Jan 01 00:00 passwd
- -rw-r--r-- 1 root root 42 Jan 01 00:00 group
- -rw-r--r-- 1 root root 30 Jan 01 00:00 issue
- -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net
- 4 files 202 bytes occupied
- SHLL \[/etc] # chmod 0322 passwd
- SHLL \[/etc] # ls
- --wx-w--w- 1 nouser root 102 Jan 01 00:00 passwd
- -rw-r--r-- 1 nouser root 42 Jan 01 00:00 group
- -rw-r--r-- 1 nouser root 30 Jan 01 00:00 issue
- -rw-r--r-- 1 nouser root 28 Jan 01 00:00 issue.net
- 4 files 202 bytes occupied
- SHLL \[/etc] # chmod 0644 passwd
- SHLL \[/etc] # ls
- -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd
- -rw-r--r-- 1 root root 42 Jan 01 00:00 group
- -rw-r--r-- 1 root root 30 Jan 01 00:00 issue
- -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net
- 4 files 202 bytes occupied
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CHMOD
-.. index:: CONFIGURE_SHELL_COMMAND_CHMOD
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CHMOD`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CHMOD`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_chmod
-
-The ``chmod`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_chmod(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``chmod`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CHMOD_Command;
-
-chroot - change the root directory
-----------------------------------
-.. index:: chroot
-
-**SYNOPSYS:**
-
-.. code:: c
-
- chroot \[dir]
-
-**DESCRIPTION:**
-
-This command changes the root directory to ``dir`` for subsequent
-commands.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-The destination directory ``dir`` must exist.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``chroot``
-and the impact it has on the environment for subsequent
-command invocations:
-.. code:: c
-
- SHLL \[/] $ cat passwd
- cat: passwd: No such file or directory
- SHLL \[/] $ chroot etc
- SHLL \[/] $ cat passwd
- root:\*:0:0:root::/:/bin/sh
- rtems:\*:1:1:RTEMS Application::/:/bin/sh
- tty:!:2:2:tty owner::/:/bin/false
- SHLL \[/] $ cat /etc/passwd
- cat: /etc/passwd: No such file or directory
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CHROOT
-.. index:: CONFIGURE_SHELL_COMMAND_CHROOT
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CHROOT`` to have this
-command included. Additional to that you have to add one
-POSIX key value pair for each thread where you want to use
-the command.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CHROOT`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_chroot
-
-The ``chroot`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_chroot(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``chroot`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CHROOT_Command;
-
-cp - copy files
----------------
-.. index:: cp
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cp \[-R \[-H | -L | -P]] \[-f | -i] \[-pv] src target
- cp \[-R \[-H | -L] ] \[-f | -i] \[-NpPv] source_file ... target_directory
-
-**DESCRIPTION:**
-
-In the first synopsis form, the cp utility copies the contents of the
-source_file to the target_file. In the second synopsis form, the contents of
-each named source_file is copied to the destination target_directory. The names
-of the files themselves are not changed. If cp detects an attempt to copy a
-file to itself, the copy will fail.
-
-The following options are available:
-
-*-f*
- For each existing destination pathname, attempt to overwrite it. If permissions
- do not allow copy to succeed, remove it and create a new file, without
- prompting for confirmation. (The -i option is ignored if the -f option is
- specified.)
-
-*-H*
- If the -R option is specified, symbolic links on the command line are followed.
- (Symbolic links encountered in the tree traversal are not followed.)
-
-*-i*
- Causes cp to write a prompt to the standard error output before copying a file
- that would overwrite an existing file. If the response from the standard input
- begins with the character ’y’, the file copy is attempted.
-
-*-L*
- If the -R option is specified, all symbolic links are followed.
-
-*-N*
- When used with -p, do not copy file flags.
-
-*-P*
- No symbolic links are followed.
-
-*-p*
- Causes cp to preserve in the copy as many of the modification time, access
- time, file flags, file mode, user ID, and group ID as allowed by permissions.
- If the user ID and group ID cannot be preserved, no error message is displayed
- and the exit value is not altered.
- If the source file has its set user ID bit on and the user ID cannot be
- preserved, the set user ID bit is not preserved in the copy’s permissions. If
- the source file has its set group ID bit on and the group ID cannot be
- preserved, the set group ID bit is not preserved in the copy’s permissions. If
- the source file has both its set user ID and set group ID bits on, and either
- the user ID or group ID cannot be preserved, neither the set user ID or set
- group ID bits are preserved in the copy’s permissions.
-
-*-R*
- If source_file designates a directory, cp copies the directory and the entire
- subtree connected at that point. This option also causes symbolic links to be
- copied, rather than indirected through, and for cp to create special files
- rather than copying them as normal files. Created directories have the same
- mode as the corresponding source directory, unmodified by the process’s umask.
-
-*-v*
- Cause cp to be verbose, showing files as they are copied.
-
-For each destination file that already exists, its contents are overwritten if
-permissions allow, but its mode, user ID, and group ID are unchanged.
-
-In the second synopsis form, target_directory must exist unless there is only
-one named source_file which is a directory and the -R flag is specified.
-
-If the destination file does not exist, the mode of the source file is used as
-modified by the file mode creation mask (umask, see csh(1)). If the source file
-has its set user ID bit on, that bit is removed unless both the source file and
-the destination file are owned by the same user. If the source file has its set
-group ID bit on, that bit is removed unless both the source file and the
-destination file are in the same group and the user is a member of that group.
-If both the set user ID and set group ID bits are set, all of the above
-conditions must be fulfilled or both bits are removed.
-
-Appropriate permissions are required for file creation or overwriting.
-
-Symbolic links are always followed unless the -R flag is set, in which case
-symbolic links are not followed, by default. The -H or -L flags (in conjunction
-with the -R flag), as well as the -P flag cause symbolic links to be followed
-as described above. The -H and -L options are ignored unless the -R option is
-specified. In addition, these options override eachsubhedading other and the
-command’s actions are determined by the last one specified.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cp`` to
-copy a file to a new name in the current directory:
-.. code:: c
-
- SHLL \[/] # cat joel
- cat: joel: No such file or directory
- SHLL \[/] # cp etc/passwd joel
- SHLL \[/] # cat joel
- root:\*:0:0:root::/:/bin/sh
- rtems:\*:1:1:RTEMS Application::/:/bin/sh
- tty:!:2:2:tty owner::/:/bin/false
- SHLL \[/] # ls
- drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/
- drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/
- -rw-r--r-- 1 root root 102 Jan 01 00:00 joel
- 3 files 1710 bytes occupied
-
-The following is an example of how to use ``cp`` to
-copy one or more files to a destination directory and
-use the same ``basename`` in the destination directory:
-.. code:: c
-
- SHLL \[/] # mkdir tmp
- SHLL \[/] # ls tmp
- 0 files 0 bytes occupied
- SHLL \[/] # cp /etc/passwd tmp
- SHLL \[/] # ls /tmp
- -rw-r--r-- 1 root root 102 Jan 01 00:01 passwd
- 1 files 102 bytes occupied
- SHLL \[/] # cp /etc/passwd /etc/group /tmp
- SHLL \[/] # ls /tmp
- -rw-r--r-- 1 root root 102 Jan 01 00:01 passwd
- -rw-r--r-- 1 root root 42 Jan 01 00:01 group
- 2 files 144 bytes occupied
- SHLL \[/] #
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CP
-.. index:: CONFIGURE_SHELL_COMMAND_CP
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CP`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CP`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_main_cp
-
-The ``cp`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_main_cp(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``cp`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CP_Command;
-
-**ORIGIN:**
-
-The implementation and portions of the documentation for this
-command are from NetBSD 4.0.
-
-dd - convert and copy a file
-----------------------------
-.. index:: dd
-
-**SYNOPSYS:**
-
-.. code:: c
-
- dd \[operands ...]
-
-**DESCRIPTION:**
-
-The dd utility copies the standard input to the standard output.
-Input data is read and written in 512-byte blocks. If input reads are
-short, input from multiple reads are aggregated to form the output
-block. When finished, dd displays the number of complete and partial
-input and output blocks and truncated input records to the standard
-error output.
-
-The following operands are available:
-
-*bs=n*
- Set both input and output block size, superseding the ibs and obs
- operands. If no conversion values other than noerror, notrunc or sync
- are specified, then each input block is copied to the output as a
- single block without any aggregation of short blocks.
-
-*cbs=n*
- Set the conversion record size to n bytes. The conversion record size
- is required by the record oriented conversion values.
-
-*count=n*
- Copy only n input blocks.
-
-*files=n*
- Copy n input files before terminating. This operand is only
- applicable when the input device is a tape.
-
-*ibs=n*
- Set the input block size to n bytes instead of the default 512.
-
-*if=file*
- Read input from file instead of the standard input.
-
-*obs=n*
- Set the output block size to n bytes instead of the default 512.
-
-*of=file*
- Write output to file instead of the standard output. Any regular
- output file is truncated unless the notrunc conversion value is
- specified. If an initial portion of the output file is skipped (see
- the seek operand) the output file is truncated at that point.
-
-*seek=n*
- Seek n blocks from the beginning of the output before copying. On
- non-tape devices, a *lseek* operation is used. Otherwise, existing
- blocks are read and the data discarded. If the seek operation is past
- the end of file, space from the current end of file to the specified
- offset is filled with blocks of NUL bytes.
-
-*skip=n*
- Skip n blocks from the beginning of the input before copying. On
- input which supports seeks, a *lseek* operation is used. Otherwise,
- input data is read and discarded. For pipes, the correct number of
- bytes is read. For all other devices, the correct number of blocks is
- read without distinguishing between a partial or complete block being
- read.
-
-*progress=n*
- Switch on display of progress if n is set to any non-zero value. This
- will cause a “.” to be printed (to the standard error output) for
- every n full or partial blocks written to the output file.
-
-*conv=value[,value...]*
- Where value is one of the symbols from the following list.
-
- *ascii, oldascii*
-
- The same as the unblock value except that characters are translated
- from EBCDIC to ASCII before the records are converted. (These values
- imply unblock if the operand cbs is also specified.) There are two
- conversion maps for ASCII. The value ascii specifies the recom-
- mended one which is compatible with AT&T System V UNIX. The value
- oldascii specifies the one used in historic AT&T and pre 4.3BSD-Reno
- systems.
-
- *block*
-
- Treats the input as a sequence of newline or end-of-file terminated
- variable length records independent of input and output block
- boundaries. Any trailing newline character is discarded. Each
- input record is converted to a fixed length output record where the
- length is specified by the cbs operand. Input records shorter than
- the conversion record size are padded with spaces. Input records
- longer than the conversion record size are truncated. The number of
- truncated input records, if any, are reported to the standard error
- output at the completion of the copy.
-
- *ebcdic, ibm, oldebcdic, oldibm*
-
- The same as the block value except that characters are translated from
- ASCII to EBCDIC after the records are converted. (These values imply
- block if the operand cbs is also specified.) There are four
- conversion maps for EBCDIC. The value ebcdic specifies the
- recommended one which is compatible with AT&T System V UNIX. The
- value ibm is a slightly different mapping, which is compatible with
- the AT&T System V UNIX ibm value. The values oldebcdic and oldibm are
- maps used in historic AT&T and pre 4.3BSD-Reno systems.
-
- *lcase*
-
- Transform uppercase characters into lowercase characters.
-
- *noerror*
-
- Do not stop processing on an input error. When an input error occurs,
- a diagnostic message followed by the current input and output block
- counts will be written to the standard error output in the same format
- as the standard completion message. If the sync conversion is also
- specified, any missing input data will be replaced with NUL bytes (or
- with spaces if a block oriented conversion value was specified) and
- processed as a normal input buffer. If the sync conversion is not
- specified, the input block is omitted from the output. On input files
- which are not tapes or pipes, the file offset will be positioned past
- the block in which the error occurred using lseek(2).
-
- *notrunc*
-
- Do not truncate the output file. This will preserve any blocks in the
- output file not explicitly written by dd. The notrunc value is not
- supported for tapes.
-
- *osync*
-
- Pad the final output block to the full output block size. If the
- input file is not a multiple of the output block size after
- conversion, this conversion forces the final output block to be the
- same size as preceding blocks for use on devices that require
- regularly sized blocks to be written. This option is incompatible
- with use of the bs=n block size specification.
-
- *sparse*
-
- If one or more non-final output blocks would consist solely of NUL
- bytes, try to seek the output file by the required space instead of
- filling them with NULs. This results in a sparse file on some file
- systems.
-
- *swab*
-
- Swap every pair of input bytes. If an input buffer has an odd number
- of bytes, the last byte will be ignored during swapping.
-
- *sync*
-
- Pad every input block to the input buffer size. Spaces are used for
- pad bytes if a block oriented conversion value is specified, otherwise
- NUL bytes are used.
-
- *ucase*
-
- Transform lowercase characters into uppercase characters.
-
- *unblock*
-
- Treats the input as a sequence of fixed length records independent of
- input and output block boundaries. The length of the input records is
- specified by the cbs operand. Any trailing space characters are
- discarded and a newline character is appended.
-
-Where sizes are specified, a decimal number of bytes is expected. Two
-or more numbers may be separated by an “x” to indicate a product.
-Each number may have one of the following optional suffixes:
-
-*b*
- Block; multiply by 512
-
-*k*
- Kibi; multiply by 1024 (1 KiB)
-
-*m*
- Mebi; multiply by 1048576 (1 MiB)
-
-*g*
- Gibi; multiply by 1073741824 (1 GiB)
-
-*t*
- Tebi; multiply by 1099511627776 (1 TiB)
-
-*w*
- Word; multiply by the number of bytes in an integer
-
-When finished, dd displays the number of complete and partial input
-and output blocks, truncated input records and odd-length
-byte-swapping ritten. Partial output blocks to tape devices are
-considered fatal errors. Otherwise, the rest of the block will be
-written. Partial output blocks to character devices will produce a
-warning message. A truncated input block is one where a variable
-length record oriented conversion value was specified and the input
-line was too long to fit in the conversion record or was not newline
-terminated.
-
-Normally, data resulting from input or conversion or both are
-aggregated into output blocks of the specified size. After the end of
-input is reached, any remaining output is written as a block. This
-means that the final output block may be shorter than the output block
-size.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``dd``:
-.. code:: c
-
- SHLL \[/] $ dd if=/nfs/boot-image of=/dev/hda1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DD
-.. index:: CONFIGURE_SHELL_COMMAND_DD
-
-This command is included in the default shell command set. When
-building a custom command set, define``CONFIGURE_SHELL_COMMAND_DD`` to have this command included.
-
-This command can be excluded from the shell command set by defining``CONFIGURE_SHELL_NO_COMMAND_DD`` when all shell commands have been
-configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_dd
-
-The ``dd`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_dd(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``dd`` has the following
-prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DD_Command;
-
-debugrfs - debug RFS file system
---------------------------------
-.. index:: debugrfs
-
-**SYNOPSYS:**
-
-.. code:: c
-
- debugrfs \[-hl] path command \[options]
-
-**DESCRIPTION:**
-
-The command provides debugging information for the RFS file system.
-
-The options are:
-
-*-h*
- Print a help message.
-
-*-l*
- List the commands.
-
-*path*
- Path to the mounted RFS file system. The file system has to be mounted
- to view to use this command.
-
-The commands are:
-
-*block start \[end]*
- Display the contents of the blocks from start to end.
-
-*data*
- Display the file system data and configuration.
-
-*dir bno*
- Process the block as a directory displaying the entries.
-
-*group start \[end]*
- Display the group data from the start group to the end group.
-
-*inode \[-aef] \[start] \[end]*
-
- Display the inodes between start and end. If no start and end is
- provides all inodes are displayed.
-
- *-a*
-
- Display all inodes. That is allocated and unallocated inodes.
-
- *-e*
-
- Search and display on inodes that have an error.
-
- *-f*
-
- Force display of inodes, even when in error.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``debugrfs``:
-.. code:: c
-
- SHLL \[/] $ debugrfs /c data
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS
-.. index:: CONFIGURE_SHELL_COMMAND_DEBUGRFS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DEBUGRFS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_debugrfs
-
-The ``debugrfs`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_debugrfs(
- int argc,
- char \**argv
- );
-
-The configuration structure for ``debugrfs`` has the following
-prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command;
-
-df - display file system disk space usage
------------------------------------------
-.. index:: df
-
-**SYNOPSYS:**
-
-.. code:: c
-
- df \[-h] \[-B block_size]
-
-**DESCRIPTION:**
-
-This command print disk space usage for mounted file systems.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``df``:
-.. code:: c
-
- SHLL \[/] $ df -B 4K
- Filesystem 4K-blocks Used Available Use% Mounted on
- /dev/rda 124 1 124 0% /mnt/ramdisk
- SHLL \[/] $ df
- Filesystem 1K-blocks Used Available Use% Mounted on
- /dev/rda 495 1 494 0% /mnt/ramdisk
- SHLL \[/] $ df -h
- Filesystem Size Used Available Use% Mounted on
- /dev/rda 495K 1K 494K 0% /mnt/ramdisk
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DF
-.. index:: CONFIGURE_SHELL_COMMAND_DF
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DF`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_DF`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_df
-
-The ``df`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_main_df(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``df`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DF_Command;
-
-dir - alias for ls
-------------------
-.. index:: dir
-
-**SYNOPSYS:**
-
-.. code:: c
-
- dir \[dir]
-
-**DESCRIPTION:**
-
-This command is an alias or alternate name for the ``ls``.
-See `ls - list files in the directory`_
-for more information.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``dir``:
-.. code:: c
-
- SHLL \[/] $ dir
- drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/
- drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/
- 2 files 1608 bytes occupied
- SHLL \[/] $ dir etc
- -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd
- -rw-r--r-- 1 root root 42 Jan 01 00:00 group
- -rw-r--r-- 1 root root 30 Jan 01 00:00 issue
- -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net
- 4 files 202 bytes occupied
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DIR
-.. index:: CONFIGURE_SHELL_COMMAND_DIR
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DIR`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_DIR`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_dir
-
-The ``dir`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_dir(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``dir`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DIR_Command;
-
-fdisk - format disk
--------------------
-.. index:: fdisk
-
-**SYNOPSYS:**
-
-.. code:: c
-
- fdisk
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_FDISK
-.. index:: CONFIGURE_SHELL_COMMAND_FDISK
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_FDISK`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all
-shell commands have been configured.
-
-hexdump - ascii/dec/hex/octal dump
-----------------------------------
-.. index:: hexdump
-
-**SYNOPSYS:**
-
-.. code:: c
-
- hexdump \[-bcCdovx] \[-e format_string] \[-f format_file] \[-n length]
- \[-s skip] file ...
-
-**DESCRIPTION:**
-
-The hexdump utility is a filter which displays the specified files, or
-the standard input, if no files are specified, in a user specified
-format.
-
-The options are as follows:
-
-*-b*
- One-byte octal display. Display the input offset in hexadecimal,
- followed by sixteen space-separated, three column, zero-filled, bytes
- of input data, in octal, per line.
-
-*-c*
- One-byte character display. Display the input offset in hexadecimal,
- followed by sixteen space-separated, three column, space-filled,
- characters of input data per line.
-
-*-C*
- Canonical hex+ASCII display. Display the input offset in hexadecimal,
- followed by sixteen space-separated, two column, hexadecimal bytes,
- followed by the same sixteen bytes in %_p format enclosed in “|”
- characters.
-
-*-d*
- Two-byte decimal display. Display the input offset in hexadecimal,
- followed by eight space-separated, five column, zero-filled, two-byte
- units of input data, in unsigned decimal, per line.
-
-*-e format_string*
- Specify a format string to be used for displaying data.
-
-*-f format_file*
- Specify a file that contains one or more newline separated format
- strings. Empty lines and lines whose first non-blank character is a
- hash mark (#) are ignored.
-
-*-n length*
- Interpret only length bytes of input.
-
-*-o*
- Two-byte octal display. Display the input offset in hexadecimal,
- followed by eight space-separated, six column, zerofilled, two byte
- quantities of input data, in octal, per line.
-
-*-s offset*
- Skip offset bytes from the beginning of the input. By default, offset
- is interpreted as a decimal number. With a leading 0x or 0X, offset
- is interpreted as a hexadecimal number, otherwise, with a leading 0,
- offset is interpreted as an octal number. Appending the character b,
- k, or m to offset causes it to be interpreted as a multiple of 512,
- 1024, or 1048576, respectively.
-
-*-v*
- The -v option causes hexdump to display all input data. Without the
- -v option, any number of groups of output lines, which would be
- identical to the immediately preceding group of output lines (except
- for the input offsets), are replaced with a line containing a single
- asterisk.
-
-*-x*
- Two-byte hexadecimal display. Display the input offset in
- hexadecimal, followed by eight, space separated, four column,
- zero-filled, two-byte quantities of input data, in hexadecimal, per
- line.
-
-For each input file, hexdump sequentially copies the input to standard
-output, transforming the data according to the format strings
-specified by the -e and -f options, in the order that they were
-specified.
-
-*Formats*
-
-A format string contains any number of format units, separated by
-whitespace. A format unit contains up to three items: an iteration
-count, a byte count, and a format.
-
-The iteration count is an optional positive integer, which defaults to
-one. Each format is applied iteration count times.
-
-The byte count is an optional positive integer. If specified it
-defines the number of bytes to be interpreted by each iteration of the
-format.
-
-If an iteration count and/or a byte count is specified, a single slash
-must be placed after the iteration count and/or before the byte count
-to disambiguate them. Any whitespace before or after the slash is
-ignored.
-
-The format is required and must be surrounded by double quote (“ “)
-marks. It is interpreted as a fprintf-style format string (see*fprintf*), with the following exceptions:
-
-- An asterisk (\*) may not be used as a field width or precision.
-
-- A byte count or field precision is required for each “s” con-
- version character (unlike the fprintf(3) default which prints the
- entire string if the precision is unspecified).
-
-- The conversion characters “h”, “l”, “n”, “p” and “q” are not
- supported.
-
-- The single character escape sequences described in the C standard
- are supported:
-
- NUL \\0
- <alert character> \\a
- <backspace> \\b
- <form-feed> \\f
- <newline> \\n
- <carriage return> \\r
- <tab> \\t
- <vertical tab> \\v
-
-Hexdump also supports the following additional conversion strings:
-
-*_a[dox]*
- Display the input offset, cumulative across input files, of the next
- byte to be displayed. The appended characters d, o, and x specify the
- display base as decimal, octal or hexadecimal respectively.
-
-*_A[dox]*
- Identical to the _a conversion string except that it is only performed
- once, when all of the input data has been processed.
-
-*_c*
- Output characters in the default character set. Nonprinting
- characters are displayed in three character, zero-padded octal, except
- for those representable by standard escape notation (see above), which
- are displayed as two character strings.
-
-*_p*
- Output characters in the default character set. Nonprinting
- characters are displayed as a single “.”.
-
-*_u*
- Output US ASCII characters, with the exception that control characters
- are displayed using the following, lower-case, names. Characters
- greater than 0xff, hexadecimal, are displayed as hexadecimal
- strings.
- 000 nul 001 soh 002 stx 003 etx 004 eot 005 enq
- 006 ack 007 bel 008 bs 009 ht 00A lf 00B vt
- 00C ff 00D cr 00E so 00F si 010 dle 011 dc1
- 012 dc2 013 dc3 014 dc4 015 nak 016 syn 017 etb
- 018 can 019 em 01A sub 01B esc 01C fs 01D gs
- 01E rs 01F us 07F del
-
-The default and supported byte counts for the conversion characters
-are as follows:
-
- %_c, %_p, %_u, %c One byte counts only.
- %d, %i, %o, %u, %X, %x Four byte default, one, two, four
- and eight byte counts supported.
- %E, %e, %f, %G, %g Eight byte default, four byte
- counts supported.
-
-The amount of data interpreted by each format string is the sum of the
-data required by each format unit, which is the iteration count times
-the byte count, or the iteration count times the number of bytes
-required by the format if the byte count is not specified.
-
-The input is manipulated in “blocks”, where a block is defined as
-the largest amount of data specified by any format string. Format
-strings interpreting less than an input block’s worth of data, whose
-last format unit both interprets some number of bytes and does not
-have a specified iteration count, have the iteration count incremented
-until the entire input block has been processed or there is not enough
-data remaining in the block to satisfy the format string.
-
-If, either as a result of user specification or hexdump modifying the
-iteration count as described above, an iteration count is greater than
-one, no trailing whitespace characters are output during the last
-iteration.
-
-It is an error to specify a byte count as well as multiple conversion
-characters or strings unless all but one of the conversion characters
-or strings is _a or _A.
-
-If, as a result of the specification of the -n option or end-of-file
-being reached, input data only partially satisfies a format string,
-the input block is zero-padded sufficiently to display all available
-data (i.e. any format units overlapping the end of data will display
-some num- ber of the zero bytes).
-
-Further output by such format strings is replaced by an equivalent
-number of spaces. An equivalent number of spaces is defined as the
-number of spaces output by an s conversion character with the same
-field width and precision as the original conversion character or
-conversion string but with any “+”, “ ”, “#” conversion flag
-characters removed, and ref- erencing a NULL string.
-
-If no format strings are specified, the default display is equivalent
-to specifying the -x option.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``hexdump``:
-.. code:: c
-
- SHLL \[/] $ hexdump -C -n 512 /dev/hda1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_HEXDUMP
-.. index:: CONFIGURE_SHELL_COMMAND_HEXDUMP
-
-This command is included in the default shell command set. When
-building a custom command set, define``CONFIGURE_SHELL_COMMAND_HEXDUMP`` to have this command included.
-
-This command can be excluded from the shell command set by defining``CONFIGURE_SHELL_NO_COMMAND_HEXDUMP`` when all shell commands have
-been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_hexdump
-
-The ``hexdump`` command is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_hexdump(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``hexdump`` has the following
-prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command;
-
-ln - make links
----------------
-.. index:: ln
-
-**SYNOPSYS:**
-
-.. code:: c
-
- ln \[-fhinsv] source_file \[target_file]
- ln \[-fhinsv] source_file ... target_dir
-
-**DESCRIPTION:**
-
-The ln utility creates a new directory entry (linked file) which has
-the same modes as the original file. It is useful for maintaining
-multiple copies of a file in many places at once without using up
-storage for the “copies”; instead, a link “points” to the original
-copy. There are two types of links; hard links and symbolic links.
-How a link “points” to a file is one of the differences between a
-hard or symbolic link.
-
-The options are as follows:
-
-*-f*
- Unlink any already existing file, permitting the link to occur.
-
-*-h*
- If the target_file or target_dir is a symbolic link, do not follow it.
- This is most useful with the -f option, to replace a symlink which may
- point to a directory.
-
-*-i*
- Cause ln to write a prompt to standard error if the target file
- exists. If the response from the standard input begins with the
- character ‘y’ or ‘Y’, then unlink the target file so that the link may
- occur. Otherwise, do not attempt the link. (The -i option overrides
- any previous -f options.)
-
-*-n*
- Same as -h, for compatibility with other ln implementations.
-
-*-s*
- Create a symbolic link.
-
-*-v*
- Cause ln to be verbose, showing files as they are processed.
-
-By default ln makes hard links. A hard link to a file is
-indistinguishable from the original directory entry; any changes to a
-file are effective independent of the name used to reference the file.
-Hard links may not normally refer to directories and may not span file
-systems.
-
-A symbolic link contains the name of the file to which it is linked.
-The referenced file is used when an *open* operation is performed on
-the link. A *stat* on a symbolic link will return the linked-to
-file; an *lstat* must be done to obtain information about the link.
-The *readlink* call may be used to read the contents of a symbolic
-link. Symbolic links may span file systems and may refer to
-directories.
-
-Given one or two arguments, ln creates a link to an existing file
-source_file. If target_file is given, the link has that name;
-target_file may also be a directory in which to place the link;
-otherwise it is placed in the current directory. If only the
-directory is specified, the link will be made to the last component of
-source_file.
-
-Given more than two arguments, ln makes links in target_dir to all the
-named source files. The links made will have the same name as the
-files being linked to.
-
-**EXIT STATUS:**
-
-The ``ln`` utility exits 0 on success, and >0 if an error occurs.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-.. code:: c
-
- SHLL \[/] ln -s /dev/console /dev/con1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_LN
-.. index:: CONFIGURE_SHELL_COMMAND_LN
-
-This command is included in the default shell command set. When
-building a custom command set, define``CONFIGURE_SHELL_COMMAND_LN`` to have this command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_LN`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_ln
-
-The ``ln`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_ln(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``ln`` has the following
-prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_LN_Command;
-
-**ORIGIN:**
-
-The implementation and portions of the documentation for this command
-are from NetBSD 4.0.
-
-ls - list files in the directory
---------------------------------
-.. index:: ls
-
-**SYNOPSYS:**
-
-.. code:: c
-
- ls \[dir]
-
-**DESCRIPTION:**
-
-This command displays the contents of the specified directory. If
-no arguments are given, then it displays the contents of the current
-working directory.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-This command currently does not display information on a set of
-files like the POSIX ls(1). It only displays the contents of
-entire directories.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``ls``:
-.. code:: c
-
- SHLL \[/] $ ls
- drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/
- drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/
- 2 files 1608 bytes occupied
- SHLL \[/] $ ls etc
- -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd
- -rw-r--r-- 1 root root 42 Jan 01 00:00 group
- -rw-r--r-- 1 root root 30 Jan 01 00:00 issue
- -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net
- 4 files 202 bytes occupied
- SHLL \[/] $ ls dev etc
- -rwxr-xr-x 1 rtems root 0 Jan 01 00:00 console
- -rwxr-xr-x 1 root root 0 Jan 01 00:00 console_b
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_LS
-.. index:: CONFIGURE_SHELL_COMMAND_LS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_LS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_ls
-
-The ``ls`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_ls(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``ls`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_LS_Command;
-
-md5 - compute the Md5 hash of a file or list of files
------------------------------------------------------
-.. index:: md5
-
-**SYNOPSYS:**
-
-.. code:: c
-
- md5 <files>
-
-**DESCRIPTION:**
-
-This command prints the MD5 of a file. You can provide one or more
-files on the command line and a hash for each file is printed in a
-single line of output.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``md5``:
-.. code:: c
-
- SHLL \[/] $ md5 shell-init
- MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MD5
-.. index:: CONFIGURE_SHELL_COMMAND_MD5
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MD5`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MD5`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_md5
-
-The ``df`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_main_md5(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``md5`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MD5_Command;
-
-mkdir - create a directory
---------------------------
-.. index:: mkdir
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mkdir dir \[dir1 .. dirN]
-
-**DESCRIPTION:**
-
-This command creates the set of directories in the order they
-are specified on the command line. If an error is encountered
-making one of the directories, the command will continue to
-attempt to create the remaining directories on the command line.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-If this command is invoked with no arguments, nothing occurs.
-
-The user must have sufficient permissions to create the directory.
-For the ``fileio`` test provided with RTEMS, this means the user
-must login as ``root`` not ``rtems``.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``mkdir``:
-.. code:: c
-
- SHLL \[/] # ls
- drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/
- drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/
- 2 files 1608 bytes occupied
- SHLL \[/] # mkdir joel
- SHLL \[/] # ls joel
- 0 files 0 bytes occupied
- SHLL \[/] # cp etc/passwd joel
- SHLL \[/] # ls joel
- -rw-r--r-- 1 root root 102 Jan 01 00:02 passwd
- 1 files 102 bytes occupied
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MKDIR
-.. index:: CONFIGURE_SHELL_COMMAND_MKDIR
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKDIR`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MKDIR`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mkdir
-
-The ``mkdir`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mkdir(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mkdir`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MKDIR_Command;
-
-mldos - DOSFS file system format
---------------------------------
-.. index:: pwd
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mkdir \[-V label] \[-s sectors/cluster] \[-r size] \[-v] path
-
-**DESCRIPTION:**
-
-This command formats a block device entry with the DOSFS file system.
-
-*-V label*
-
-*-s sectors/cluster*
-
-*-r size*
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``mkdos``:
-.. code:: c
-
- SHLL \[/] $ mkdos /dev/rda1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MKDOS
-.. index:: CONFIGURE_SHELL_COMMAND_MKDOS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKDOS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MKDOS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mkdos
-
-The ``mkdos`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mkdos(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mkdos`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MKDOS_Command;
-
-mknod - make device special file
---------------------------------
-.. index:: mknod
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mknod \[-rR] \[-F fmt] \[-g gid] \[-m mode] \[-u uid] name \[c | b]
- \[driver | major] minor
- mknod \[-rR] \[-F fmt] \[-g gid] \[-m mode] \[-u uid] name \[c | b]
- major unit subunit
- mknod \[-rR] \[-g gid] \[-m mode] \[-u uid] name \[c | b] number
- mknod \[-rR] \[-g gid] \[-m mode] \[-u uid] name p
-
-**DESCRIPTION:**
-
-The mknod command creates device special files, or fifos. Normally
-the shell script /dev/MAKEDEV is used to create special files for
-commonly known devices; it executes mknod with the appropriate
-arguments and can make all the files required for the device.
-
-To make nodes manually, the arguments are:
-
-*-r*
- Replace an existing file if its type is incorrect.
-
-*-R*
- Replace an existing file if its type is incorrect. Correct the
- mode, user and group.
-
-*-g gid*
- Specify the group for the device node. The gid operand may be a
- numeric group ID or a group name. If a group name is also a numeric
- group ID, the operand is used as a group name. Precede a numeric
- group ID with a # to stop it being treated as a name.
-
-*-m mode*
- Specify the mode for the device node. The mode may be absolute or
- symbolic, see *chmod*.
-
-*-u uid*
- Specify the user for the device node. The uid operand may be a
- numeric user ID or a user name. If a user name is also a numeric user
- ID, the operand is used as a user name. Precede a numeric user ID
- with a # to stop it being treated as a name.
-
-*name*
- Device name, for example “tty” for a termios serial device or “hd”
- for a disk.
-
-*b | c | p*
- Type of device. If the device is a block type device such as a tape
- or disk drive which needs both cooked and raw special files, the type
- is b. All other devices are character type devices, such as terminal
- and pseudo devices, and are type c. Specifying p creates fifo files.
-
-*driver | major*
- The major device number is an integer number which tells the kernel
- which device driver entry point to use. If the device driver is
- configured into the current kernel it may be specified by driver name
- or major number.
-
-*minor*
- The minor device number tells the kernel which one of several similar
- devices the node corresponds to; for example, it may be a specific
- serial port or pty.
-
-*unit and subunit*
- The unit and subunit numbers select a subset of a device; for example,
- the unit may specify a particular disk, and the subunit a partition on
- that disk. (Currently this form of specification is only supported
- by the bsdos format, for compatibility with the BSD/OS mknod).
-
-*number*
- A single opaque device number. Useful for netbooted computers which
- require device numbers packed in a format that isn’t supported by
- -F.
-
-**EXIT STATUS:**
-
-The ``mknod`` utility exits 0 on success, and >0 if an error occurs.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-.. code:: c
-
- SHLL \[/] mknod c 3 0 /dev/ttyS10
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MKNOD
-.. index:: CONFIGURE_SHELL_COMMAND_MKNOD
-
-This command is included in the default shell command set. When
-building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKNOD`` to have this command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MKNOD`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mknod
-
-The ``mknod`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mknod(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mknod`` has the following
-prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MKNOD_Command;
-
-**ORIGIN:**
-
-The implementation and portions of the documentation for this command
-are from NetBSD 4.0.
-
-mkrfs - format RFS file system
-------------------------------
-.. index:: mkrfs
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mkrfs \[-vsbiIo] device
-
-**DESCRIPTION:**
-
-Format the block device with the RTEMS File System (RFS). The default
-configuration with not parameters selects a suitable block size based
-on the size of the media being formatted.
-
-The media is broken up into groups of blocks. The number of blocks in
-a group is based on the number of bits a block contains. The large a
-block the more blocks a group contains and the fewer groups in the
-file system.
-
-The following options are provided:
-
-*-v*
- Display configuration and progress of the format.
-
-*-s*
- Set the block size in bytes.
-
-*-b*
- The number of blocks in a group. The block count must be equal or less
- than the number of bits in a block.
-
-*-i*
- Number of inodes in a group. The inode count must be equal or less
- than the number of bits in a block.
-
-*-I*
- Initialise the inodes. The default is not to initialise the inodes and
- to rely on the inode being initialised when allocated. Initialising
- the inode table helps recovery if a problem appears.
-
-*-o*
- Integer percentage of the media used by inodes. The default is 1%.
-
-*device*
- Path of the device to format.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``mkrfs``:
-.. code:: c
-
- SHLL \[/] $ mkrfs /dev/fdda
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MKRFS
-.. index:: CONFIGURE_SHELL_COMMAND_MKRFS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKRFS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MKRFS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mkrfs
-
-The ``mkrfs`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mkrfs(
- int argc,
- char \**argv
- );
-
-The configuration structure for ``mkrfs`` has the following
-prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MKRFS_Command;
-
-mount - mount disk
-------------------
-.. index:: mount
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mount \[-t fstype] \[-r] \[-L] device path
-
-**DESCRIPTION:**
-
-The ``mount`` command will mount a block device to a mount point
-using the specified file system. The files systems are:
-
-- msdos - MSDOS File System
-
-- tftp - TFTP Network File System
-
-- ftp - FTP Network File System
-
-- nfs - Network File System
-
-- rfs - RTEMS File System
-
-When the file system type is ’msdos’ or ’rfs’ the driver is a "block
-device driver" node present in the file system. The driver is ignored
-with the ’tftp’ and ’ftp’ file systems. For the ’nfs’ file system the
-driver is the ’host:/path’ string that described NFS host and the
-exported file system path.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The mount point must exist.
-
-The services offered by each file-system vary. For example you cannot list the
-directory of a TFTP file-system as this server is not provided in the TFTP
-protocol. You need to check each file-system’s documentation for the services
-provided.
-
-**EXAMPLES:**
-
-Mount the Flash Disk driver to the ’/fd’ mount point:
-.. code:: c
-
- SHLL \[/] $ mount -t msdos /dev/flashdisk0 /fd
-
-Mount the NFS file system exported path ’bar’ by host ’foo’:
-.. code:: c
-
- $ mount -t nfs foo:/bar /nfs
-
-Mount the TFTP file system on ’/tftp’:
-.. code:: c
-
- $ mount -t tftp /tftp
-
-To access the TFTP files on server ’10.10.10.10’:
-.. code:: c
-
- $ cat /tftp/10.10.10.10/test.txt
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MOUNT
-.. index:: CONFIGURE_SHELL_COMMAND_MOUNT
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MOUNT`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MOUNT`` when all
-shell commands have been configured.
-
-The mount command includes references to file-system code. If you do not wish
-to include file-system that you do not use do not define the mount command
-support for that file-system. The file-system mount command defines are:
-
-- msdos - CONFIGURE_SHELL_MOUNT_MSDOS
-
-- tftp - CONFIGURE_SHELL_MOUNT_TFTP
-
-- ftp - CONFIGURE_SHELL_MOUNT_FTP
-
-- nfs - CONFIGURE_SHELL_MOUNT_NFS
-
-- rfs - CONFIGURE_SHELL_MOUNT_RFS
-
-An example configuration is:
-.. code:: c
-
- #define CONFIGURE_SHELL_MOUNT_MSDOS
- #ifdef RTEMS_NETWORKING
- #define CONFIGURE_SHELL_MOUNT_TFTP
- #define CONFIGURE_SHELL_MOUNT_FTP
- #define CONFIGURE_SHELL_MOUNT_NFS
- #define CONFIGURE_SHELL_MOUNT_RFS
- #endif
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mount
-
-The ``mount`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mount(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mount`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MOUNT_Command;
-
-mv - move files
----------------
-.. index:: mv
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mv \[-fiv] source_file target_file
- mv \[-fiv] source_file... target_file
-
-**DESCRIPTION:**
-
-In its first form, the mv utility renames the file named by the source
-operand to the destination path named by the target operand. This
-form is assumed when the last operand does not name an already
-existing directory.
-
-In its second form, mv moves each file named by a source operand to a
-destination file in the existing directory named by the directory
-operand. The destination path for each operand is the pathname
-produced by the concatenation of the last operand, a slash, and the
-final pathname component of the named file.
-
-The following options are available:
-
-*-f*
- Do not prompt for confirmation before overwriting the destination
- path.
-
-*-i*
- Causes mv to write a prompt to standard error before moving a file
- that would overwrite an existing file. If the response from the
- standard input begins with the character ’y’, the move is attempted.
-
-*-v*
- Cause mv to be verbose, showing files as they are processed.
-
-The last of any -f or -i options is the one which affects mv’s
-behavior.
-
-It is an error for any of the source operands to specify a nonexistent
-file or directory.
-
-It is an error for the source operand to specify a directory if the
-target exists and is not a directory.
-
-If the destination path does not have a mode which permits writing, mv
-prompts the user for confirmation as specified for the -i option.
-
-Should the *rename* call fail because source and target are on
-different file systems, ``mv`` will remove the destination file,
-copy the source file to the destination, and then remove the source.
-The effect is roughly equivalent to:
-.. code:: c
-
- rm -f destination_path && \\
- cp -PRp source_file destination_path && \\
- rm -rf source_file
-
-**EXIT STATUS:**
-
-The ``mv`` utility exits 0 on success, and >0 if an error occurs.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-.. code:: c
-
- SHLL \[/] mv /dev/console /dev/con1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MV
-.. index:: CONFIGURE_SHELL_COMMAND_MV
-
-This command is included in the default shell command set. When
-building a custom command set, define``CONFIGURE_SHELL_COMMAND_MV`` to have this command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MV`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_main_mv
-
-The ``mv`` command is implemented by a C language function which
-has the following prototype:
-.. code:: c
-
- int rtems_shell_main_mv(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mv`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MV_Command;
-
-**ORIGIN:**
-
-The implementation and portions of the documentation for this command
-are from NetBSD 4.0.
-
-pwd - print work directory
---------------------------
-.. index:: pwd
-
-**SYNOPSYS:**
-
-.. code:: c
-
- pwd
-
-**DESCRIPTION:**
-
-This command prints the fully qualified filename of the current
-working directory.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``pwd``:
-.. code:: c
-
- SHLL \[/] $ pwd
- /
- SHLL \[/] $ cd dev
- SHLL \[/dev] $ pwd
- /dev
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_PWD
-.. index:: CONFIGURE_SHELL_COMMAND_PWD
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PWD`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_PWD`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_pwd
-
-The ``pwd`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_pwd(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``pwd`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_PWD_Command;
-
-rmdir - remove empty directories
---------------------------------
-.. index:: rmdir
-
-**SYNOPSYS:**
-
-.. code:: c
-
- rmdir \[dir1 .. dirN]
-
-**DESCRIPTION:**
-
-This command removes the specified set of directories. If no
-directories are provided on the command line, no actions are taken.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-This command is a implemented using the ``rmdir(2)`` system
-call and all reasons that call may fail apply to this command.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``rmdir``:
-.. code:: c
-
- SHLL \[/] # mkdir joeldir
- SHLL \[/] # rmdir joeldir
- SHLL \[/] # ls joeldir
- joeldir: No such file or directory.
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_RMDIR
-.. index:: CONFIGURE_SHELL_COMMAND_RMDIR
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_RMDIR`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_RMDIR`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_rmdir
-
-The ``rmdir`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_rmdir(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``rmdir`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_RMDIR_Command;
-
-rm - remove files
------------------
-.. index:: rm
-
-**SYNOPSYS:**
-
-.. code:: c
-
- rm file1 \[file2 ... fileN]
-
-**DESCRIPTION:**
-
-This command deletes a name from the filesystem. If the specified file name
-was the last link to a file and there are no ``open`` file descriptor
-references to that file, then it is deleted and the associated space in
-the file system is made available for subsequent use.
-
-If the filename specified was the last link to a file but there
-are open file descriptor references to it, then the file will
-remain in existence until the last file descriptor referencing
-it is closed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``rm``:
-.. code:: c
-
- SHLL \[/] # cp /etc/passwd tmpfile
- SHLL \[/] # cat tmpfile
- root:\*:0:0:root::/:/bin/sh
- rtems:\*:1:1:RTEMS Application::/:/bin/sh
- tty:!:2:2:tty owner::/:/bin/false
- SHLL \[/] # rm tmpfile
- SHLL \[/] # cat tmpfile
- cat: tmpfile: No such file or directory
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_RM
-.. index:: CONFIGURE_SHELL_COMMAND_RM
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_RM`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_RM`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_main_rm
-
-The ``rm`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_main_rm(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``rm`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_RM_Command;
-
-umask - set file mode creation mask
------------------------------------
-.. index:: umask
-
-**SYNOPSYS:**
-
-.. code:: c
-
- umask \[new_umask]
-
-**DESCRIPTION:**
-
-This command sets the user file creation mask to ``new_umask``. The
-argument ``new_umask`` may be octal, hexadecimal, or decimal.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-This command does not currently support symbolic mode masks.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``umask``:
-.. code:: c
-
- SHLL \[/] $ umask
- 022
- SHLL \[/] $ umask 0666
- 0666
- SHLL \[/] $ umask
- 0666
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_UMASK
-.. index:: CONFIGURE_SHELL_COMMAND_UMASK
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_UMASK`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_UMASK`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_umask
-
-The ``umask`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_umask(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``umask`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_UMASK_Command;
-
-unmount - unmount disk
-----------------------
-.. index:: unmount
-
-**SYNOPSYS:**
-
-.. code:: c
-
- unmount path
-
-**DESCRIPTION:**
-
-This command unmounts the device at the specified ``path``.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-TBD - Surely there must be some warnings to go here.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``unmount``:
-.. code:: c
-
- EXAMPLE_TBD
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_UNMOUNT
-.. index:: CONFIGURE_SHELL_COMMAND_UNMOUNT
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_UNMOUNT`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_UNMOUNT`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_unmount
-
-The ``unmount`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_unmount(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``unmount`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command;
-
-.. COMMENT: COPYRIGHT (c) 1988-2012.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Memory Commands
-###############
-
-Introduction
-============
-
-The RTEMS shell has the following memory commands:
-
-- ``mdump`` - Display contents of memory
-
-- ``wdump`` - Display contents of memory (word)
-
-- ``ldump`` - Display contents of memory (longword)
-
-- ``medit`` - Modify contents of memory
-
-- ``mfill`` - File memory with pattern
-
-- ``mmove`` - Move contents of memory
-
-- ``malloc`` - Obtain information on C Program Heap
-
-Commands
-========
-
-This section details the Memory Commands available. A
-subsection is dedicated to each of the commands and
-describes the behavior and configuration of that
-command as well as providing an example usage.
-
-mdump - display contents of memory
-----------------------------------
-.. index:: mdump
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mdump \[address \[length \[size]]]
-
-**DESCRIPTION:**
-
-This command displays the contents of memory at the ``address``
-and ``length`` in ``size`` byte units specified on the command line.
-
-When ``size`` is not provided, it defaults to ``1`` byte units.
-Values of ``1``, ``2``, and ``4`` are valid; all others will
-cause an error to be reported.
-
-When ``length`` is not provided, it defaults to ``320`` which
-is twenty lines of output with sixteen bytes of output per line.
-
-When ``address`` is not provided, it defaults to ``0x00000000``.
-
-**EXIT STATUS:**
-
-This command always returns 0 to indicate success.
-
-**NOTES:**
-
-Dumping memory from a non-existent address may result in an unrecoverable
-program fault.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``mdump``:
-.. code:: c
-
- SHLL \[/] $ mdump 0x10000 32
- 0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
- 0x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
- SHLL \[/] $ mdump 0x02000000 32
- 0x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
- 0x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
- SHLL \[/] $ mdump 0x02001000 32
- 0x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`.....H..
- 0x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(..
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MDUMP
-.. index:: CONFIGURE_SHELL_COMMAND_MDUMP
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mdump
-
-The ``mdump`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mdump(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mdump`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MDUMP_Command;
-
-wdump - display contents of memory (word)
------------------------------------------
-.. index:: wdump
-
-**SYNOPSYS:**
-
-.. code:: c
-
- wdump \[address \[length]]
-
-**DESCRIPTION:**
-
-This command displays the contents of memory at the ``address``
-and ``length`` in bytes specified on the command line.
-
-This command is equivalent to ``mdump address length 2``.
-
-When ``length`` is not provided, it defaults to ``320`` which
-is twenty lines of output with eight words of output per line.
-
-When ``address`` is not provided, it defaults to ``0x00000000``.
-
-**EXIT STATUS:**
-
-This command always returns 0 to indicate success.
-
-**NOTES:**
-
-Dumping memory from a non-existent address may result in an unrecoverable
-program fault.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``wdump``:
-.. code:: c
-
- SHLL \[/] $ wdump 0x02010000 32
- 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t
- 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...............
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP
-.. index:: CONFIGURE_SHELL_COMMAND_WDUMP
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_wdump
-
-The ``wdump`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_wdump(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``wdump`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_WDUMP_Command;
-
-ldump - display contents of memory (longword)
----------------------------------------------
-.. index:: ldump
-
-**SYNOPSYS:**
-
-.. code:: c
-
- ldump \[address \[length]]
-
-**DESCRIPTION:**
-
-This command displays the contents of memory at the ``address``
-and ``length`` in bytes specified on the command line.
-
-This command is equivalent to ``mdump address length 4``.
-
-When ``length`` is not provided, it defaults to ``320`` which
-is twenty lines of output with four longwords of output per line.
-
-When ``address`` is not provided, it defaults to ``0x00000000``.
-
-**EXIT STATUS:**
-
-This command always returns 0 to indicate success.
-
-**NOTES:**
-
-Dumping memory from a non-existent address may result in an unrecoverable
-program fault.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``ldump``:
-.. code:: c
-
- SHLL \[/] $ ldump 0x02010000 32
- 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t
- 0x02010010 020 0894 02010718-02010640 02010798 ...............
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP
-.. index:: CONFIGURE_SHELL_COMMAND_LDUMP
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_ldump
-
-The ``ldump`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_ldump(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``ldump`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_LDUMP_Command;
-
-medit - modify contents of memory
----------------------------------
-.. index:: medit
-
-**SYNOPSYS:**
-
-.. code:: c
-
- medit address value1 \[value2 ... valueN]
-
-**DESCRIPTION:**
-
-This command is used to modify the contents of the memory starting
-at ``address`` using the octets specified by the parameters``value1`` through ``valueN``.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-Dumping memory from a non-existent address may result in an unrecoverable
-program fault.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``medit``:
-.. code:: c
-
- SHLL \[/] $ mdump 0x02000000 32
- 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
- 0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
- SHLL \[/] $ medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
- SHLL \[/] $ mdump 0x02000000 32
- 0x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!.
- 0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MEDIT
-.. index:: CONFIGURE_SHELL_COMMAND_MEDIT
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_medit
-
-The ``medit`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_medit(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``medit`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MEDIT_Command;
-
-mfill - file memory with pattern
---------------------------------
-.. index:: mfill
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mfill address length value
-
-**DESCRIPTION:**
-
-This command is used to fill the memory starting at ``address``
-for the specified ``length`` in octets when the specified at``value``.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-Filling a non-existent address range may result in an unrecoverable
-program fault. Similarly overwriting interrupt vector tables, code
-space or critical data areas can be fatal as shown in the example.
-
-**EXAMPLES:**
-
-In this example, the address used (``0x23d89a0``) as the base
-address of the filled area is the end of the stack for the
-Idle thread. This address was determined manually using gdb and
-is very specific to this application and BSP. The first command
-in this example is an ``mdump`` to display the initial contents
-of this memory. We see that the first 8 bytes are 0xA5 which is
-the pattern used as a guard by the Stack Checker. On
-the first context switch after the pattern is overwritten
-by the ``mfill`` command, the Stack Checker detect the pattern
-has been corrupted and generates a fatal error.
-.. code:: c
-
- SHLL \[/] $ mdump 0x23d89a0 16
- 0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................
- SHLL \[/] $ mfill 0x23d89a0 13 0x5a
- SHLL \[/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908
- stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
- Damaged pattern begins at 0x023D89A8 and is 16 bytes long
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL
-.. index:: CONFIGURE_SHELL_COMMAND_MFILL
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mfill
-
-The ``mfill`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mfill(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mfill`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
-
-mmove - move contents of memory
--------------------------------
-.. index:: mmove
-
-**SYNOPSYS:**
-
-.. code:: c
-
- mmove dst src length
-
-**DESCRIPTION:**
-
-This command is used to copy the contents of the memory
-starting at ``src`` to the memory located at ``dst``
-for the specified ``length`` in octets.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``mmove``:
-.. code:: c
-
- SHLL \[/] $ mdump 0x023d99a0 16
- 0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................
- SHLL \[/] $ mdump 0x02000000 16
- 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
- SHLL \[/] $ mmove 0x023d99a0 0x02000000 13
- SHLL \[/] $ mdump 0x023d99a0 16
- 0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3..".....
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MMOVE
-.. index:: CONFIGURE_SHELL_COMMAND_MMOVE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_mmove
-
-The ``mmove`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_mmove(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``mmove`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
-
-malloc - obtain information on C program heap
----------------------------------------------
-.. index:: malloc
-
-**SYNOPSYS:**
-
-.. code:: c
-
- malloc \[walk]
-
-**DESCRIPTION:**
-
-This command prints information about the current state of the C Program Heap
-used by the ``malloc()`` family of calls if no or invalid options are passed
-to the command. This includes the following information:
-
-- Number of free blocks
-
-- Largest free block
-
-- Total bytes free
-
-- Number of used blocks
-
-- Largest used block
-
-- Total bytes used
-
-- Size of the allocatable area in bytes
-
-- Minimum free size ever in bytes
-
-- Maximum number of free blocks ever
-
-- Maximum number of blocks searched ever
-
-- Lifetime number of bytes allocated
-
-- Lifetime number of bytes freed
-
-- Total number of searches
-
-- Total number of successful allocations
-
-- Total number of failed allocations
-
-- Total number of successful frees
-
-- Total number of successful resizes
-
-When the subcommand ``walk`` is specified, then a heap walk will be
-performed and information about each block is printed out.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use the ``malloc`` command.
-.. code:: c
-
- SHLL \[/] $ malloc
- C Program Heap and RTEMS Workspace are the same.
- Number of free blocks: 2
- Largest free block: 266207504
- Total bytes free: 266208392
- Number of used blocks: 167
- Largest used block: 16392
- Total bytes used: 83536
- Size of the allocatable area in bytes: 266291928
- Minimum free size ever in bytes: 266207360
- Maximum number of free blocks ever: 6
- Maximum number of blocks searched ever: 5
- Lifetime number of bytes allocated: 91760
- Lifetime number of bytes freed: 8224
- Total number of searches: 234
- Total number of successful allocations: 186
- Total number of failed allocations: 0
- Total number of successful frees: 19
- Total number of successful resizes: 0
- SHLL \[/] $ malloc walk
- malloc walk
- PASS[0]: page size 8, min block size 48
- area begin 0x00210210, area end 0x0FFFC000
- first block 0x00210214, last block 0x0FFFBFDC
- first free 0x00228084, last free 0x00228354
- PASS[0]: block 0x00210214: size 88
- ...
- PASS[0]: block 0x00220154: size 144
- PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free)
- PASS[0]: block 0x0022028C: size 168, prev_size 168
- ...
- PASS[0]: block 0x00226E7C: size 4136
- PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4
- PASS[0]: block 0x0022803C: size 72, prev_size 408
- PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4
- PASS[0]: block 0x0022830C: size 72, prev_size 648
- PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail)
- PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC
-.. index:: CONFIGURE_SHELL_COMMAND_MALLOC
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_malloc
-
-The ``malloc`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_malloc(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``malloc`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_MALLOC_Command;
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-RTEMS Specific Commands
-#######################
-
-Introduction
-============
-
-The RTEMS shell has the following RTEMS specific commands:
-
-- ``shutdown`` - Shutdown the system
-
-- ``cpuuse`` - print or reset per thread cpu usage
-
-- ``stackuse`` - print per thread stack usage
-
-- ``perioduse`` - print or reset per period usage
-
-- ``profreport`` - print a profiling report
-
-- ``wkspace`` - Display information on Executive Workspace
-
-- ``config`` - Show the system configuration.
-
-- ``itask`` - List init tasks for the system
-
-- ``extension`` - Display information about extensions
-
-- ``task`` - Display information about tasks
-
-- ``queue`` - Display information about message queues
-
-- ``sema`` - display information about semaphores
-
-- ``region`` - display information about regions
-
-- ``part`` - display information about partitions
-
-- ``object`` - Display information about RTEMS objects
-
-- ``driver`` - Display the RTEMS device driver table
-
-- ``dname`` - Displays information about named drivers
-
-- ``pthread`` - Displays information about POSIX threads
-
-Commands
-========
-
-This section details the RTEMS Specific Commands available. A
-subsection is dedicated to each of the commands and
-describes the behavior and configuration of that
-command as well as providing an example usage.
-
-shutdown - Shutdown the system
-------------------------------
-.. index:: shutdown
-
-**SYNOPSYS:**
-
-.. code:: c
-
- shutdown
-
-**DESCRIPTION:**
-
-This command is used to shutdown the RTEMS application.
-
-**EXIT STATUS:**
-
-This command does not return.
-
-**NOTES:**
-
-**EXAMPLES:**
-
-The following is an example of how to use ``shutdown``:
-.. code:: c
-
- SHLL \[/] $ shutdown
- System shutting down at user request
-
-The user will not see another prompt and the system will
-shutdown.
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN
-.. index:: CONFIGURE_SHELL_COMMAND_SHUTDOWN
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SHUTDOWN`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-The configuration structure for the ``shutdown`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command;
-
-cpuuse - print or reset per thread cpu usage
---------------------------------------------
-.. index:: cpuuse
-
-**SYNOPSYS:**
-
-.. code:: c
-
- cpuuse \[-r]
-
-**DESCRIPTION:**
-
-This command may be used to print a report on the per thread
-cpu usage or to reset the per thread CPU usage statistics. When
-invoked with the ``-r`` option, the CPU usage statistics
-are reset.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The granularity of the timing information reported is dependent
-upon the BSP and the manner in which RTEMS was built. In the
-default RTEMS configuration, if the BSP supports nanosecond
-granularity timestamps, then the information reported will be
-highly accurate. Otherwise, the accuracy of the information
-reported is limited by the clock tick quantum.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``cpuuse``:
-.. code:: c
-
- SHLL \[/] $ cpuuse
- CPU Usage by thread
- ID NAME SECONDS PERCENT
- 0x09010001 IDLE 49.745393 98.953
- 0x0a010001 UI1 0.000000 0.000
- 0x0a010002 SHLL 0.525928 1.046
- Time since last CPU Usage reset 50.271321 seconds
- SHLL \[/] $ cpuuse -r
- Resetting CPU Usage information
- SHLL \[/] $ cpuuse
- CPU Usage by thread
- ID NAME SECONDS PERCENT
- 0x09010001 IDLE 0.000000 0.000
- 0x0a010001 UI1 0.000000 0.000
- 0x0a010002 SHLL 0.003092 100.000
- Time since last CPU Usage reset 0.003092 seconds
-
-In the above example, the system had set idle for nearly
-a minute when the first report was generated. The``cpuuse -r`` and ``cpuuse`` commands were pasted
-from another window so were executed with no gap between.
-In the second report, only the ``shell`` thread has
-run since the CPU Usage was reset. It has consumed
-approximately 3.092 milliseconds of CPU time processing
-the two commands and generating the output.
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CPUUSE
-.. index:: CONFIGURE_SHELL_COMMAND_CPUUSE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CPUUSE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CPUUSE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_cpuuse
-
-The ``cpuuse`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_cpuuse(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``cpuuse`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command;
-
-stackuse - print per thread stack usage
----------------------------------------
-.. index:: stackuse
-
-**SYNOPSYS:**
-
-.. code:: c
-
- stackuse
-
-**DESCRIPTION:**
-
-This command prints a Stack Usage Report for all of the tasks
-and threads in the system. On systems which support it, the
-usage of the interrupt stack is also included in the report.
-
-**EXIT STATUS:**
-
-This command always succeeds and returns 0.
-
-**NOTES:**
-
-The ``CONFIGURE_STACK_CHECKER_ENABLED`` ``confdefs.h`` constant
-must be defined when the application is configured for this
-command to have any information to report.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``stackuse``:
-.. code:: c
-
- SHLL \[/] $ stackuse
- Stack usage by thread
- ID NAME LOW HIGH CURRENT AVAILABLE USED
- 0x09010001 IDLE 0x023d89a0 - 0x023d99af 0x023d9760 4096 608
- 0x0a010001 UI1 0x023d9f30 - 0x023daf3f 0x023dad18 4096 1804
- 0x0a010002 SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0 16384 5116
- 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_STACKUSE
-.. index:: CONFIGURE_SHELL_COMMAND_STACKUSE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_STACKUSE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_STACKUSE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_stackuse
-
-The ``stackuse`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_stackuse(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``stackuse`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command;
-
-perioduse - print or reset per period usage
--------------------------------------------
-.. index:: perioduse
-
-**SYNOPSYS:**
-
-.. code:: c
-
- perioduse \[-r]
-
-**DESCRIPTION:**
-
-This command may be used to print a statistics report on the rate
-monotonic periods in the application or to reset the rate monotonic
-period usage statistics. When invoked with the ``-r`` option, the
-usage statistics are reset.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-The granularity of the timing information reported is dependent
-upon the BSP and the manner in which RTEMS was built. In the
-default RTEMS configuration, if the BSP supports nanosecond
-granularity timestamps, then the information reported will be
-highly accurate. Otherwise, the accuracy of the information
-reported is limited by the clock tick quantum.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``perioduse``:
-.. code:: c
-
- SHLL \[/] $ perioduse
- Period information by period
- --- CPU times are in seconds ---
- --- Wall times are in seconds ---
- ID OWNER COUNT MISSED CPU TIME WALL TIME
- MIN/MAX/AVG MIN/MAX/AVG
- 0x42010001 TA1 502 0 0:000039/0:042650/0:004158 0:000039/0:020118/0:002848
- 0x42010002 TA2 502 0 0:000041/0:042657/0:004309 0:000041/0:020116/0:002848
- 0x42010003 TA3 501 0 0:000041/0:041564/0:003653 0:000041/0:020003/0:002814
- 0x42010004 TA4 501 0 0:000043/0:044075/0:004911 0:000043/0:020004/0:002814
- 0x42010005 TA5 10 0 0:000065/0:005413/0:002739 0:000065/1:000457/0:041058
- MIN/MAX/AVG MIN/MAX/AVG
- SHLL \[/] $ perioduse -r
- Resetting Period Usage information
- SHLL \[/] $ perioduse
- --- CPU times are in seconds ---
- --- Wall times are in seconds ---
- ID OWNER COUNT MISSED CPU TIME WALL TIME
- MIN/MAX/AVG MIN/MAX/AVG
- 0x42010001 TA1 0 0
- 0x42010002 TA2 0 0
- 0x42010003 TA3 0 0
- 0x42010004 TA4 0 0
- 0x42010005 TA5 0 0
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_PERIODUSE
-.. index:: CONFIGURE_SHELL_COMMAND_PERIODUSE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PERIODUSE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_PERIODUSE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_perioduse
-
-The ``perioduse`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_perioduse(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``perioduse`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command;
-
-profreport - print a profiling report
--------------------------------------
-.. index:: profreport
-
-**SYNOPSYS:**
-
-.. code:: c
-
- profreport
-
-**DESCRIPTION:**
-
-This command may be used to print a profiling report.
-
-**EXIT STATUS:**
-
-This command returns 0.
-
-**NOTES:**
-
-Profiling must be enabled at build configuration time to get profiling
-information.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``profreport``:
-.. code:: c
-
- SHLL \[/] $ profreport
- <ProfilingReport name="Shell">
- <PerCPUProfilingReport processorIndex="0">
- <MaxThreadDispatchDisabledTime unit="ns">10447</MaxThreadDispatchDisabledTime>
- <MeanThreadDispatchDisabledTime unit="ns">2</MeanThreadDispatchDisabledTime>
- <TotalThreadDispatchDisabledTime unit="ns">195926627</TotalThreadDispatchDisabledTime>
- <ThreadDispatchDisabledCount>77908688</ThreadDispatchDisabledCount>
- <MaxInterruptDelay unit="ns">0</MaxInterruptDelay>
- <MaxInterruptTime unit="ns">688</MaxInterruptTime>
- <MeanInterruptTime unit="ns">127</MeanInterruptTime>
- <TotalInterruptTime unit="ns">282651157</TotalInterruptTime>
- <InterruptCount>2215855</InterruptCount>
- </PerCPUProfilingReport>
- <PerCPUProfilingReport processorIndex="1">
- <MaxThreadDispatchDisabledTime unit="ns">9053</MaxThreadDispatchDisabledTime>
- <MeanThreadDispatchDisabledTime unit="ns">41</MeanThreadDispatchDisabledTime>
- <TotalThreadDispatchDisabledTime unit="ns">3053830335</TotalThreadDispatchDisabledTime>
- <ThreadDispatchDisabledCount>73334202</ThreadDispatchDisabledCount>
- <MaxInterruptDelay unit="ns">0</MaxInterruptDelay>
- <MaxInterruptTime unit="ns">57</MaxInterruptTime>
- <MeanInterruptTime unit="ns">35</MeanInterruptTime>
- <TotalInterruptTime unit="ns">76980203</TotalInterruptTime>
- <InterruptCount>2141179</InterruptCount>
- </PerCPUProfilingReport>
- <SMPLockProfilingReport name="SMP lock stats">
- <MaxAcquireTime unit="ns">608</MaxAcquireTime>
- <MaxSectionTime unit="ns">1387</MaxSectionTime>
- <MeanAcquireTime unit="ns">112</MeanAcquireTime>
- <MeanSectionTime unit="ns">338</MeanSectionTime>
- <TotalAcquireTime unit="ns">119031</TotalAcquireTime>
- <TotalSectionTime unit="ns">357222</TotalSectionTime>
- <UsageCount>1055</UsageCount>
- <ContentionCount initialQueueLength="0">1055</ContentionCount>
- <ContentionCount initialQueueLength="1">0</ContentionCount>
- <ContentionCount initialQueueLength="2">0</ContentionCount>
- <ContentionCount initialQueueLength="3">0</ContentionCount>
- </SMPLockProfilingReport>
- <SMPLockProfilingReport name="Giant">
- <MaxAcquireTime unit="ns">4186</MaxAcquireTime>
- <MaxSectionTime unit="ns">7575</MaxSectionTime>
- <MeanAcquireTime unit="ns">160</MeanAcquireTime>
- <MeanSectionTime unit="ns">183</MeanSectionTime>
- <TotalAcquireTime unit="ns">1772793111</TotalAcquireTime>
- <TotalSectionTime unit="ns">2029733879</TotalSectionTime>
- <UsageCount>11039140</UsageCount>
- <ContentionCount initialQueueLength="0">11037655</ContentionCount>
- <ContentionCount initialQueueLength="1">1485</ContentionCount>
- <ContentionCount initialQueueLength="2">0</ContentionCount>
- <ContentionCount initialQueueLength="3">0</ContentionCount>
- </SMPLockProfilingReport>
- </ProfilingReport>
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_PROFREPORT
-.. index:: CONFIGURE_SHELL_COMMAND_PROFREPORT
-
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PROFREPORT`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_PROFREPORT`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-The configuration structure for the ``profreport`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command;
-
-wkspace - display information on executive workspace
-----------------------------------------------------
-.. index:: wkspace
-
-**SYNOPSYS:**
-
-.. code:: c
-
- wkspace
-
-**DESCRIPTION:**
-
-This command prints information on the current state of
-the RTEMS Executive Workspace reported. This includes the
-following information:
-
-- Number of free blocks
-
-- Largest free block
-
-- Total bytes free
-
-- Number of used blocks
-
-- Largest used block
-
-- Total bytes used
-
-**EXIT STATUS:**
-
-This command always succeeds and returns 0.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``wkspace``:
-.. code:: c
-
- SHLL \[/] $ wkspace
- Number of free blocks: 1
- Largest free block: 132336
- Total bytes free: 132336
- Number of used blocks: 36
- Largest used block: 16408
- Total bytes used: 55344
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_WKSPACE
-.. index:: CONFIGURE_SHELL_COMMAND_WKSPACE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WKSPACE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_WKSPACE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_wkspace
-
-The ``wkspace`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_wkspace(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``wkspace`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command;
-
-config - show the system configuration.
----------------------------------------
-.. index:: config
-
-**SYNOPSYS:**
-
-.. code:: c
-
- config
-
-**DESCRIPTION:**
-
-This command display information about the RTEMS Configuration.
-
-**EXIT STATUS:**
-
-This command always succeeds and returns 0.
-
-**NOTES:**
-
-At this time, it does not report every configuration parameter.
-This is an area in which user submissions or sponsorship of
-a developer would be appreciated.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``config``:
-.. code:: c
-
- INITIAL (startup) Configuration Info
-
- WORKSPACE start: 0x23d22e0; size: 0x2dd20
- TIME usec/tick: 10000; tick/timeslice: 50; tick/sec: 100
- MAXIMUMS tasks: 20; timers: 0; sems: 50; que's: 20; ext's: 1
- partitions: 0; regions: 0; ports: 0; periods: 0
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_CONFIG
-.. index:: CONFIGURE_SHELL_COMMAND_CONFIG
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CONFIG`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_CONFIG`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_config
-
-The ``config`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_config(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``config`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_CONFIG_Command;
-
-itask - list init tasks for the system
---------------------------------------
-.. index:: itask
-
-**SYNOPSYS:**
-
-.. code:: c
-
- itask
-
-**DESCRIPTION:**
-
-This command prints a report on the set of initialization
-tasks and threads in the system.
-
-**EXIT STATUS:**
-
-This command always succeeds and returns 0.
-
-**NOTES:**
-
-At this time, it includes only Classic API Initialization Tasks.
-This is an area in which user submissions or sponsorship of
-a developer would be appreciated.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``itask``:
-.. code:: c
-
- SHLL \[/] $ itask
- # NAME ENTRY ARGUMENT PRIO MODES ATTRIBUTES STACK SIZE
- ------------------------------------------------------------------------------
- 0 UI1 \[0x2002258] 0 \[0x0] 1 nP DEFAULT 4096 \[0x1000]
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_ITASK
-.. index:: CONFIGURE_SHELL_COMMAND_ITASK
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ITASK`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_ITASK`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_itask
-
-The ``itask`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_itask(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``itask`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_ITASK_Command;
-
-extension - display information about extensions
-------------------------------------------------
-.. index:: extension
-
-**SYNOPSYS:**
-
-.. code:: c
-
- extension \[id \[id ...] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of User Extensions currently active in the system.
-
-If invoked with a set of ids as arguments, then just
-those objects are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of using the ``extension`` command
-on a system with no user extensions.
-.. code:: c
-
- SHLL \[/] $ extension
- ID NAME
- ------------------------------------------------------------------------------
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_EXTENSION
-.. index:: CONFIGURE_SHELL_COMMAND_EXTENSION
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_EXTENSION`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_EXTENSION`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_extension
-
-The ``extension`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_extension(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``extension`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command;
-
-task - display information about tasks
---------------------------------------
-.. index:: task
-
-**SYNOPSYS:**
-
-.. code:: c
-
- task \[id \[id ...] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of Classic API Tasks currently active in the system.
-
-If invoked with a set of ids as arguments, then just
-those objects are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use the ``task`` on an
-application with just two Classic API tasks:
-.. code:: c
-
- SHLL \[/] $ task
- ID NAME PRIO STAT MODES EVENTS WAITID WAITARG NOTES
- ------------------------------------------------------------------------------
- 0a010001 UI1 1 SUSP P:T:nA NONE
- 0a010002 SHLL 100 READY P:T:nA NONE
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_TASK
-.. index:: CONFIGURE_SHELL_COMMAND_TASK
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_TASK`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_TASK`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_task
-
-The ``task`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_task(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``task`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_TASK_Command;
-
-queue - display information about message queues
-------------------------------------------------
-.. index:: queue
-
-**SYNOPSYS:**
-
-.. code:: c
-
- queue \[id \[id ... ] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of Classic API Message Queues currently active in the system.
-
-If invoked with a set of ids as arguments, then just
-those objects are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of using the ``queue`` command
-on a system with no Classic API Message Queues.
-.. code:: c
-
- SHLL \[/] $ queue
- ID NAME ATTRIBUTES PEND MAXPEND MAXSIZE
- ------------------------------------------------------------------------------
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_QUEUE
-.. index:: CONFIGURE_SHELL_COMMAND_QUEUE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_QUEUE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_QUEUE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_queue
-
-The ``queue`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_queue(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``queue`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_QUEUE_Command;
-
-sema - display information about semaphores
--------------------------------------------
-.. index:: sema
-
-**SYNOPSYS:**
-
-.. code:: c
-
- sema \[id \[id ... ] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of Classic API Semaphores currently active in the system.
-
-If invoked with a set of objects ids as arguments, then just
-those objects are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``sema``:
-.. code:: c
-
- SHLL \[/] $ sema
- ID NAME ATTR PRICEIL CURR_CNT HOLDID
- ------------------------------------------------------------------------------
- 1a010001 LBIO PR:BI:IN 0 1 00000000
- 1a010002 TRmi PR:BI:IN 0 1 00000000
- 1a010003 LBI00 PR:BI:IN 0 1 00000000
- 1a010004 TRia PR:BI:IN 0 1 00000000
- 1a010005 TRoa PR:BI:IN 0 1 00000000
- 1a010006 TRxa <assoc.c: BAD NAME> 0 0 09010001
- 1a010007 LBI01 PR:BI:IN 0 1 00000000
- 1a010008 LBI02 PR:BI:IN 0 1 00000000
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_SEMA
-.. index:: CONFIGURE_SHELL_COMMAND_SEMA
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SEMA`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_SEMA`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_sema
-
-The ``sema`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_sema(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``sema`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_SEMA_Command;
-
-region - display information about regions
-------------------------------------------
-.. index:: region
-
-**SYNOPSYS:**
-
-.. code:: c
-
- region \[id \[id ... ] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of Classic API Regions currently active in the system.
-
-If invoked with a set of object ids as arguments, then just
-those object are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of using the ``region`` command
-on a system with no user extensions.
-.. code:: c
-
- SHLL \[/] $ region
- ID NAME ATTR STARTADDR LENGTH PAGE_SIZE USED_BLOCKS
- ------------------------------------------------------------------------------
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_REGION
-.. index:: CONFIGURE_SHELL_COMMAND_REGION
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_REGION`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_REGION`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_region
-
-The ``region`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_region(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``region`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_REGION_Command;
-
-part - display information about partitions
--------------------------------------------
-.. index:: part
-
-**SYNOPSYS:**
-
-.. code:: c
-
- part \[id \[id ... ] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of Classic API Partitions currently active in the system.
-
-If invoked with a set of object ids as arguments, then just
-those objects are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of using the ``part`` command
-on a system with no user extensions.
-.. code:: c
-
- SHLL \[/] $ part
- ID NAME ATTR STARTADDR LENGTH BUF_SIZE USED_BLOCKS
- ------------------------------------------------------------------------------
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_PART
-.. index:: CONFIGURE_SHELL_COMMAND_PART
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PART`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_PART`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_part
-
-The ``part`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_part(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``part`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_PART_Command;
-
-object - display information about RTEMS objects
-------------------------------------------------
-.. index:: object
-
-**SYNOPSYS:**
-
-.. code:: c
-
- object \[id \[id ...] ]
-
-**DESCRIPTION:**
-
-When invoked with a set of object ids as arguments, then
-a report on those objects is printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``object``:
-.. code:: c
-
- SHLL \[/] $ object 0a010001 1a010002
- ID NAME PRIO STAT MODES EVENTS WAITID WAITARG NOTES
- ------------------------------------------------------------------------------
- 0a010001 UI1 1 SUSP P:T:nA NONE
- ID NAME ATTR PRICEIL CURR_CNT HOLDID
- ------------------------------------------------------------------------------
- 1a010002 TRmi PR:BI:IN 0 1 00000000
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_OBJECT
-.. index:: CONFIGURE_SHELL_COMMAND_OBJECT
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_OBJECT`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_OBJECT`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_object
-
-The ``object`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_object(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``object`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_OBJECT_Command;
-
-driver - display the RTEMS device driver table
-----------------------------------------------
-.. index:: driver
-
-**SYNOPSYS:**
-
-.. code:: c
-
- driver [ major [ major ... ] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of Device Drivers currently active in the system.
-
-If invoked with a set of major numbers as arguments, then just
-those Device Drivers are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``driver``:
-.. code:: c
-
- SHLL \[/] $ driver
- Major Entry points
- ------------------------------------------------------------------------------
- 0 init: \[0x200256c]; control: \[0x20024c8]
- open: \[0x2002518]; close: \[0x2002504]
- read: \[0x20024f0]; write: \[0x20024dc]
- 1 init: \[0x20023fc]; control: \[0x2002448]
- open: \[0x0]; close: \[0x0]
- read: \[0x0]; write: \[0x0]
- SHLL \[/] $
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DRIVER
-.. index:: CONFIGURE_SHELL_COMMAND_DRIVER
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DRIVER`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_DRIVER`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_driver
-
-The ``driver`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_driver(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``driver`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DRIVER_Command;
-
-dname - displays information about named drivers
-------------------------------------------------
-.. index:: dname
-
-**SYNOPSYS:**
-
-.. code:: c
-
- dname
-
-**DESCRIPTION:**
-
-This command XXX
-
-WARNING! XXX This command does not appear to work as of 27 February 2008.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``dname``:
-.. code:: c
-
- EXAMPLE_TBD
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_DNAME
-.. index:: CONFIGURE_SHELL_COMMAND_DNAME
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DNAME`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_DNAME`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_dname
-
-The ``dname`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_dname(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``dname`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_DNAME_Command;
-
-pthread - display information about POSIX threads
--------------------------------------------------
-.. index:: pthread
-
-**SYNOPSYS:**
-
-.. code:: c
-
- pthread \[id \[id ...] ]
-
-**DESCRIPTION:**
-
-When invoked with no arguments, this command prints information on
-the set of POSIX API threads currently active in the system.
-
-If invoked with a set of ids as arguments, then just
-those objects are included in the information printed.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-This command is only available when the POSIX API is configured.
-
-**EXAMPLES:**
-
-The following is an example of how to use the ``task`` on an
-application with four POSIX threads:
-.. code:: c
-
- SHLL \[/] $ pthread
- ID NAME PRI STATE MODES EVENTS WAITID WAITARG NOTES
- ------------------------------------------------------------------------------
- 0b010002 Main 133 READY P:T:nA NONE 43010001 0x7b1148
- 0b010003 ISR 133 Wcvar P:T:nA NONE 43010003 0x7b1148
- 0b01000c 133 READY P:T:nA NONE 33010002 0x7b1148
- 0b01000d 133 Wmutex P:T:nA NONE 33010002 0x7b1148
-
-**CONFIGURATION:**
-
-This command is part of the monitor commands which are always
-available in the shell.
-
-**PROGRAMMING INFORMATION:**
-
-This command is not directly available for invocation.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-Network Commands
-################
-
-Introduction
-============
-
-The RTEMS shell has the following network commands:
-
-- ``netstats`` - obtain network statistics
-
-- ``ifconfig`` - configure a network interface
-
-- ``route`` - show or manipulate the IP routing table
-
-- ``ping`` - ping a host or IP address
-
-Commands
-========
-
-This section details the Network Commands available. A
-subsection is dedicated to each of the commands and
-describes the behavior and configuration of that
-command as well as providing an example usage.
-
-netstats - obtain network statistics
-------------------------------------
-.. index:: netstats
-
-**SYNOPSYS:**
-
-.. code:: c
-
- netstats \[-Aimfpcut]
-
-**DESCRIPTION:**
-
-This command is used to display various types of network statistics. The
-information displayed can be specified using command line arguments in
-various combinations. The arguments are interpreted as follows:
-
-*-A*
- print All statistics
-
-*-i*
- print Inet Routes
-
-*-m*
- print MBUF Statistics
-
-*-f*
- print IF Statistics
-
-*-p*
- print IP Statistics
-
-*-c*
- print ICMP Statistics
-
-*-u*
- print UDP Statistics
-
-*-t*
- print TCP Statistics
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-NONE
-
-**EXAMPLES:**
-
-The following is an example of how to use ``netstats``:
-
-The following is an example of using the ``netstats``
-command to print the IP routing table:
-.. code:: c
-
- [/] $ netstats -i
- Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
- default 192.168.1.14 UGS 0 0 0 eth1
- 192.168.1.0 255.255.255.0 U 0 0 1 eth1
- 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1219 eth1
- 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 840 1202 eth1
- 192.168.1.151 00:1C:23:B2:0F:BB UHL 1 23 1219 eth1
-
-The following is an example of using the ``netstats``
-command to print the MBUF statistics:
-.. code:: c
-
- [/] $ netstats -m
- \************ MBUF STATISTICS \************
- mbufs:2048 clusters: 128 free: 63
- drops: 0 waits: 0 drains: 0
- free:1967 data:79 header:2 socket:0
- pcb:0 rtable:0 htable:0 atable:0
- soname:0 soopts:0 ftable:0 rights:0
- ifaddr:0 control:0 oobdata:0
-
-The following is an example of using the ``netstats``
-command to print the print the interface statistics:
-.. code:: c
-
- [/] $ netstats -f
- \************ INTERFACE STATISTICS \************
- \***** eth1 \*****
- Ethernet Address: 00:04:9F:00:5B:21
- Address:192.168.1.244 Broadcast Address:192.168.1.255 Net mask:255.255.255.0
- Flags: Up Broadcast Running Active Multicast
- Send queue limit:50 length:1 Dropped:0
- Rx Interrupts:889 Not First:0 Not Last:0
- Giant:0 Non-octet:0
- Bad CRC:0 Overrun:0 Collision:0
- Tx Interrupts:867 Deferred:0 Late Collision:0
- Retransmit Limit:0 Underrun:0 Misaligned:0
-
-The following is an example of using the ``netstats``
-command to print the print IP statistics:
-.. code:: c
-
- [/] $ netstats -p
- \************ IP Statistics \************
- total packets received 894
- packets rcvd for unreachable dest 13
- datagrams delivered to upper level 881
- total ip packets generated here 871
-
-The following is an example of using the ``netstats``
-command to print the ICMP statistics:
-.. code:: c
-
- [/] $ netstats -c
- \************ ICMP Statistics \************
- Type 0 sent 843
- number of responses 843
- Type 8 received 843
-
-The following is an example of using the ``netstats``
-command to print the UDP statistics:
-.. code:: c
-
- [/] $ netstats -u
- \************ UDP Statistics \************
-
-The following is an example of using the ``netstats``
-command to print the TCP statistics:
-.. code:: c
-
- [/] $ netstats -t
- \************ TCP Statistics \************
- connections accepted 1
- connections established 1
- segs where we tried to get rtt 34
- times we succeeded 35
- delayed acks sent 2
- total packets sent 37
- data packets sent 35
- data bytes sent 2618
- ack-only packets sent 2
- total packets received 47
- packets received in sequence 12
- bytes received in sequence 307
- rcvd ack packets 35
- bytes acked by rcvd acks 2590
- times hdr predict ok for acks 27
- times hdr predict ok for data pkts 10
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS
-.. index:: CONFIGURE_SHELL_COMMAND_NETSTATS
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_netstats
-
-The ``netstats`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_netstats(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``netstats`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command;
-
-ifconfig - configure a network interface
-----------------------------------------
-.. index:: ifconfig
-
-**SYNOPSYS:**
-
-.. code:: c
-
- ifconfig
- ifconfig interface
- ifconfig interface \[up|down]
- ifconfig interface \[netmask|pointtopoint|broadcast] IP
-
-**DESCRIPTION:**
-
-This command may be used to display information about the
-network interfaces in the system or configure them.
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-Just like its counterpart on GNU/Linux and BSD systems, this command
-is complicated. More example usages would be a welcome submission.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``ifconfig``:
-.. code:: c
-
- ************ INTERFACE STATISTICS \************
- \***** eth1 \*****
- Ethernet Address: 00:04:9F:00:5B:21
- Address:192.168.1.244 Broadcast Address:192.168.1.255 Net mask:255.255.255.0
- Flags: Up Broadcast Running Active Multicast
- Send queue limit:50 length:1 Dropped:0
- Rx Interrupts:5391 Not First:0 Not Last:0
- Giant:0 Non-octet:0
- Bad CRC:0 Overrun:0 Collision:0
- Tx Interrupts:5256 Deferred:0 Late Collision:0
- Retransmit Limit:0 Underrun:0 Misaligned:0
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG
-.. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_ifconfig
-
-The ``ifconfig`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_ifconfig(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``ifconfig`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command;
-
-route - show or manipulate the ip routing table
------------------------------------------------
-.. index:: route
-
-**SYNOPSYS:**
-
-.. code:: c
-
- route \[subcommand] \[args]
-
-**DESCRIPTION:**
-
-This command is used to display and manipulate the routing table.
-When invoked with no arguments, the current routing information is
-displayed. When invoked with the subcommands ``add`` or ``del``,
-then additional arguments must be provided to describe the route.
-
-Command templates include the following:
-.. code:: c
-
- route \[add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS \[netmask MASK]
- route \[add|del] -host IP_ADDRESS gw GATEWAY_ADDRES \[netmask MASK]
-
-When not provided the netmask defaults to ``255.255.255.0``
-
-**EXIT STATUS:**
-
-This command returns 0 on success and non-zero if an error is encountered.
-
-**NOTES:**
-
-Just like its counterpart on GNU/Linux and BSD systems, this command
-is complicated. More example usages would be a welcome submission.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``route`` to display,
-add, and delete a new route:
-.. code:: c
-
- [/] $ route
- Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
- default 192.168.1.14 UGS 0 0 0 eth1
- 192.168.1.0 255.255.255.0 U 0 0 1 eth1
- 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1444 eth1
- 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 10844 1202 eth1
- 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 37 1399 eth1
- \[/] $ route add -net 192.168.3.0 gw 192.168.1.14
- \[/] $ route
- Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
- default 192.168.1.14 UGS 0 0 0 eth1
- 192.168.1.0 255.255.255.0 U 0 0 1 eth1
- 192.168.1.14 00:A0:C8:1C:EE:28 UHL 2 0 1498 eth1
- 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 14937 1202 eth1
- 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 96 1399 eth1
- 192.168.3.0 192.168.1.14 UGS 0 0 0 eth1
- \[/] $ route del -net 192.168.3.0 gw 192.168.1.14
- \[/] $ route
- Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
- default 192.168.1.14 UGS 0 0 0 eth1
- 192.168.1.0 255.255.255.0 U 0 0 1 eth1
- 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1498 eth1
- 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 15945 1202 eth1
- 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 117 1399 eth1
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE
-.. index:: CONFIGURE_SHELL_COMMAND_ROUTE
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_route
-
-The ``route`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_route(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``route`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_ROUTE_Command;
-
-ping - ping a host or IP address
---------------------------------
-.. index:: ping
-
-**SYNOPSYS:**
-
-.. code:: c
-
- ping \[-AaDdfnoQqRrv] \[-c count] \[-G sweepmaxsize] \[-g sweepminsize]
- \[-h sweepincrsize] \[-i wait] \[-l preload] \[-M mask | time] \[-m ttl]
- \[-p pattern] \[-S src_addr] \[-s packetsize] \[-t timeout]
- \[-W waittime] \[-z tos] host
- ping \[-AaDdfLnoQqRrv] \[-c count] \[-I iface] \[-i wait] \[-l preload]
- \[-M mask | time] \[-m ttl] \[-p pattern] \[-S src_addr]
- \[-s packetsize] \[-T ttl] \[-t timeout] \[-W waittime]
- \[-z tos] mcast-group
-
-**DESCRIPTION:**
-
-The ping utility uses the ICMP protocol’s mandatory ECHO_REQUEST
-datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway.
-ECHO_REQUEST datagrams (“pings”) have an IP and ICMP header,
-followed by a “struct timeval” and then an arbitrary number of
-“pad” bytes used to fill out the packet. The options are as
-follows:
-
-*-A*
- Audible. Output a bell (ASCII 0x07) character when no packet is
- received before the next packet is transmitted. To cater for
- round-trip times that are longer than the interval between
- transmissions, further missing packets cause a bell only if the
- maximum number of unreceived packets has increased.
-
-*-a*
- Audible. Include a bell (ASCII 0x07) character in the output when any
- packet is received. This option is ignored if other format options
- are present.
-
-*-c count*
- Stop after sending (and receiving) count ECHO_RESPONSE packets. If
- this option is not specified, ping will operate until interrupted. If
- this option is specified in conjunction with ping sweeps, each sweep
- will consist of count packets.
-
-*-D*
- Set the Don’t Fragment bit.
-
-*-d*
- Set the SO_DEBUG option on the socket being used.
-
-*-f*
- Flood ping. Outputs packets as fast as they come back or one
- hundred times per second, whichever is more. For every ECHO_REQUEST
- sent a period “.” is printed, while for every ECHO_REPLY received a
- backspace is printed. This provides a rapid display of how many
- packets are being dropped. Only the super-user may use this option.
- This can be very hard on a network and should be used with caution.
-
-*-G sweepmaxsize*
- Specify the maximum size of ICMP payload when sending sweeping pings.
- This option is required for ping sweeps.
-
-*-g sweepminsize*
- Specify the size of ICMP payload to start with when sending sweeping
- pings. The default value is 0.
-
-*-h sweepincrsize*
- Specify the number of bytes to increment the size of ICMP payload
- after each sweep when sending sweeping pings. The default value is 1.
-
-*-I iface*
- Source multicast packets with the given interface address. This flag
- only applies if the ping destination is a multicast address.
-
-*-i wait*
- Wait wait seconds between sending each packet. The default is to wait
- for one second between each packet. The wait time may be fractional,
- but only the super-user may specify values less than 1 second. This
- option is incompatible with the -f option.
-
-*-L*
- Suppress loopback of multicast packets. This flag only applies if the
- ping destination is a multicast address.
-
-*-l preload*
- If preload is specified, ping sends that many packets as fast as
- possible before falling into its normal mode of behavior. Only the
- super-user may use this option.
-
-*-M mask | time*
- Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO. For mask, print
- the netmask of the remote machine. Set the net.inet.icmp.maskrepl MIB
- variable to enable ICMP_MASKREPLY. For time, print the origination,
- reception and transmission timestamps.
-
-*-m ttl*
- Set the IP Time To Live for outgoing packets. If not specified, the
- kernel uses the value of the net.inet.ip.ttl MIB variable.
-
-*-n*
- Numeric output only. No attempt will be made to lookup symbolic names
- for host addresses.
-
-*-o*
- Exit successfully after receiving one reply packet.
-
-*-p pattern*
- You may specify up to 16 “pad” bytes to fill out the packet you
- send. This is useful for diagnosing data-dependent problems in a
- network. For example, “-p ff” will cause the sent packet to be
- filled with all ones.
-
-*-Q*
- Somewhat quiet output. Don’t display ICMP error messages that are in
- response to our query messages. Originally, the -v flag was required
- to display such errors, but -v displays all ICMP error messages. On a
- busy machine, this output can be overbear- ing. Without the -Q flag,
- ping prints out any ICMP error mes- sages caused by its own
- ECHO_REQUEST messages.
-
-*-q*
- Quiet output. Nothing is displayed except the summary lines at
- startup time and when finished.
-
-*-R*
- Record route. Includes the RECORD_ROUTE option in the ECHO_REQUEST
- packet and displays the route buffer on returned packets. Note that
- the IP header is only large enough for nine such routes; the
- traceroute(8) command is usually better at determining the route
- packets take to a particular destination. If more routes come back
- than should, such as due to an illegal spoofed packet, ping will print
- the route list and then truncate it at the correct spot. Many hosts
- ignore or discard the RECORD_ROUTE option.
-
-*-r*
- Bypass the normal routing tables and send directly to a host on an
- attached network. If the host is not on a directly-attached network,
- an error is returned. This option can be used to ping a local host
- through an interface that has no route through it (e.g., after the
- interface was dropped).
-
-*-S src_addr*
- Use the following IP address as the source address in outgoing
- packets. On hosts with more than one IP address, this option can be
- used to force the source address to be something other than the IP
- address of the interface the probe packet is sent on. If the IP
- address is not one of this machine’s interface addresses, an error is
- returned and nothing is sent.
-
-*-s packetsize*
- Specify the number of data bytes to be sent. The default is 56, which
- translates into 64 ICMP data bytes when combined with the 8 bytes of
- ICMP header data. Only the super-user may specify val- ues more than
- default. This option cannot be used with ping sweeps.
-
-*-T ttl*
- Set the IP Time To Live for multicasted packets. This flag only
- applies if the ping destination is a multicast address.
-
-*-t timeout*
- Specify a timeout, in seconds, before ping exits regardless of how
- many packets have been received.
-
-*-v*
- Verbose output. ICMP packets other than ECHO_RESPONSE that are
- received are listed.
-
-*-W waittime*
- Time in milliseconds to wait for a reply for each packet sent. If a
- reply arrives later, the packet is not printed as replied, but
- considered as replied when calculating statistics.
-
-*-z tos*
- Use the specified type of service.
-
-**EXIT STATUS:**
-
-The ping utility exits with one of the following values:
-
-0 At least one response was heard from the specified host.
-
-2 The transmission was successful but no responses were
-received.
-
-any other value an error occurred. These values are defined in
-<sysexits.h>.
-
-**NOTES:**
-
-When using ping for fault isolation, it should first be run on the
-local host, to verify that the local network interface is up and
-running. Then, hosts and gateways further and further away should be
-“pinged”. Round-trip times and packet loss statistics are computed.
-If duplicate packets are received, they are not included in the packet
-loss calculation, although the round trip time of these packets is
-used in calculating the round-trip time statistics. When the
-specified number of packets have been sent a brief summary is
-displayed, showing the number of packets sent and received, and the
-minimum, mean, maximum, and standard deviation of the round-trip
-times.
-
-This program is intended for use in network testing, measurement and
-management. Because of the load it can impose on the network, it is
-unwise to use ping during normal operations or from automated scripts.
-
-**EXAMPLES:**
-
-The following is an example of how to use ``oing`` to ping:
-.. code:: c
-
- [/] # ping 10.10.10.1
- PING 10.10.10.1 (10.10.10.1): 56 data bytes
- 64 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms
- 64 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms
- 64 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms
- 64 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms
- 64 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms
- --- 10.10.10.1 ping statistics ---
- 5 packets transmitted, 5 packets received, 0.0% packet loss
- round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms
- \[/] # ping -f -c 10000 10.10.10.1
- PING 10.10.10.1 (10.10.10.1): 56 data bytes
- .
- --- 10.10.10.1 ping statistics ---
- 10000 packets transmitted, 10000 packets received, 0.0% packet loss
- round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms
-
-**CONFIGURATION:**
-
-.. index:: CONFIGURE_SHELL_NO_COMMAND_PING
-.. index:: CONFIGURE_SHELL_COMMAND_PING
-
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PING`` to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_PING`` when all
-shell commands have been configured.
-
-**PROGRAMMING INFORMATION:**
-
-.. index:: rtems_shell_rtems_main_ping
-
-The ``ping`` is implemented by a C language function
-which has the following prototype:
-.. code:: c
-
- int rtems_shell_rtems_main_ping(
- int argc,
- char \**argv
- );
-
-The configuration structure for the ``ping`` has the
-following prototype:
-.. code:: c
-
- extern rtems_shell_cmd_t rtems_shell_PING_Command;
-
-Function and Variable Index
-###########################
-
-.. COMMENT: There are currently no Command and Variable Index entries.
-
-Concept Index
-#############
-
-Command Index
-#############
-