: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:ref:`Configuring a System <Configuring-a-System>` for more details.
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 :ref:`Time and Date Data Structures <Clock-Manager-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 :ref:`Fatal Error Manager Announcing a Fatal Error <Fatal-Error-Manager-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 :ref:`Linker
Sets <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 :ref:`Configuring a System <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
|