rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 19:17:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

C user guide clean up. Up to timer manager.

Browse Source
This commit is contained in:
Chris Johns 2016-01-24 21:37:53 +11:00 committed by Amar Takhar
parent 0f5ccd4d6d
commit b8d3f6b3b7
14 changed files with 3433 additions and 3339 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

568
c_user/clock_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Clock Manager Clock Manager
############# #############
@ -10,37 +14,37 @@ The clock manager provides support for time of day
and other time related capabilities. The directives provided by and other time related capabilities. The directives provided by
the clock manager are: the clock manager are:
- ``rtems_clock_set`` - Set date and time - rtems_clock_set_ - Set date and time
- ``rtems_clock_get`` - Get date and time information - rtems_clock_get_ - Get date and time information
- ``rtems_clock_get_tod`` - Get date and time in TOD format - rtems_clock_get_tod_ - Get date and time in TOD format
- ``rtems_clock_get_tod_timeval`` - Get date and time in timeval format - rtems_clock_get_tod_timeval_ - Get date and time in timeval format
- ``rtems_clock_get_seconds_since_epoch`` - Get seconds since epoch - rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch
- ``rtems_clock_get_ticks_per_second`` - Get ticks per second - rtems_clock_get_ticks_per_second_ - Get ticks per second
- ``rtems_clock_get_ticks_since_boot`` - Get current ticks counter value - rtems_clock_get_ticks_since_boot_ - Get current ticks counter value
- ``rtems_clock_tick_later`` - Get tick value in the future - rtems_clock_tick_later_ - Get tick value in the future
- ``rtems_clock_tick_later_usec`` - Get tick value in the future in microseconds - rtems_clock_tick_later_usec_ - Get tick value in the future in microseconds
- ``rtems_clock_tick_before`` - Is tick value is before a point in time - rtems_clock_tick_before_ - Is tick value is before a point in time
- ``rtems_clock_get_uptime`` - Get time since boot - rtems_clock_get_uptime_ - Get time since boot
- ``rtems_clock_get_uptime_timeval`` - Get time since boot in timeval format - rtems_clock_get_uptime_timeval_ - Get time since boot in timeval format
- ``rtems_clock_get_uptime_seconds`` - Get seconds since boot - rtems_clock_get_uptime_seconds_ - Get seconds since boot
- ``rtems_clock_get_uptime_nanoseconds`` - Get nanoseconds since boot - rtems_clock_get_uptime_nanoseconds_ - Get nanoseconds since boot
- ``rtems_clock_set_nanoseconds_extension`` - Install the nanoseconds since last tick handler - rtems_clock_set_nanoseconds_extension_ - Install the nanoseconds since last tick handler
- ``rtems_clock_tick`` - Announce a clock tick - rtems_clock_tick_ - Announce a clock tick
Background Background
========== ==========
@ -48,93 +52,89 @@ Background
Required Support Required Support
---------------- ----------------
For the features provided by the clock manager to be For the features provided by the clock manager to be utilized, periodic timer
utilized, periodic timer interrupts are required. Therefore, a interrupts are required. Therefore, a real-time clock or hardware timer is
real-time clock or hardware timer is necessary to create the necessary to create the timer interrupts. The ``rtems_clock_tick`` directive
timer interrupts. The ``rtems_clock_tick`` is normally called by the timer ISR to announce to RTEMS that a system clock
directive is normally called tick has occurred. Elapsed time is measured in ticks. A tick is defined to be
by the timer ISR to announce to RTEMS that a system clock tick an integral number of microseconds which is specified by the user in the
has occurred. Elapsed time is measured in ticks. A tick is Configuration Table.
defined to be an integral number of microseconds which is
specified by the user in the Configuration Table.
Time and Date Data Structures Time and Date Data Structures
----------------------------- -----------------------------
The clock facilities of the clock manager operate The clock facilities of the clock manager operate upon calendar time. These
upon calendar time. These directives utilize the following date directives utilize the following date and time structure for the native time
and time structure for the native time and date format: and date format:
.. index:: rtems_time_of_day .. index:: rtems_time_of_day
.. code:: c .. code:: c
struct rtems_tod_control { struct rtems_tod_control {
uint32_t year; /* greater than 1987 \*/ uint32_t year; /* greater than 1987 */
uint32_t month; /* 1 - 12 \*/ uint32_t month; /* 1 - 12 */
uint32_t day; /* 1 - 31 \*/ uint32_t day; /* 1 - 31 */
uint32_t hour; /* 0 - 23 \*/ uint32_t hour; /* 0 - 23 */
uint32_t minute; /* 0 - 59 \*/ uint32_t minute; /* 0 - 59 */
uint32_t second; /* 0 - 59 \*/ uint32_t second; /* 0 - 59 */
uint32_t ticks; /* elapsed between seconds \*/ uint32_t ticks; /* elapsed between seconds */
}; };
typedef struct rtems_tod_control rtems_time_of_day; typedef struct rtems_tod_control rtems_time_of_day;
The native date and time format is the only format The native date and time format is the only format supported when setting the
supported when setting the system date and time using the``rtems_clock_set`` directive. Some applications system date and time using the ``rtems_clock_set`` directive. Some
expect to operate on a "UNIX-style" date and time data structure. The``rtems_clock_get_tod_timeval`` always returns applications expect to operate on a *UNIX-style* date and time data structure.
the date and time in ``struct timeval`` format. The``rtems_clock_get`` directive can optionally return The ``rtems_clock_get_tod_timeval`` always returns the date and time in
the current date and time in this format. ``struct timeval`` format. The ``rtems_clock_get`` directive can optionally
return the current date and time in this format.
The ``struct timeval`` data structure has two fields: ``tv_sec`` The ``struct timeval`` data structure has two fields: ``tv_sec`` and
and ``tv_usec`` which are seconds and microseconds, respectively. ``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec``
The ``tv_sec`` field in this data structure is the number of seconds field in this data structure is the number of seconds since the POSIX epoch of
since the POSIX epoch of January 1, 1970 but will never be prior to *January 1, 1970* but will never be prior to the RTEMS epoch of *January 1,
the RTEMS epoch of January 1, 1988. 1988*.
Clock Tick and Timeslicing Clock Tick and Timeslicing
-------------------------- --------------------------
.. index:: timeslicing .. index:: timeslicing
Timeslicing is a task scheduling discipline in which Timeslicing is a task scheduling discipline in which tasks of equal priority
tasks of equal priority are executed for a specific period of are executed for a specific period of time before control of the CPU is passed
time before control of the CPU is passed to another task. It is to another task. It is also sometimes referred to as the automatic round-robin
also sometimes referred to as the automatic round-robin scheduling algorithm. The length of time allocated to each task is known as
scheduling algorithm. The length of time allocated to each task the quantum or timeslice.
is known as the quantum or timeslice.
The system's timeslice is defined as an integral The system's timeslice is defined as an integral number of ticks, and is
number of ticks, and is specified in the Configuration Table. specified in the Configuration Table. The timeslice is defined for the entire
The timeslice is defined for the entire system of tasks, but system of tasks, but timeslicing is enabled and disabled on a per task basis.
timeslicing is enabled and disabled on a per task basis.
The ``rtems_clock_tick`` The ``rtems_clock_tick`` directive implements timeslicing by decrementing the
directive implements timeslicing by running task's time-remaining counter when both timeslicing and preemption are
decrementing the running task's time-remaining counter when both enabled. If the task's timeslice has expired, then that task will be preempted
timeslicing and preemption are enabled. If the task's timeslice if there exists a ready task of equal priority.
has expired, then that task will be preempted if there exists a
ready task of equal priority.
Delays Delays
------ ------
.. index:: delays .. index:: delays
A sleep timer allows a task to delay for a given A sleep timer allows a task to delay for a given interval or up until a given
interval or up until a given time, and then wake and continue time, and then wake and continue execution. This type of timer is created
execution. This type of timer is created automatically by the``rtems_task_wake_after`` automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when``
and ``rtems_task_wake_when`` directives and, as a result, directives and, as a result, does not have an RTEMS ID. Once activated, a
does not have an RTEMS ID. Once activated, a sleep timer cannot sleep timer cannot be explicitly deleted. Each task may activate one and only
be explicitly deleted. Each task may activate one and only one one sleep timer at a time.
sleep timer at a time.
Timeouts Timeouts
-------- --------
.. index:: timeouts .. index:: timeouts
Timeouts are a special type of timer automatically Timeouts are a special type of timer automatically created when the timeout
created when the timeout option is used on the``rtems_message_queue_receive``,``rtems_event_receive``,``rtems_semaphore_obtain`` and``rtems_region_get_segment`` directives. option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``,
Each task may have one and only one timeout active at a time. ``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each
When a timeout expires, it unblocks the task with a timeout status code. task may have one and only one timeout active at a time. When a timeout
expires, it unblocks the task with a timeout status code.
Operations Operations
========== ==========
@ -142,71 +142,67 @@ Operations
Announcing a Tick Announcing a Tick
----------------- -----------------
RTEMS provides the ``rtems_clock_tick`` directive which is RTEMS provides the ``rtems_clock_tick`` directive which is called from the
called from the user's real-time clock ISR to inform RTEMS that user's real-time clock ISR to inform RTEMS that a tick has elapsed. The tick
a tick has elapsed. The tick frequency value, defined in frequency value, defined in microseconds, is a configuration parameter found in
microseconds, is a configuration parameter found in the the Configuration Table. RTEMS divides one million microseconds (one second)
Configuration Table. RTEMS divides one million microseconds by the number of microseconds per tick to determine the number of calls to
(one second) by the number of microseconds per tick to determine the``rtems_clock_tick`` directive per second. The frequency of
the number of calls to the``rtems_clock_tick`` directive per second. The ``rtems_clock_tick`` calls determines the resolution (granularity) for all time
frequency of ``rtems_clock_tick`` dependent RTEMS actions. For example, calling ``rtems_clock_tick`` ten times
calls determines the resolution per second yields a higher resolution than calling ``rtems_clock_tick`` two
(granularity) for all time dependent RTEMS actions. For times per second. The ``rtems_clock_tick`` directive is responsible for
example, calling ``rtems_clock_tick`` maintaining both calendar time and the dynamic set of timers.
ten times per second yields a higher
resolution than calling ``rtems_clock_tick``
two times per second. The ``rtems_clock_tick``
directive is responsible for maintaining both
calendar time and the dynamic set of timers.
Setting the Time Setting the Time
---------------- ----------------
The ``rtems_clock_set`` directive allows a task or an ISR to The ``rtems_clock_set`` directive allows a task or an ISR to set the date and
set the date and time maintained by RTEMS. If setting the date time maintained by RTEMS. If setting the date and time causes any outstanding
and time causes any outstanding timers to pass their deadline, timers to pass their deadline, then the expired timers will be fired during the
then the expired timers will be fired during the invocation of invocation of the ``rtems_clock_set`` directive.
the ``rtems_clock_set`` directive.
Obtaining the Time Obtaining the Time
------------------ ------------------
The ``rtems_clock_get`` directive allows a task or an ISR to The ``rtems_clock_get`` directive allows a task or an ISR to obtain the current
obtain the current date and time or date and time related date and time or date and time related information. The current date and time
information. The current date and time can be returned in can be returned in either native or *UNIX-style* format. Additionally, the
either native or UNIX-style format. Additionally, the application can obtain date and time related information such as the number of
application can obtain date and time related information such as seconds since the RTEMS epoch, the number of ticks since the executive was
the number of seconds since the RTEMS epoch, the number of ticks initialized, and the number of ticks per second. The information returned by
since the executive was initialized, and the number of ticks per the``rtems_clock_get`` directive is dependent on the option selected by the
second. The information returned by the``rtems_clock_get`` directive is caller. This is specified using one of the following constants associated with
dependent on the option selected by the caller. This the enumerated type ``rtems_clock_get_options``:
is specified using one of the following constants
associated with the enumerated type``rtems_clock_get_options``:.. index:: rtems_clock_get_options
- ``RTEMS_CLOCK_GET_TOD`` - obtain native style date and time .. index:: rtems_clock_get_options
- ``RTEMS_CLOCK_GET_TIME_VALUE`` - obtain UNIX-style ``RTEMS_CLOCK_GET_TOD``
date and time obtain native style date and time
- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - obtain number of ticks ``RTEMS_CLOCK_GET_TIME_VALUE``
since RTEMS was initialized obtain *UNIX-style* date and time
- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - obtain number ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``
of seconds since RTEMS epoch obtain number of ticks since RTEMS was initialized
- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - obtain number of clock ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``
ticks per second obtain number of seconds since RTEMS epoch
Calendar time operations will return an error code if ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``
invoked before the date and time have been set. obtain number of clock ticks per second
Calendar time operations will return an error code if invoked before the date
and time have been set.
Directives Directives
========== ==========
This section details the clock manager's directives. This section details the clock manager's directives. A subsection is dedicated
A subsection is dedicated to each of this manager's directives to each of this manager's directives and describes the calling sequence,
and describes the calling sequence, related constants, usage, related constants, usage, and status codes.
and status codes.
.. _rtems_clock_set:
CLOCK_SET - Set date and time CLOCK_SET - Set date and time
----------------------------- -----------------------------
@ -220,42 +216,51 @@ CLOCK_SET - Set date and time
.. code:: c .. code:: c
rtems_status_code rtems_clock_set( rtems_status_code rtems_clock_set(
rtems_time_of_day \*time_buffer rtems_time_of_day *time_buffer
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - date and time set successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL date and time set successfully
``RTEMS_INVALID_CLOCK`` - invalid time of day
``RTEMS_INVALID_ADDRESS``
``time_buffer`` is NULL
``RTEMS_INVALID_CLOCK``
invalid time of day
**DESCRIPTION:** **DESCRIPTION:**
This directive sets the system date and time. The This directive sets the system date and time. The date, time, and ticks in the
date, time, and ticks in the time_buffer structure are all time_buffer structure are all range-checked, and an error is returned if any
range-checked, and an error is returned if any one is out of its one is out of its valid range.
valid range.
**NOTES:** **NOTES:**
Years before 1988 are invalid. Years before 1988 are invalid.
The system date and time are based on the configured The system date and time are based on the configured tick rate (number of
tick rate (number of microseconds in a tick). microseconds in a tick).
Setting the time forward may cause a higher priority Setting the time forward may cause a higher priority task, blocked waiting on a
task, blocked waiting on a specific time, to be made ready. In specific time, to be made ready. In this case, the calling task will be
this case, the calling task will be preempted after the next preempted after the next clock tick.
clock tick.
Re-initializing RTEMS causes the system date and time Re-initializing RTEMS causes the system date and time to be reset to an
to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize uninitialized state. Another call to ``rtems_clock_set`` is required to
the system date and time to application specific specifications. re-initialize the system date and time to application specific specifications.
.. _rtems_clock_get:
CLOCK_GET - Get date and time information CLOCK_GET - Get date and time information
----------------------------------------- -----------------------------------------
.. index:: obtain the time of day .. index:: obtain the time of day
.. warning::
This directive is deprecated and will be removed.
**CALLING SEQUENCE:** **CALLING SEQUENCE:**
.. index:: rtems_clock_get .. index:: rtems_clock_get
@ -263,49 +268,62 @@ CLOCK_GET - Get date and time information
.. code:: c .. code:: c
rtems_status_code rtems_clock_get( rtems_status_code rtems_clock_get(
rtems_clock_get_options option, rtems_clock_get_options option,
void \*time_buffer void *time_buffer
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - current time obtained successfully ``RTEMS_SUCCESSFUL``
``RTEMS_NOT_DEFINED`` - system date and time is not set current time obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
``RTEMS_NOT_DEFINED``
system date and time is not set
``RTEMS_INVALID_ADDRESS``
``time_buffer`` is NULL
**DESCRIPTION:** **DESCRIPTION:**
This directive is deprecated. This directive obtains the system date and time. If the caller is attempting
to obtain the date and time (i.e. option is set to either
``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or
``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with a
previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
code is returned. The caller can always obtain the number of ticks per second
(option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of ticks since
the executive was initialized option is ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
This directive obtains the system date and time. If The ``option`` argument may taken on any value of the enumerated type
the caller is attempting to obtain the date and time (i.e. ``rtems_clock_get_options``. The data type expected for``time_buffer`` is
option is set to either ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``,``RTEMS_CLOCK_GET_TOD``, or``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time based on the value of ``option`` as indicated below:
has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
The caller can always obtain the number of ticks per second (option is``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of
ticks since the executive was initialized option is``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
The ``option`` argument may taken on any value of the enumerated .. index:: rtems_clock_get_options
type ``rtems_clock_get_options``. The data type expected for``time_buffer`` is based on the value of ``option`` as
indicated below:.. index:: rtems_clock_get_options
- ``RTEMS_CLOCK_GET_TOD`` - (rtems_time_of_day \*) +-----------------------------------------+---------------------------+
| Option | Return type |
- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - (rtems_interval \*) +=========================================+===========================+
| ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` |
- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - (rtems_interval \*) +-----------------------------------------+---------------------------+
| ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` |
- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - (rtems_interval \*) +-----------------------------------------+---------------------------+
| ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` |
- ``RTEMS_CLOCK_GET_TIME_VALUE`` - (struct timeval \*) +-----------------------------------------+---------------------------+
|``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` |
+-----------------------------------------+---------------------------+
| ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` |
+-----------------------------------------+---------------------------+
**NOTES:** **NOTES:**
This directive is callable from an ISR. This directive is callable from an ISR.
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted. Re-initializing RTEMS causes the system date and Re-initializing RTEMS causes the system date and time to be reset to an
time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the uninitialized state. Another call to ``rtems_clock_set`` is required to
system date and time to application specific specifications. re-initialize the system date and time to application specific specifications.
.. _rtems_clock_get_tod:
CLOCK_GET_TOD - Get date and time in TOD format CLOCK_GET_TOD - Get date and time in TOD format
----------------------------------------------- -----------------------------------------------
@ -318,28 +336,36 @@ CLOCK_GET_TOD - Get date and time in TOD format
.. code:: c .. code:: c
rtems_status_code rtems_clock_get_tod( rtems_status_code rtems_clock_get_tod(
rtems_time_of_day \*time_buffer rtems_time_of_day *time_buffer
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - current time obtained successfully ``RTEMS_SUCCESSFUL``
``RTEMS_NOT_DEFINED`` - system date and time is not set current time obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
``RTEMS_NOT_DEFINED``
system date and time is not set
``RTEMS_INVALID_ADDRESS``
``time_buffer`` is NULL
**DESCRIPTION:** **DESCRIPTION:**
This directive obtains the system date and time. If the date and time This directive obtains the system date and time. If the date and time has not
has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. been set with a previous call to ``rtems_clock_set``, then the
``RTEMS_NOT_DEFINED`` status code is returned.
**NOTES:** **NOTES:**
This directive is callable from an ISR. This directive is callable from an ISR.
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted. Re-initializing RTEMS causes the system date and Re-initializing RTEMS causes the system date and time to be reset to an
time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the uninitialized state. Another call to ``rtems_clock_set`` is required to
system date and time to application specific specifications. re-initialize the system date and time to application specific specifications.
.. _rtems_clock_get_tod_timeval:
CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
----------------------------------------------------------- -----------------------------------------------------------
@ -351,29 +377,37 @@ CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
.. code:: c .. code:: c
rtems_status_code rtems_clock_get_tod( rtems_status_code rtems_clock_get_tod_interval(
struct timeval \*time struct timeval *time
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - current time obtained successfully ``RTEMS_SUCCESSFUL``
``RTEMS_NOT_DEFINED`` - system date and time is not set current time obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``time`` is NULL
``RTEMS_NOT_DEFINED``
system date and time is not set
``RTEMS_INVALID_ADDRESS``
``time`` is NULL
**DESCRIPTION:** **DESCRIPTION:**
This directive obtains the system date and time in POSIX``struct timeval`` format. If the date and time This directive obtains the system date and time in POSIX ``struct timeval``
has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. format. If the date and time has not been set with a previous call to
``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is returned.
**NOTES:** **NOTES:**
This directive is callable from an ISR. This directive is callable from an ISR.
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted. Re-initializing RTEMS causes the system date and Re-initializing RTEMS causes the system date and time to be reset to an
time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the uninitialized state. Another call to ``rtems_clock_set`` is required to
system date and time to application specific specifications. re-initialize the system date and time to application specific specifications.
.. _rtems_clock_get_seconds_since_epoch:
CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
------------------------------------------------------- -------------------------------------------------------
@ -386,29 +420,37 @@ CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
.. code:: c .. code:: c
rtems_status_code rtems_clock_get_seconds_since_epoch( rtems_status_code rtems_clock_get_seconds_since_epoch(
rtems_interval \*the_interval rtems_interval *the_interval
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - current time obtained successfully ``RTEMS_SUCCESSFUL``
``RTEMS_NOT_DEFINED`` - system date and time is not set current time obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``the_interval`` is NULL
``RTEMS_NOT_DEFINED``
system date and time is not set
``RTEMS_INVALID_ADDRESS``
``the_interval`` is NULL
**DESCRIPTION:** **DESCRIPTION:**
This directive returns the number of seconds since the RTEMS This directive returns the number of seconds since the RTEMS epoch and the
epoch and the current system date and time. If the date and time current system date and time. If the date and time has not been set with a
has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
code is returned.
**NOTES:** **NOTES:**
This directive is callable from an ISR. This directive is callable from an ISR.
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted. Re-initializing RTEMS causes the system date and Re-initializing RTEMS causes the system date and time to be reset to an
time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the uninitialized state. Another call to ``rtems_clock_set`` is required to
system date and time to application specific specifications. re-initialize the system date and time to application specific specifications.
.. _rtems_clock_get_ticks_per_second:
CLOCK_GET_TICKS_PER_SECOND - Get ticks per second CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
------------------------------------------------- -------------------------------------------------
@ -428,9 +470,8 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive returns the number of clock ticks per second. This This directive returns the number of clock ticks per second. This is strictly
is strictly based upon the microseconds per clock tick that the based upon the microseconds per clock tick that the application has configured.
application has configured.
**NOTES:** **NOTES:**
@ -438,6 +479,8 @@ This directive is callable from an ISR.
This directive will not cause the running task to be preempted. This directive will not cause the running task to be preempted.
.. _rtems_clock_get_ticks_since_boot:
CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
------------------------------------------------------------ ------------------------------------------------------------
.. index:: obtain ticks since boot .. index:: obtain ticks since boot
@ -459,8 +502,9 @@ NONE
This directive returns the current tick counter value. With a 1ms clock tick, This directive returns the current tick counter value. With a 1ms clock tick,
this counter overflows after 50 days since boot. This is the historical this counter overflows after 50 days since boot. This is the historical
measure of uptime in an RTEMS system. The newer service``rtems_clock_get_uptime`` is another and potentially more measure of uptime in an RTEMS system. The newer service
accurate way of obtaining similar information. ``rtems_clock_get_uptime`` is another and potentially more accurate way of
obtaining similar information.
**NOTES:** **NOTES:**
@ -468,6 +512,8 @@ This directive is callable from an ISR.
This directive will not cause the running task to be preempted. This directive will not cause the running task to be preempted.
.. _rtems_clock_tick_later:
CLOCK_TICK_LATER - Get tick value in the future CLOCK_TICK_LATER - Get tick value in the future
----------------------------------------------- -----------------------------------------------
@ -478,7 +524,7 @@ CLOCK_TICK_LATER - Get tick value in the future
.. code:: c .. code:: c
rtems_interval rtems_clock_tick_later( rtems_interval rtems_clock_tick_later(
rtems_interval delta rtems_interval delta
); );
**DESCRIPTION:** **DESCRIPTION:**
@ -491,6 +537,8 @@ This directive is callable from an ISR.
This directive will not cause the running task to be preempted. This directive will not cause the running task to be preempted.
.. _rtems_clock_tick_later_usec:
CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
-------------------------------------------------------------------- --------------------------------------------------------------------
@ -501,7 +549,7 @@ CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
.. code:: c .. code:: c
rtems_interval rtems_clock_tick_later_usec( rtems_interval rtems_clock_tick_later_usec(
rtems_interval delta_in_usec rtems_interval delta_in_usec
); );
**DESCRIPTION:** **DESCRIPTION:**
@ -514,6 +562,8 @@ This directive is callable from an ISR.
This directive will not cause the running task to be preempted. This directive will not cause the running task to be preempted.
.. _rtems_clock_tick_before:
CLOCK_TICK_BEFORE - Is tick value is before a point in time CLOCK_TICK_BEFORE - Is tick value is before a point in time
----------------------------------------------------------- -----------------------------------------------------------
@ -524,7 +574,7 @@ CLOCK_TICK_BEFORE - Is tick value is before a point in time
.. code:: c .. code:: c
rtems_interval rtems_clock_tick_before( rtems_interval rtems_clock_tick_before(
rtems_interval tick rtems_interval tick
); );
**DESCRIPTION:** **DESCRIPTION:**
@ -544,15 +594,17 @@ This directive will not cause the running task to be preempted.
status busy( void ) status busy( void )
{ {
rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
do { do {
if ( ok() ) { if ( ok() ) {
return success; return success;
} }
} while ( rtems_clock_tick_before( timeout ) ); } while ( rtems_clock_tick_before( timeout ) );
return timeout; return timeout;
} }
.. _rtems_clock_get_uptime:
CLOCK_GET_UPTIME - Get the time since boot CLOCK_GET_UPTIME - Get the time since boot
------------------------------------------ ------------------------------------------
.. index:: clock get uptime .. index:: clock get uptime
@ -565,28 +617,32 @@ CLOCK_GET_UPTIME - Get the time since boot
.. code:: c .. code:: c
rtems_status_code rtems_clock_get_uptime( rtems_status_code rtems_clock_get_uptime(
struct timespec \*uptime struct timespec *uptime
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - clock tick processed successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL clock tick processed successfully
``RTEMS_INVALID_ADDRESS``
``time_buffer`` is NULL
**DESCRIPTION:** **DESCRIPTION:**
This directive returns the seconds and nanoseconds since the This directive returns the seconds and nanoseconds since the system was booted.
system was booted. If the BSP supports nanosecond clock If the BSP supports nanosecond clock accuracy, the time reported will probably
accuracy, the time reported will probably be different on every be different on every call.
call.
**NOTES:** **NOTES:**
This directive may be called from an ISR. This directive may be called from an ISR.
.. _rtems_clock_get_uptime_timeval:
CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
-------------------------------------------------------------------- --------------------------------------------------------------------
.. index:: clock get uptime .. index:: clock get uptime interval
.. index:: uptime .. index:: uptime
**CALLING SEQUENCE:** **CALLING SEQUENCE:**
@ -596,7 +652,7 @@ CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
.. code:: c .. code:: c
void rtems_clock_get_uptime_timeval( void rtems_clock_get_uptime_timeval(
struct timeval \*uptime struct timeval *uptime
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -605,18 +661,19 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive returns the seconds and microseconds since the This directive returns the seconds and microseconds since the system was
system was booted. If the BSP supports nanosecond clock booted. If the BSP supports nanosecond clock accuracy, the time reported will
accuracy, the time reported will probably be different on every probably be different on every call.
call.
**NOTES:** **NOTES:**
This directive may be called from an ISR. This directive may be called from an ISR.
.. _rtems_clock_get_uptime_seconds:
CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
----------------------------------------------------- -----------------------------------------------------
.. index:: clock get uptime .. index:: clock get uptime seconds
.. index:: uptime .. index:: uptime
**CALLING SEQUENCE:** **CALLING SEQUENCE:**
@ -639,6 +696,8 @@ This directive returns the seconds since the system was booted.
This directive may be called from an ISR. This directive may be called from an ISR.
.. _rtems_clock_get_uptime_nanoseconds:
CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
------------------------------------------------------------- -------------------------------------------------------------
.. index:: clock get nanoseconds uptime .. index:: clock get nanoseconds uptime
@ -664,6 +723,8 @@ This directive returns the nanoseconds since the system was booted.
This directive may be called from an ISR. This directive may be called from an ISR.
.. _rtems_clock_set_nanoseconds_extension:
CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
--------------------------------------------------------------------------------- ---------------------------------------------------------------------------------
.. index:: clock set nanoseconds extension .. index:: clock set nanoseconds extension
@ -677,32 +738,37 @@ CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handle
.. code:: c .. code:: c
rtems_status_code rtems_clock_set_nanoseconds_extension( rtems_status_code rtems_clock_set_nanoseconds_extension(
rtems_nanoseconds_extension_routine routine rtems_nanoseconds_extension_routine routine
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - clock tick processed successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL clock tick processed successfully
``RTEMS_INVALID_ADDRESS``
``time_buffer`` is NULL
**DESCRIPTION:** **DESCRIPTION:**
This directive is used by the Clock device driver to install the``routine`` which will be invoked by the internal RTEMS method used to This directive is used by the Clock device driver to install the ``routine``
obtain a highly accurate time of day. It is usually called during which will be invoked by the internal RTEMS method used to obtain a highly
the initialization of the driver. accurate time of day. It is usually called during the initialization of the
driver.
When the ``routine`` is invoked, it will determine the number of When the ``routine`` is invoked, it will determine the number of nanoseconds
nanoseconds which have elapsed since the last invocation of which have elapsed since the last invocation of the ``rtems_clock_tick``
the ``rtems_clock_tick`` directive. It should do directive. It should do this as quickly as possible with as little impact as
this as quickly as possible with as little impact as possible possible on the device used as a clock source.
on the device used as a clock source.
**NOTES:** **NOTES:**
This directive may be called from an ISR. This directive may be called from an ISR.
This directive is called as part of every service to obtain the This directive is called as part of every service to obtain the current date
current date and time as well as timestamps. and time as well as timestamps.
.. _rtems_clock_tick:
CLOCK_TICK - Announce a clock tick CLOCK_TICK - Announce a clock tick
---------------------------------- ----------------------------------
@ -718,29 +784,21 @@ CLOCK_TICK - Announce a clock tick
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - clock tick processed successfully ``RTEMS_SUCCESSFUL``
clock tick processed successfully
**DESCRIPTION:** **DESCRIPTION:**
This directive announces to RTEMS that a system clock This directive announces to RTEMS that a system clock tick has occurred. The
tick has occurred. The directive is usually called from the directive is usually called from the timer interrupt ISR of the local
timer interrupt ISR of the local processor. This directive processor. This directive maintains the system date and time, decrements
maintains the system date and time, decrements timers for timers for delayed tasks, timeouts, rate monotonic periods, and implements
delayed tasks, timeouts, rate monotonic periods, and implements
timeslicing. timeslicing.
**NOTES:** **NOTES:**
This directive is typically called from an ISR. This directive is typically called from an ISR.
The ``microseconds_per_tick`` and ``ticks_per_timeslice`` The ``microseconds_per_tick`` and ``ticks_per_timeslice`` parameters in the
parameters in the Configuration Table contain the number of Configuration Table contain the number of microseconds per tick and number of
microseconds per tick and number of ticks per timeslice, ticks per timeslice, respectively.
respectively.
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

260
c_user/initialization.rst
View File

@ -1,16 +1,19 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Initialization Manager Initialization Manager
###################### ######################
Introduction Introduction
============ ============
The Initialization Manager is responsible for The Initialization Manager is responsible for initiating and shutting down
initiating and shutting down RTEMS. Initiating RTEMS involves RTEMS. Initiating RTEMS involves creating and starting all configured
creating and starting all configured initialization tasks, and initialization tasks, and for invoking the initialization routine for each
for invoking the initialization routine for each user-supplied user-supplied device driver. In a multiprocessor configuration, this manager
device driver. In a multiprocessor configuration, this manager also initializes the interprocessor communications layer. The directives
also initializes the interprocessor communications layer. The provided by the Initialization Manager are:
directives provided by the Initialization Manager are:
- ``rtems_initialize_executive`` - Initialize RTEMS - ``rtems_initialize_executive`` - Initialize RTEMS
@ -23,97 +26,85 @@ Initialization Tasks
-------------------- --------------------
.. index:: initialization tasks .. index:: initialization tasks
Initialization task(s) are the mechanism by which Initialization task(s) are the mechanism by which RTEMS transfers initial
RTEMS transfers initial control to the user's application. control to the user's application. Initialization tasks differ from other
Initialization tasks differ from other application tasks in that application tasks in that they are defined in the User Initialization Tasks
they are defined in the User Initialization Tasks Table and Table and automatically created and started by RTEMS as part of its
automatically created and started by RTEMS as part of its initialization sequence. Since the initialization tasks are scheduled using
initialization sequence. Since the initialization tasks are the same algorithm as all other RTEMS tasks, they must be configured at a
scheduled using the same algorithm as all other RTEMS tasks, priority and mode which will ensure that they will complete execution before
they must be configured at a priority and mode which will ensure other application tasks execute. Although there is no upper limit on the
that they will complete execution before other application tasks number of initialization tasks, an application is required to define at least
execute. Although there is no upper limit on the number of one.
initialization tasks, an application is required to define at
least one.
A typical initialization task will create and start A typical initialization task will create and start the static set of
the static set of application tasks. It may also create any application tasks. It may also create any other objects used by the
other objects used by the application. Initialization tasks application. Initialization tasks which only perform initialization should
which only perform initialization should delete themselves upon delete themselves upon completion to free resources for other tasks.
completion to free resources for other tasks. Initialization Initialization tasks may transform themselves into a "normal" application task.
tasks may transform themselves into a "normal" application task. This transformation typically involves changing priority and execution mode.
This transformation typically involves changing priority and RTEMS does not automatically delete the initialization tasks.
execution mode. RTEMS does not automatically delete the
initialization tasks.
System Initialization System Initialization
--------------------- ---------------------
System Initialization begins with board reset and continues System Initialization begins with board reset and continues through RTEMS
through RTEMS initialization, initialization of all device initialization, initialization of all device drivers, and eventually a context
drivers, and eventually a context switch to the first user switch to the first user task. Remember, that interrupts are disabled during
task. Remember, that interrupts are disabled during initialization and the *initialization context* is not a task in any sense and
initialization and the *initialization context* is not the user should be very careful during initialization.
a task in any sense and the user should be very careful
during initialization.
The BSP must ensure that the there is enough stack The BSP must ensure that the there is enough stack space reserved for the
space reserved for the initialization context to initialization context to successfully execute the initialization routines for
successfully execute the initialization routines for all device drivers and, in multiprocessor configurations, the Multiprocessor
all device drivers and, in multiprocessor configurations, the Communications Interface Layer initialization routine.
Multiprocessor Communications Interface Layer initialization
routine.
The Idle Task The Idle Task
------------- -------------
The Idle Task is the lowest priority task in a system The Idle Task is the lowest priority task in a system and executes only when no
and executes only when no other task is ready to execute. This other task is ready to execute. This default implementation of this task
default implementation of this task consists of an infinite consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
loop. RTEMS allows the Idle Task body to be replaced by a CPU a CPU specific implementation, a BSP specific implementation or an application
specific implementation, a BSP specific implementation or an specific implementation.
application specific implementation.
The Idle Task is preemptible and *WILL* be preempted when The Idle Task is preemptible and *WILL* be preempted when any other task is
any other task is made ready to execute. This characteristic is made ready to execute. This characteristic is critical to the overall behavior
critical to the overall behavior of any application. of any application.
Initialization Manager Failure Initialization Manager Failure
------------------------------ ------------------------------
The ``rtems_fatal_error_occurred`` directive will The ``rtems_fatal_error_occurred`` directive will be invoked from
be invoked from ``rtems_initialize_executive`` ``rtems_initialize_executive`` for any of the following reasons:
for any of the following reasons:
- If either the Configuration Table or the CPU Dependent - If either the Configuration Table or the CPU Dependent Information Table is
Information Table is not provided. not provided.
- If the starting address of the RTEMS RAM Workspace, - If the starting address of the RTEMS RAM Workspace, supplied by the
supplied by the application in the Configuration Table, is NULL application in the Configuration Table, is NULL or is not aligned on a
or is not aligned on a four-byte boundary. four-byte boundary.
- If the size of the RTEMS RAM Workspace is not large - If the size of the RTEMS RAM Workspace is not large enough to initialize and
enough to initialize and configure the system. configure the system.
- If the interrupt stack size specified is too small. - If the interrupt stack size specified is too small.
- If multiprocessing is configured and the node entry in - If multiprocessing is configured and the node entry in the Multiprocessor
the Multiprocessor Configuration Table is not between one and Configuration Table is not between one and the maximum_nodes entry.
the maximum_nodes entry.
- If a multiprocessor system is being configured and no - If a multiprocessor system is being configured and no Multiprocessor
Multiprocessor Communications Interface is specified. Communications Interface is specified.
- If no user initialization tasks are configured. At - If no user initialization tasks are configured. At least one initialization
least one initialization task must be configured to allow RTEMS task must be configured to allow RTEMS to pass control to the application at
to pass control to the application at the end of the executive the end of the executive initialization sequence.
initialization sequence.
- If any of the user initialization tasks cannot be - If any of the user initialization tasks cannot be created or started
created or started successfully. successfully.
A discussion of RTEMS actions when a fatal error occurs A discussion of RTEMS actions when a fatal error occurs may be found
may be found `Announcing a Fatal Error`_. `Announcing a Fatal Error`_.
Operations Operations
========== ==========
@ -121,10 +112,10 @@ Operations
Initializing RTEMS Initializing RTEMS
------------------ ------------------
The Initialization Manager ``rtems_initialize_executive`` The Initialization Manager ``rtems_initialize_executive`` directives is called
directives is called by the ``boot_card`` routine. The ``boot_card`` by the ``boot_card`` routine. The ``boot_card`` routine is invoked by the
routine is invoked by the Board Support Package once a basic C run-time Board Support Package once a basic C run-time environment is set up. This
environment is set up. This consists of consists of
- a valid and accessible text section, read-only data, read-write data and - a valid and accessible text section, read-only data, read-write data and
zero-initialized data, zero-initialized data,
@ -136,85 +127,83 @@ environment is set up. This consists of
- disabled interrupts. - disabled interrupts.
The ``rtems_initialize_executive`` directive uses a system The ``rtems_initialize_executive`` directive uses a system initialization
initialization linker set to initialize only those parts of the overall RTEMS linker set to initialize only those parts of the overall RTEMS feature set that
feature set that is necessary for a particular application. See `Linker Sets`_. is necessary for a particular application. See `Linker Sets`_. Each RTEMS
Each RTEMS feature used the application may optionally register an feature used the application may optionally register an initialization handler.
initialization handler. The system initialization API is available via``#included <rtems/sysinit.h>``. The system initialization API is available via``#included <rtems/sysinit.h>``.
A list of all initialization steps follows. Some steps are optional depending A list of all initialization steps follows. Some steps are optional depending
on the requested feature set of the application. The initialization steps are on the requested feature set of the application. The initialization steps are
execute in the order presented here. execute in the order presented here.
:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS` `RTEMS_SYSINIT_BSP_WORK_AREAS`
The work areas consisting of C Program Heap and the RTEMS Workspace are The work areas consisting of C Program Heap and the RTEMS Workspace are
initialized by the Board Support Package. This step is mandatory. initialized by the Board Support Package. This step is mandatory.
:dfn:`RTEMS_SYSINIT_BSP_START` `RTEMS_SYSINIT_BSP_START`
Basic initialization step provided by the Board Support Package. This step is Basic initialization step provided by the Board Support Package. This step
mandatory. is mandatory.
:dfn:`RTEMS_SYSINIT_DATA_STRUCTURES` `RTEMS_SYSINIT_DATA_STRUCTURES`
This directive is called when the Board Support Package has completed its basic This directive is called when the Board Support Package has completed its
initialization and allows RTEMS to initialize the application environment based basic initialization and allows RTEMS to initialize the application
upon the information in the Configuration Table, User Initialization Tasks environment based upon the information in the Configuration Table, User
Table, Device Driver Table, User Extension Table, Multiprocessor Configuration Initialization Tasks Table, Device Driver Table, User Extension Table,
Table, and the Multiprocessor Communications Interface (MPCI) Table. Multiprocessor Configuration Table, and the Multiprocessor Communications
Interface (MPCI) Table.
:dfn:`RTEMS_SYSINIT_BSP_LIBC` `RTEMS_SYSINIT_BSP_LIBC`
Depending on the application configuration the IO library and root filesystem Depending on the application configuration the IO library and root
is initialized. This step is mandatory. filesystem is initialized. This step is mandatory.
:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS` `RTEMS_SYSINIT_BEFORE_DRIVERS`
This directive performs initialization that must occur between basis RTEMS data This directive performs initialization that must occur between basis RTEMS
structure initialization and device driver initialization. In particular, in a data structure initialization and device driver initialization. In
multiprocessor configuration, this directive will create the MPCI Server Task. particular, in a multiprocessor configuration, this directive will create
the MPCI Server Task.
:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS` `RTEMS_SYSINIT_BSP_PRE_DRIVERS`
Initialization step performed right before device drivers are initialized Initialization step performed right before device drivers are initialized
provided by the Board Support Package. This step is mandatory. provided by the Board Support Package. This step is mandatory.
:dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS` `RTEMS_SYSINIT_DEVICE_DRIVERS`
This step initializes all statically configured device drivers and performs all This step initializes all statically configured device drivers and performs
RTEMS initialization which requires device drivers to be initialized. This all RTEMS initialization which requires device drivers to be initialized.
step is mandatory. This step is mandatory. In a multiprocessor configuration, this service
In a multiprocessor configuration, this service will initialize the will initialize the Multiprocessor Communications Interface (MPCI) and
Multiprocessor Communications Interface (MPCI) and synchronize with the other synchronize with the other nodes in the system.
nodes in the system.
:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS` `RTEMS_SYSINIT_BSP_POST_DRIVERS`
Initialization step performed right after device drivers are initialized Initialization step performed right after device drivers are initialized
provided by the Board Support Package. This step is mandatory. provided by the Board Support Package. This step is mandatory.
The final action of the ``rtems_initialize_executive`` directive The final action of the ``rtems_initialize_executive`` directive is to start
is to start multitasking. RTEMS does not return to the initialization context multitasking. RTEMS does not return to the initialization context and the
and the initialization stack may be re-used for interrupt processing. initialization stack may be re-used for interrupt processing.
Many of RTEMS actions during initialization are based upon Many of RTEMS actions during initialization are based upon the contents of the
the contents of the Configuration Table. For more information Configuration Table. For more information regarding the format and contents of
regarding the format and contents of this table, please refer this table, please refer to the chapter `Configuring a System`_.
to the chapter `Configuring a System`_.
The final action in the initialization sequence is the The final action in the initialization sequence is the initiation of
initiation of multitasking. When the scheduler and dispatcher multitasking. When the scheduler and dispatcher are enabled, the highest
are enabled, the highest priority, ready task will be dispatched priority, ready task will be dispatched to run. Control will not be returned
to run. Control will not be returned to the Board Support to the Board Support Package after multitasking is enabled. The initialization
Package after multitasking is enabled. The initialization stack may be re-used stack may be re-used for interrupt processing.
for interrupt processing.
Shutting Down RTEMS Shutting Down RTEMS
------------------- -------------------
The ``rtems_shutdown_executive`` directive is invoked by the The ``rtems_shutdown_executive`` directive is invoked by the application to end
application to end multitasking and terminate the system. multitasking and terminate the system.
Directives Directives
========== ==========
This section details the Initialization Manager's This section details the Initialization Manager's directives. A subsection is
directives. A subsection is dedicated to each of this manager's dedicated to each of this manager's directives and describes the calling
directives and describes the calling sequence, related sequence, related constants, usage, and status codes.
constants, usage, and status codes.
INITIALIZE_EXECUTIVE - Initialize RTEMS INITIALIZE_EXECUTIVE - Initialize RTEMS
--------------------------------------- ---------------------------------------
@ -256,7 +245,7 @@ SHUTDOWN_EXECUTIVE - Shutdown RTEMS
.. code:: c .. code:: c
void rtems_shutdown_executive( void rtems_shutdown_executive(
uint32_t result uint32_t result
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -266,19 +255,12 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive is called when the application wishes to shutdown RTEMS. The 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 system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and the
the specified ``result`` code. specified ``result`` code.
**NOTES:** **NOTES:**
This directive *must* be the last RTEMS directive This directive *must* be the last RTEMS directive invoked by an application and
invoked by an application and it *does not return* to the caller. it *does not return* to the caller.
This directive may be called any time. This directive may be called any time.
.. COMMENT: COPYRIGHT (c) 1988-2014.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

396
c_user/interrupt_manager.rst
View File

@ -1,41 +1,43 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Interrupt Manager Interrupt Manager
################# #################
Introduction Introduction
============ ============
Any real-time executive must provide a mechanism for Any real-time executive must provide a mechanism for quick response to
quick response to externally generated interrupts to satisfy the externally generated interrupts to satisfy the critical time constraints of the
critical time constraints of the application. The interrupt application. The interrupt manager provides this mechanism for RTEMS. This
manager provides this mechanism for RTEMS. This manager permits manager permits quick interrupt response times by providing the critical
quick interrupt response times by providing the critical ability ability to alter task execution which allows a task to be preempted upon exit
to alter task execution which allows a task to be preempted upon from an ISR. The interrupt manager includes the following directive:
exit from an ISR. The interrupt manager includes the following
directive:
- ``rtems_interrupt_catch`` - Establish an ISR - rtems_interrupt_catch_ - Establish an ISR
- ``rtems_interrupt_disable`` - Disable Interrupts - rtems_interrupt_disable_ - Disable Interrupts
- ``rtems_interrupt_enable`` - Enable Interrupts - rtems_interrupt_enable_ - Enable Interrupts
- ``rtems_interrupt_flash`` - Flash Interrupt - rtems_interrupt_flash_ - Flash Interrupt
- ``rtems_interrupt_local_disable`` - Disable Interrupts on Current Processor - rtems_interrupt_local_disable_ - Disable Interrupts on Current Processor
- ``rtems_interrupt_local_enable`` - Enable Interrupts on Current Processor - rtems_interrupt_local_enable_ - Enable Interrupts on Current Processor
- ``rtems_interrupt_lock_initialize`` - Initialize an ISR Lock - rtems_interrupt_lock_initialize_ - Initialize an ISR Lock
- ``rtems_interrupt_lock_acquire`` - Acquire an ISR Lock - rtems_interrupt_lock_acquire_ - Acquire an ISR Lock
- ``rtems_interrupt_lock_release`` - Release an ISR Lock - rtems_interrupt_lock_release_ - Release an ISR Lock
- ``rtems_interrupt_lock_acquire_isr`` - Acquire an ISR Lock from ISR - rtems_interrupt_lock_acquire_isr_ - Acquire an ISR Lock from ISR
- ``rtems_interrupt_lock_release_isr`` - Release an ISR Lock from ISR - rtems_interrupt_lock_release_isr_ - Release an ISR Lock from ISR
- ``rtems_interrupt_is_in_progress`` - Is an ISR in Progress - rtems_interrupt_is_in_progress_ - Is an ISR in Progress
Background Background
========== ==========
@ -44,108 +46,98 @@ Processing an Interrupt
----------------------- -----------------------
.. index:: interrupt processing .. index:: interrupt processing
The interrupt manager allows the application to The interrupt manager allows the application to connect a function to a
connect a function to a hardware interrupt vector. When an hardware interrupt vector. When an interrupt occurs, the processor will
interrupt occurs, the processor will automatically vector to automatically vector to RTEMS. RTEMS saves and restores all registers which
RTEMS. RTEMS saves and restores all registers which are not are not preserved by the normal C calling convention for the target processor
preserved by the normal C calling convention and invokes the user's ISR. The user's ISR is responsible for processing the
for the target interrupt, clearing the interrupt if necessary, and device specific
processor and invokes the user's ISR. The user's ISR is manipulation.
responsible for processing the interrupt, clearing the interrupt
if necessary, and device specific manipulation... index:: rtems_vector_number
The ``rtems_interrupt_catch`` .. index:: rtems_vector_number
directive connects a procedure to
an interrupt vector. The vector number is managed using
the ``rtems_vector_number`` data type.
The interrupt service routine is assumed The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt
to abide by these conventions and have a prototype similar to vector. The vector number is managed using the ``rtems_vector_number`` data
the following:.. index:: rtems_isr type.
The interrupt service routine is assumed to abide by these conventions and have
a prototype similar to the following:
.. index:: rtems_isr
.. code:: c .. code:: c
rtems_isr user_isr( rtems_isr user_isr(
rtems_vector_number vector rtems_vector_number vector
); );
The vector number argument is provided by RTEMS to The vector number argument is provided by RTEMS to allow the application to
allow the application to identify the interrupt source. This identify the interrupt source. This could be used to allow a single routine to
could be used to allow a single routine to service interrupts service interrupts from multiple instances of the same device. For example, a
from multiple instances of the same device. For example, a single routine could service interrupts from multiple serial ports and use the
single routine could service interrupts from multiple serial vector number to identify which port requires servicing.
ports and use the vector number to identify which port requires
servicing.
To minimize the masking of lower or equal priority To minimize the masking of lower or equal priority level interrupts, the ISR
level interrupts, the ISR should perform the minimum actions should perform the minimum actions required to service the interrupt. Other
required to service the interrupt. Other non-essential actions non-essential actions should be handled by application tasks. Once the user's
should be handled by application tasks. Once the user's ISR has ISR has completed, it returns control to the RTEMS interrupt manager which will
completed, it returns control to the RTEMS interrupt manager perform task dispatching and restore the registers saved before the ISR was
which will perform task dispatching and restore the registers invoked.
saved before the ISR was invoked.
The RTEMS interrupt manager guarantees that proper The RTEMS interrupt manager guarantees that proper task scheduling and
task scheduling and dispatching are performed at the conclusion dispatching are performed at the conclusion of an ISR. A system call made by
of an ISR. A system call made by the ISR may have readied a the ISR may have readied a task of higher priority than the interrupted task.
task of higher priority than the interrupted task. Therefore, Therefore, when the ISR completes, the postponed dispatch processing must be
when the ISR completes, the postponed dispatch processing must performed. No dispatch processing is performed as part of directives which
be performed. No dispatch processing is performed as part of have been invoked by an ISR.
directives which have been invoked by an ISR.
Applications must adhere to the following rule if Applications must adhere to the following rule if proper task scheduling and
proper task scheduling and dispatching is to be performed: dispatching is to be performed:
- ** *The interrupt manager must be used for all ISRs which .. note::
may be interrupted by the highest priority ISR which invokes an
RTEMS directive.*
Consider a processor which allows a numerically low The interrupt manager must be used for all ISRs which may be interrupted by
interrupt level to interrupt a numerically greater interrupt the highest priority ISR which invokes an RTEMS directive.
level. In this example, if an RTEMS directive is used in a
level 4 ISR, then all ISRs which execute at levels 0 through 4
must use the interrupt manager.
Interrupts are nested whenever an interrupt occurs Consider a processor which allows a numerically low interrupt level to
during the execution of another ISR. RTEMS supports efficient interrupt a numerically greater interrupt level. In this example, if an RTEMS
interrupt nesting by allowing the nested ISRs to terminate directive is used in a level 4 ISR, then all ISRs which execute at levels 0
without performing any dispatch processing. Only when the through 4 must use the interrupt manager.
Interrupts are nested whenever an interrupt occurs during the execution of
another ISR. RTEMS supports efficient interrupt nesting by allowing the nested
ISRs to terminate without performing any dispatch processing. Only when the
outermost ISR terminates will the postponed dispatching occur. outermost ISR terminates will the postponed dispatching occur.
RTEMS Interrupt Levels RTEMS Interrupt Levels
---------------------- ----------------------
.. index:: interrupt levels .. index:: interrupt levels
Many processors support multiple interrupt levels or Many processors support multiple interrupt levels or priorities. The exact
priorities. The exact number of interrupt levels is processor number of interrupt levels is processor dependent. RTEMS internally supports
dependent. RTEMS internally supports 256 interrupt levels which 256 interrupt levels which are mapped to the processor's interrupt levels. For
are mapped to the processor's interrupt levels. For specific specific information on the mapping between RTEMS and the target processor's
information on the mapping between RTEMS and the target interrupt levels, refer to the Interrupt Processing chapter of the Applications
processor's interrupt levels, refer to the Interrupt Processing Supplement document for a specific target processor.
chapter of the Applications Supplement document for a specific
target processor.
Disabling of Interrupts by RTEMS Disabling of Interrupts by RTEMS
-------------------------------- --------------------------------
.. index:: disabling interrupts .. index:: disabling interrupts
During the execution of directive calls, critical During the execution of directive calls, critical sections of code may be
sections of code may be executed. When these sections are executed. When these sections are encountered, RTEMS disables all maskable
encountered, RTEMS disables all maskable interrupts before the interrupts before the execution of the section and restores them to the
execution of the section and restores them to the previous level previous level upon completion of the section. RTEMS has been optimized to
upon completion of the section. RTEMS has been optimized to ensure that interrupts are disabled for a minimum length of time. The maximum
ensure that interrupts are disabled for a minimum length of length of time interrupts are disabled by RTEMS is processor dependent and is
time. The maximum length of time interrupts are disabled by detailed in the Timing Specification chapter of the Applications Supplement
RTEMS is processor dependent and is detailed in the Timing document for a specific target processor.
Specification chapter of the Applications Supplement document
for a specific target processor.
Non-maskable interrupts (NMI) cannot be disabled, and Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
ISRs which execute at this level MUST NEVER issue RTEMS system this level MUST NEVER issue RTEMS system calls. If a directive is invoked,
calls. If a directive is invoked, unpredictable results may unpredictable results may occur due to the inability of RTEMS to protect its
occur due to the inability of RTEMS to protect its critical critical sections. However, ISRs that make no system calls may safely execute
sections. However, ISRs that make no system calls may safely as non-maskable interrupts.
execute as non-maskable interrupts.
Operations Operations
========== ==========
@ -153,32 +145,28 @@ Operations
Establishing an ISR Establishing an ISR
------------------- -------------------
The ``rtems_interrupt_catch`` The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The
directive establishes an ISR for address of the ISR and its associated CPU vector number are specified to this
the system. The address of the ISR and its associated CPU directive. This directive installs the RTEMS interrupt wrapper in the
vector number are specified to this directive. This directive processor's Interrupt Vector Table and the address of the user's ISR in the
installs the RTEMS interrupt wrapper in the processor's RTEMS' Vector Table. This directive returns the previous contents of the
Interrupt Vector Table and the address of the user's ISR in the specified vector in the RTEMS' Vector Table.
RTEMS' Vector Table. This directive returns the previous
contents of the specified vector in the RTEMS' Vector Table.
Directives Allowed from an ISR Directives Allowed from an ISR
------------------------------ ------------------------------
Using the interrupt manager ensures that RTEMS knows Using the interrupt manager ensures that RTEMS knows when a directive is being
when a directive is being called from an ISR. The ISR may then called from an ISR. The ISR may then use system calls to synchronize itself
use system calls to synchronize itself with an application task. with an application task. The synchronization may involve messages, events or
The synchronization may involve messages, events or signals signals being passed by the ISR to the desired task. Directives invoked by an
being passed by the ISR to the desired task. Directives invoked ISR must operate only on objects which reside on the local node. The following
by an ISR must operate only on objects which reside on the local is a list of RTEMS system calls that may be made from an ISR:
node. The following is a list of RTEMS system calls that may be
made from an ISR:
- Task Management - Task Management
Although it is acceptable to operate on the RTEMS_SELF task (e.g. Although it is acceptable to operate on the RTEMS_SELF task (e.g. the
the currently executing task), while in an ISR, this will refer currently executing task), while in an ISR, this will refer to the
to the interrupted task. Most of the time, it is an application interrupted task. Most of the time, it is an application implementation
implementation error to use RTEMS_SELF from an ISR. error to use RTEMS_SELF from an ISR.
- rtems_task_suspend - rtems_task_suspend
- rtems_task_resume - rtems_task_resume
@ -253,10 +241,11 @@ made from an ISR:
Directives Directives
========== ==========
This section details the interrupt manager's This section details the interrupt manager's directives. A subsection is
directives. A subsection is dedicated to each of this manager's dedicated to each of this manager's directives and describes the calling
directives and describes the calling sequence, related sequence, related constants, usage, and status codes.
constants, usage, and status codes.
.. _rtems_interrupt_catch:
INTERRUPT_CATCH - Establish an ISR INTERRUPT_CATCH - Establish an ISR
---------------------------------- ----------------------------------
@ -270,31 +259,38 @@ INTERRUPT_CATCH - Establish an ISR
.. code:: c .. code:: c
rtems_status_code rtems_interrupt_catch( rtems_status_code rtems_interrupt_catch(
rtems_isr_entry new_isr_handler, rtems_isr_entry new_isr_handler,
rtems_vector_number vector, rtems_vector_number vector,
rtems_isr_entry \*old_isr_handler rtems_isr_entry *old_isr_handler
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - ISR established successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_NUMBER`` - illegal vector number ISR established successfully
``RTEMS_INVALID_ADDRESS`` - illegal ISR entry point or invalid ``old_isr_handler``
``RTEMS_INVALID_NUMBER``
illegal vector number
``RTEMS_INVALID_ADDRESS``
illegal ISR entry point or invalid ``old_isr_handler``
**DESCRIPTION:** **DESCRIPTION:**
This directive establishes an interrupt service This directive establishes an interrupt service routine (ISR) for the specified
routine (ISR) for the specified interrupt vector number. The``new_isr_handler`` parameter specifies the entry point of the ISR. interrupt vector number. The ``new_isr_handler`` parameter specifies the entry
The entry point of the previous ISR for the specified vector is point of the ISR. The entry point of the previous ISR for the specified vector
returned in ``old_isr_handler``. is returned in ``old_isr_handler``.
To release an interrupt vector, pass the old handler's address obtained To release an interrupt vector, pass the old handler's address obtained when
when the vector was first capture. the vector was first capture.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
.. _rtems_interrupt_disable:
INTERRUPT_DISABLE - Disable Interrupts INTERRUPT_DISABLE - Disable Interrupts
-------------------------------------- --------------------------------------
.. index:: disable interrupts .. index:: disable interrupts
@ -306,9 +302,8 @@ INTERRUPT_DISABLE - Disable Interrupts
.. code:: c .. code:: c
void rtems_interrupt_disable( void rtems_interrupt_disable(
rtems_interrupt_level level rtems_interrupt_level level
); );
/* this is implemented as a macro and sets level as a side-effect \*/
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -316,20 +311,23 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive disables all maskable interrupts and returns .. sidebar:: *Macro*
the previous ``level``. A later invocation of the``rtems_interrupt_enable`` directive should be used to
restore the interrupt level. This directive is implemented as a macro which modifies the ``level``
parameter.
This directive disables all maskable interrupts and returns the previous
``level``. A later invocation of the ``rtems_interrupt_enable`` directive
should be used to restore the interrupt level.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
*This directive is implemented as a macro which modifies the ``level``
parameter.*
This directive is only available on uni-processor configurations. The This directive is only available on uni-processor configurations. The
directive ``rtems_interrupt_local_disable`` is available on all directive ``rtems_interrupt_local_disable`` is available on all configurations.
configurations.
.. _rtems_interrupt_enable:
INTERRUPT_ENABLE - Enable Interrupts INTERRUPT_ENABLE - Enable Interrupts
------------------------------------ ------------------------------------
@ -342,7 +340,7 @@ INTERRUPT_ENABLE - Enable Interrupts
.. code:: c .. code:: c
void rtems_interrupt_enable( void rtems_interrupt_enable(
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -351,19 +349,20 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive enables maskable interrupts to the ``level`` This directive enables maskable interrupts to the ``level`` which was returned
which was returned by a previous call to``rtems_interrupt_disable``. by a previous call to ``rtems_interrupt_disable``. Immediately prior to
Immediately prior to invoking this directive, maskable interrupts should invoking this directive, maskable interrupts should be disabled by a call to
be disabled by a call to ``rtems_interrupt_disable`` ``rtems_interrupt_disable`` and will be enabled when this directive returns to
and will be enabled when this directive returns to the caller. the caller.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
This directive is only available on uni-processor configurations. The This directive is only available on uni-processor configurations. The
directive ``rtems_interrupt_local_enable`` is available on all directive ``rtems_interrupt_local_enable`` is available on all configurations.
configurations.
.. _rtems_interrupt_flash:
INTERRUPT_FLASH - Flash Interrupts INTERRUPT_FLASH - Flash Interrupts
---------------------------------- ----------------------------------
@ -376,7 +375,7 @@ INTERRUPT_FLASH - Flash Interrupts
.. code:: c .. code:: c
void rtems_interrupt_flash( void rtems_interrupt_flash(
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -385,19 +384,21 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive temporarily enables maskable interrupts to the ``level`` This directive temporarily enables maskable interrupts to the ``level`` which
which was returned by a previous call to``rtems_interrupt_disable``. was returned by a previous call to ``rtems_interrupt_disable``. Immediately
Immediately prior to invoking this directive, maskable interrupts should prior to invoking this directive, maskable interrupts should be disabled by a
be disabled by a call to ``rtems_interrupt_disable`` call to ``rtems_interrupt_disable`` and will be redisabled when this directive
and will be redisabled when this directive returns to the caller. returns to the caller.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
This directive is only available on uni-processor configurations. The This directive is only available on uni-processor configurations. The
directives ``rtems_interrupt_local_disable`` and``rtems_interrupt_local_enable`` is available on all directives ``rtems_interrupt_local_disable``
configurations. and``rtems_interrupt_local_enable`` is available on all configurations.
.. _rtems_interrupt_local_disable:
INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
----------------------------------------------------------------- -----------------------------------------------------------------
@ -410,9 +411,8 @@ INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
.. code:: c .. code:: c
void rtems_interrupt_local_disable( void rtems_interrupt_local_disable(
rtems_interrupt_level level rtems_interrupt_level level
); );
/* this is implemented as a macro and sets level as a side-effect \*/
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -420,20 +420,24 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive disables all maskable interrupts and returns .. sidebar:: *Macro*
the previous ``level``. A later invocation of the``rtems_interrupt_local_enable`` directive should be used to
restore the interrupt level. This directive is implemented as a macro which modifies the ``level``
parameter.
This directive disables all maskable interrupts and returns the previous
``level``. A later invocation of the ``rtems_interrupt_local_enable`` directive
should be used to restore the interrupt level.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
*This directive is implemented as a macro which modifies the ``level``
parameter.*
On SMP configurations this will not ensure system wide mutual exclusion. Use On SMP configurations this will not ensure system wide mutual exclusion. Use
interrupt locks instead. interrupt locks instead.
.. _rtems_interrupt_local_enable:
INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
--------------------------------------------------------------- ---------------------------------------------------------------
.. index:: enable interrupts .. index:: enable interrupts
@ -445,7 +449,7 @@ INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
.. code:: c .. code:: c
void rtems_interrupt_local_enable( void rtems_interrupt_local_enable(
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -454,16 +458,18 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive enables maskable interrupts to the ``level`` This directive enables maskable interrupts to the ``level`` which was returned
which was returned by a previous call to``rtems_interrupt_local_disable``. by a previous call to ``rtems_interrupt_local_disable``. Immediately prior to
Immediately prior to invoking this directive, maskable interrupts should invoking this directive, maskable interrupts should be disabled by a call to
be disabled by a call to ``rtems_interrupt_local_disable`` ``rtems_interrupt_local_disable`` and will be enabled when this directive
and will be enabled when this directive returns to the caller. returns to the caller.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
.. _rtems_interrupt_lock_initialize:
INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
-------------------------------------------------- --------------------------------------------------
@ -474,7 +480,7 @@ INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
.. code:: c .. code:: c
void rtems_interrupt_lock_initialize( void rtems_interrupt_lock_initialize(
rtems_interrupt_lock \*lock rtems_interrupt_lock *lock
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -489,6 +495,8 @@ Initializes an interrupt lock.
Concurrent initialization leads to unpredictable results. Concurrent initialization leads to unpredictable results.
.. _rtems_interrupt_lock_acquire:
INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
-------------------------------------------- --------------------------------------------
@ -499,8 +507,8 @@ INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
.. code:: c .. code:: c
void rtems_interrupt_lock_acquire( void rtems_interrupt_lock_acquire(
rtems_interrupt_lock \*lock, rtems_interrupt_lock *lock,
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -517,6 +525,8 @@ SMP lock.
This directive will not cause the calling thread to be preempted. This This directive will not cause the calling thread to be preempted. This
directive can be used in thread and interrupt context. directive can be used in thread and interrupt context.
.. _rtems_interrupt_lock_release:
INTERRUPT_LOCK_RELEASE - Release an ISR Lock INTERRUPT_LOCK_RELEASE - Release an ISR Lock
-------------------------------------------- --------------------------------------------
@ -527,8 +537,8 @@ INTERRUPT_LOCK_RELEASE - Release an ISR Lock
.. code:: c .. code:: c
void rtems_interrupt_lock_release( void rtems_interrupt_lock_release(
rtems_interrupt_lock \*lock, rtems_interrupt_lock *lock,
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -545,6 +555,8 @@ releases a SMP lock.
This directive will not cause the calling thread to be preempted. This This directive will not cause the calling thread to be preempted. This
directive can be used in thread and interrupt context. directive can be used in thread and interrupt context.
.. _rtems_interrupt_lock_acquire_isr:
INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
--------------------------------------------------------- ---------------------------------------------------------
@ -555,8 +567,8 @@ INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
.. code:: c .. code:: c
void rtems_interrupt_lock_acquire_isr( void rtems_interrupt_lock_acquire_isr(
rtems_interrupt_lock \*lock, rtems_interrupt_lock *lock,
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -577,6 +589,8 @@ protected by this lock, then the result is unpredictable.
This directive should be called from the corresponding interrupt service This directive should be called from the corresponding interrupt service
routine. routine.
.. _rtems_interrupt_lock_release_isr:
INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
--------------------------------------------------------- ---------------------------------------------------------
@ -587,8 +601,8 @@ INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
.. code:: c .. code:: c
void rtems_interrupt_lock_release_isr( void rtems_interrupt_lock_release_isr(
rtems_interrupt_lock \*lock, rtems_interrupt_lock *lock,
rtems_interrupt_level level rtems_interrupt_level level
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -605,6 +619,8 @@ directive releases a SMP lock.
This directive should be called from the corresponding interrupt service This directive should be called from the corresponding interrupt service
routine. routine.
.. _rtems_interrupt_is_in_progress:
INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
------------------------------------------------ ------------------------------------------------
.. index:: is interrupt in progress .. index:: is interrupt in progress
@ -615,7 +631,7 @@ INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
.. code:: c .. code:: c
bool rtems_interrupt_is_in_progress( void ); bool rtems_interrupt_is_in_progress(void);
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
@ -623,19 +639,11 @@ NONE
**DESCRIPTION:** **DESCRIPTION:**
This directive returns ``TRUE`` if the processor is currently This directive returns ``TRUE`` if the processor is currently servicing an
servicing an interrupt and ``FALSE`` otherwise. A return value interrupt and ``FALSE`` otherwise. A return value of ``TRUE`` indicates that
of ``TRUE`` indicates that the caller is an interrupt service the caller is an interrupt service routine, *NOT* a task. The directives
routine, *NOT* a task. The directives available to an interrupt available to an interrupt service routine are restricted.
service routine are restricted.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be preempted. This directive will not cause the calling task to be preempted.
.. COMMENT: COPYRIGHT (c) 1988-2008
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

355
c_user/key_concepts.rst
View File

@ -1,106 +1,108 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Key Concepts Key Concepts
############ ############
Introduction Introduction
============ ============
The facilities provided by RTEMS are built upon a The facilities provided by RTEMS are built upon a foundation of very powerful
foundation of very powerful concepts. These concepts must be concepts. These concepts must be understood before the application developer
understood before the application developer can efficiently can efficiently utilize RTEMS. The purpose of this chapter is to familiarize
utilize RTEMS. The purpose of this chapter is to familiarize
one with these concepts. one with these concepts.
.. _objects:
Objects Objects
======= =======
.. index:: objects .. index:: objects
RTEMS provides directives which can be used to RTEMS provides directives which can be used to dynamically create, delete, and
dynamically create, delete, and manipulate a set of predefined manipulate a set of predefined object types. These types include tasks,
object types. These types include tasks, message queues, message queues, semaphores, memory regions, memory partitions, timers, ports,
semaphores, memory regions, memory partitions, timers, ports, and rate monotonic periods. The object-oriented nature of RTEMS encourages the
and rate monotonic periods. The object-oriented nature of RTEMS creation of modular applications built upon re-usable "building block"
encourages the creation of modular applications built upon routines.
re-usable "building block" routines.
All objects are created on the local node as required All objects are created on the local node as required by the application and
by the application and have an RTEMS assigned ID. All objects have an RTEMS assigned ID. All objects have a user-assigned name. Although a
have a user-assigned name. Although a relationship exists relationship exists between an object's name and its RTEMS assigned ID, the
between an object's name and its RTEMS assigned ID, the name and name and ID are not identical. Object names are completely arbitrary and
ID are not identical. Object names are completely arbitrary and selected by the user as a meaningful "tag" which may commonly reflect the
selected by the user as a meaningful "tag" which may commonly object's use in the application. Conversely, object IDs are designed to
reflect the object's use in the application. Conversely, object facilitate efficient object manipulation by the executive.
IDs are designed to facilitate efficient object manipulation by
the executive.
Object Names Object Names
------------ ------------
.. index:: object name .. index:: object name
.. index:: rtems_object_name .. index:: rtems_object_name
An object name is an unsigned thirty-two bit entity An object name is an unsigned thirty-two bit entity associated with the object
associated with the object by the user. The data type``rtems_name`` is used to store object names... index:: rtems_build_name 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
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 .. code:: c
rtems_object_name my_name; rtems_object_name my_name;
my_name = rtems_build_name( 'L', 'I', 'T', 'E' ); my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
However, it is not required that the application use ASCII However, it is not required that the application use ASCII characters to build
characters to build object names. For example, if an object names. For example, if an application requires one-hundred tasks, it
application requires one-hundred tasks, it would be difficult to would be difficult to assign meaningful ASCII names to each task. A more
assign meaningful ASCII names to each task. A more convenient convenient approach would be to name them the binary values one through
approach would be to name them the binary values one through
one-hundred, respectively... index:: rtems_object_get_name one-hundred, respectively... index:: rtems_object_get_name
RTEMS provides a helper routine, ``rtems_object_get_name``, RTEMS provides a helper routine, ``rtems_object_get_name``, which can be used
which can be used to obtain the name of any RTEMS object using just to obtain the name of any RTEMS object using just its ID. This routine
its ID. This routine attempts to convert the name into a printable string. attempts to convert the name into a printable string.
The following example illustrates the use of this method to print an object
name:
The following example illustrates the use of this method to print
an object name:
.. code:: c .. code:: c
#include <rtems.h> #include <rtems.h>
#include <rtems/bspIo.h> #include <rtems/bspIo.h>
void print_name(rtems_id id) void print_name(rtems_id id)
{ {
char buffer[10]; /* name assumed to be 10 characters or less \*/ char buffer[10]; /* name assumed to be 10 characters or less */
char \*result; char *result;
result = rtems_object_get_name( id, sizeof(buffer), buffer ); result = rtems_object_get_name( id, sizeof(buffer), buffer );
printk( "ID=0x%08x name=%s\\n", id, ((result) ? result : "no name") ); printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
} }
Object IDs Object IDs
---------- ----------
.. index:: object ID .. index:: object ID
.. index:: object ID composition .. index:: object ID composition
.. index:: rtems_id .. index:: rtems_id
An object ID is a unique unsigned integer value which uniquely identifies An object ID is a unique unsigned integer value which uniquely identifies an
an object instance. Object IDs are passed as arguments to many directives object instance. Object IDs are passed as arguments to many directives in
in RTEMS and RTEMS translates the ID to an internal object pointer. The RTEMS and RTEMS translates the ID to an internal object pointer. The efficient
efficient manipulation of object IDs is critical to the performance manipulation of object IDs is critical to the performance of RTEMS services.
of RTEMS services. Because of this, there are two object Id formats Because of this, there are two object Id formats defined. Each target
defined. Each target architecture specifies which format it will use. architecture specifies which format it will use. There is a thirty-two bit
There is a thirty-two bit format which is used for most of the supported format which is used for most of the supported architectures and supports
architectures and supports multiprocessor configurations. There is also multiprocessor configurations. There is also a simpler sixteen bit format
a simpler sixteen bit format which is appropriate for smaller target which is appropriate for smaller target architectures and does not support
architectures and does not support multiprocessor configurations. multiprocessor configurations.
Thirty-Two Object ID Format Thirty-Two Object ID Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The thirty-two bit format for an object ID is composed of four parts: API, 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`` object class, node, and index. The data type ``rtems_id`` is used to store
is used to store object IDs. object IDs.
.. code:: c .. code:: c
@ -111,21 +113,19 @@ is used to store object IDs.
| | | | | | | | | |
+---------+-------+--------------+-------------------------------+ +---------+-------+--------------+-------------------------------+
The most significant five bits are the object class. The next The most significant five bits are the object class. The next three bits
three bits indicate the API to which the object class belongs. indicate the API to which the object class belongs. The next eight bits
The next eight bits (16-23) are the number of the node on which (16-23) are the number of the node on which this object was created. The node
this object was created. The node number is always one (1) in a single number is always one (1) in a single processor system. The least significant
processor system. The least significant sixteen bits form an sixteen bits form an identifier within a particular object type. This
identifier within a particular object type. This identifier, identifier, called the object index, ranges in value from 1 to the maximum
called the object index, ranges in value from 1 to the maximum
number of objects configured for this object type. number of objects configured for this object type.
Sixteen Bit Object ID Format Sixteen Bit Object ID Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The sixteen bit format for an object ID is composed of three parts: API, The sixteen bit format for an object ID is composed of three parts: API, object
object class, and index. The data type ``rtems_id`` class, and index. The data type ``rtems_id`` is used to store object IDs.
is used to store object IDs.
.. code:: c .. code:: c
@ -137,39 +137,35 @@ is used to store object IDs.
+---------+-------+--------------+ +---------+-------+--------------+
The sixteen-bit format is designed to be as similar as possible to the 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 thrity-two bit format. The differences are limited to the eliminatation of the
of the node field and reduction of the index field from sixteen-bits node field and reduction of the index field from sixteen-bits to 8-bits. Thus
to 8-bits. Thus the sixteen bit format only supports up to 255 object the sixteen bit format only supports up to 255 object instances per API/Class
instances per API/Class combination and single processor systems. combination and single processor systems. As this format is typically utilized
As this format is typically utilized by sixteen-bit processors with by sixteen-bit processors with limited address space, this is more than enough
limited address space, this is more than enough object instances. object instances.
Object ID Description Object ID Description
--------------------- ---------------------
The components of an object ID make it possible The components of an object ID make it possible to quickly locate any object in
to quickly locate any object in even the most complicated even the most complicated multiprocessor system. Object ID's are associated
multiprocessor system. Object ID's are associated with an with an object by RTEMS when the object is created and the corresponding ID is
object by RTEMS when the object is created and the corresponding returned by the appropriate object create directive. The object ID is required
ID is returned by the appropriate object create directive. The as input to all directives involving objects, except those which create an
object ID is required as input to all directives involving object or obtain the ID of an object.
objects, except those which create an object or obtain the ID of
an object.
The object identification directives can be used to The object identification directives can be used to dynamically obtain a
dynamically obtain a particular object's ID given its name. particular object's ID given its name. This mapping is accomplished by
This mapping is accomplished by searching the name table searching the name table associated with this object type. If the name is
associated with this object type. If the name is non-unique, non-unique, then the ID associated with the first occurrence of the name will
then the ID associated with the first occurrence of the name be returned to the application. Since object IDs are returned when the object
will be returned to the application. Since object IDs are is created, the object identification directives are not necessary in a
returned when the object is created, the object identification properly designed single processor application.
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
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 node from object ID
.. index:: obtaining index from object ID .. index:: obtaining index from object ID
.. index:: get class from object ID .. index:: get class from object ID
@ -187,26 +183,24 @@ as follows:.. index:: obtaining class from object ID
uint32_t rtems_object_id_get_node( rtems_id ); uint32_t rtems_object_id_get_node( rtems_id );
uint32_t rtems_object_id_get_index( rtems_id ); uint32_t rtems_object_id_get_index( rtems_id );
An object control block is a data structure defined An object control block is a data structure defined by RTEMS which contains the
by RTEMS which contains the information necessary to manage a information necessary to manage a particular object type. For efficiency
particular object type. For efficiency reasons, the format of reasons, the format of each object type's control block is different. However,
each object type's control block is different. However, many of many of the fields are similar in function. The number of each type of control
the fields are similar in function. The number of each type of block is application dependent and determined by the values specified in the
control block is application dependent and determined by the user's Configuration Table. An object control block is allocated at object
values specified in the user's Configuration Table. An object create time and freed when the object is deleted. With the exception of user
control block is allocated at object create time and freed when extension routines, object control blocks are not directly manipulated by user
the object is deleted. With the exception of user extension applications.
routines, object control blocks are not directly manipulated by
user applications.
Communication and Synchronization Communication and Synchronization
================================= =================================
.. index:: communication and synchronization .. index:: communication and synchronization
In real-time multitasking applications, the ability In real-time multitasking applications, the ability for cooperating execution
for cooperating execution threads to communicate and synchronize threads to communicate and synchronize with each other is imperative. A
with each other is imperative. A real-time executive should real-time executive should provide an application with the following
provide an application with the following capabilities: capabilities:
- Data transfer between cooperating tasks - Data transfer between cooperating tasks
@ -216,15 +210,13 @@ provide an application with the following capabilities:
- Synchronization of tasks and ISRs - Synchronization of tasks and ISRs
Most RTEMS managers can be used to provide some form Most RTEMS managers can be used to provide some form of communication and/or
of communication and/or synchronization. However, managers synchronization. However, managers dedicated specifically to communication and
dedicated specifically to communication and synchronization synchronization provide well established mechanisms which directly map to the
provide well established mechanisms which directly map to the application's varying needs. This level of flexibility allows the application
application's varying needs. This level of flexibility allows designer to match the features of a particular manager with the complexity of
the application designer to match the features of a particular communication and synchronization required. The following managers were
manager with the complexity of communication and synchronization specifically designed for communication and synchronization:
required. The following managers were specifically designed for
communication and synchronization:
- Semaphore - Semaphore
@ -234,83 +226,69 @@ communication and synchronization:
- Signal - Signal
The semaphore manager supports mutual exclusion The semaphore manager supports mutual exclusion involving the synchronization
involving the synchronization of access to one or more shared of access to one or more shared user resources. Binary semaphores may utilize
user resources. Binary semaphores may utilize the optional the optional priority inheritance algorithm to avoid the problem of priority
priority inheritance algorithm to avoid the problem of priority
inversion. The message manager supports both communication and inversion. The message manager supports both communication and
synchronization, while the event manager primarily provides a synchronization, while the event manager primarily provides a high performance
high performance synchronization mechanism. The signal manager synchronization mechanism. The signal manager supports only asynchronous
supports only asynchronous communication and is typically used communication and is typically used for exception handling.
for exception handling.
Time Time
==== ====
.. index:: time .. index:: time
The development of responsive real-time applications The development of responsive real-time applications requires an understanding
requires an understanding of how RTEMS maintains and supports of how RTEMS maintains and supports time-related operations. The basic unit of
time-related operations. The basic unit of time in RTEMS is time in RTEMS is known as a tick. The frequency of clock ticks is completely
known as a tick. The frequency of clock ticks is completely application dependent and determines the granularity and accuracy of all
application dependent and determines the granularity and interval and calendar time operations... index:: rtems_interval
accuracy of all interval and calendar time operations... index:: rtems_interval
By tracking time in units of ticks, RTEMS is capable By tracking time in units of ticks, RTEMS is capable of supporting interval
of supporting interval timing functions such as task delays, timing functions such as task delays, timeouts, timeslicing, the delayed
timeouts, timeslicing, the delayed execution of timer service execution of timer service routines, and the rate monotonic scheduling of
routines, and the rate monotonic scheduling of tasks. An tasks. An interval is defined as a number of ticks relative to the current
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
time. For example, when a task delays for an interval of ten implied that the task will not execute until ten clock ticks have occurred.
ticks, it is implied that the task will not execute until ten All intervals are specified using data type ``rtems_interval``.
clock ticks have occurred.
All intervals are specified using data type``rtems_interval``.
A characteristic of interval timing is that the A characteristic of interval timing is that the actual interval period may be a
actual interval period may be a fraction of a tick less than the fraction of a tick less than the interval requested. This occurs because the
interval requested. This occurs because the time at which the time at which the delay timer is set up occurs at some time between two clock
delay timer is set up occurs at some time between two clock ticks. Therefore, the first countdown tick occurs in less than the complete
ticks. Therefore, the first countdown tick occurs in less than time interval for a tick. This can be a problem if the clock granularity is
the complete time interval for a tick. This can be a problem if large.
the clock granularity is large.
The rate monotonic scheduling algorithm is a hard The rate monotonic scheduling algorithm is a hard real-time scheduling
real-time scheduling methodology. This methodology provides methodology. This methodology provides rules which allows one to guarantee
rules which allows one to guarantee that a set of independent that a set of independent periodic tasks will always meet their deadlines -
periodic tasks will always meet their deadlines - even under even under transient overload conditions. The rate monotonic manager provides
transient overload conditions. The rate monotonic manager directives built upon the Clock Manager's interval timer support routines.
provides directives built upon the Clock Manager's interval
timer support routines.
Interval timing is not sufficient for the many Interval timing is not sufficient for the many applications which require that
applications which require that time be kept in wall time or time be kept in wall time or true calendar form. Consequently, RTEMS maintains
true calendar form. Consequently, RTEMS maintains the current the current date and time. This allows selected time operations to be
date and time. This allows selected time operations to be scheduled at an actual calendar date and time. For example, a task could
scheduled at an actual calendar date and time. For example, a request to delay until midnight on New Year's Eve before lowering the ball at
task could request to delay until midnight on New Year's Eve Times Square. The data type ``rtems_time_of_day`` is used to specify calendar
before lowering the ball at Times Square. time in RTEMS services. See `Time and Date Data Structures`_
The data type ``rtems_time_of_day`` is used to specify
calendar time in RTEMS services.
See `Time and Date Data Structures`_
... index:: rtems_time_of_day ... index:: rtems_time_of_day
Obviously, the directives which use intervals or wall Obviously, the directives which use intervals or wall time cannot operate
time cannot operate without some external mechanism which without some external mechanism which provides a periodic clock tick. This
provides a periodic clock tick. This clock tick is typically clock tick is typically provided by a real time clock or counter/timer device.
provided by a real time clock or counter/timer device.
Memory Management Memory Management
================= =================
.. index:: memory management .. index:: memory management
RTEMS memory management facilities can be grouped RTEMS memory management facilities can be grouped into two classes: dynamic
into two classes: dynamic memory allocation and address memory allocation and address translation. Dynamic memory allocation is
translation. Dynamic memory allocation is required by required by applications whose memory requirements vary through the
applications whose memory requirements vary through the application's course of execution. Address translation is needed by
application's course of execution. Address translation is applications which share memory with another CPU or an intelligent Input/Output
needed by applications which share memory with another CPU or an processor. The following RTEMS managers provide facilities to manage memory:
intelligent Input/Output processor. The following RTEMS
managers provide facilities to manage memory:
- Region - Region
@ -318,21 +296,12 @@ managers provide facilities to manage memory:
- Dual Ported Memory - Dual Ported Memory
RTEMS memory management features allow an application RTEMS memory management features allow an application to create simple memory
to create simple memory pools of fixed size buffers and/or more pools of fixed size buffers and/or more complex memory pools of variable size
complex memory pools of variable size segments. The partition segments. The partition manager provides directives to manage and maintain
manager provides directives to manage and maintain pools of pools of fixed size entities such as resource control blocks. Alternatively,
fixed size entities such as resource control blocks. the region manager provides a more general purpose memory allocation scheme
Alternatively, the region manager provides a more general that supports variable size blocks of memory which are dynamically obtained and
purpose memory allocation scheme that supports variable size freed by the application. The dual-ported memory manager provides executive
blocks of memory which are dynamically obtained and freed by the support for address translation between internal and external dual-ported RAM
application. The dual-ported memory manager provides executive address space.
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.

540
c_user/overview.rst
View File

@ -1,13 +1,16 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Overview Overview
######## ########
Introduction Introduction
============ ============
RTEMS, Real-Time Executive for Multiprocessor Systems, is a RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive
real-time executive (kernel) which provides a high performance (kernel) which provides a high performance environment for embedded military
environment for embedded military applications including the applications including the following features:
following features:
- multitasking capabilities - multitasking capabilities
@ -27,164 +30,153 @@ following features:
- high level of user configurability - high level of user configurability
This manual describes the usage of RTEMS for This manual describes the usage of RTEMS for applications written in the C
applications written in the C programming language. Those programming language. Those implementation details that are processor
implementation details that are processor dependent are provided dependent are provided in the Applications Supplement documents. A supplement
in the Applications Supplement documents. A supplement document which addresses specific architectural issues that affect RTEMS is
document which addresses specific architectural issues that provided for each processor type that is supported.
affect RTEMS is provided for each processor type that is
supported.
Real-time Application Systems Real-time Application Systems
============================= =============================
Real-time application systems are a special class of Real-time application systems are a special class of computer applications.
computer applications. They have a complex set of They have a complex set of characteristics that distinguish them from other
characteristics that distinguish them from other software software problems. Generally, they must adhere to more rigorous requirements.
problems. Generally, they must adhere to more rigorous The correctness of the system depends not only on the results of computations,
requirements. The correctness of the system depends not only on but also on the time at which the results are produced. The most important and
the results of computations, but also on the time at which the complex characteristic of real-time application systems is that they must
results are produced. The most important and complex receive and respond to a set of external stimuli within rigid and critical time
characteristic of real-time application systems is that they constraints referred to as deadlines. Systems can be buried by an avalanche of
must receive and respond to a set of external stimuli within interdependent, asynchronous or cyclical event streams.
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 Deadlines can be further characterized as either hard or soft based upon the
or soft based upon the value of the results when produced after value of the results when produced after the deadline has passed. A deadline
the deadline has passed. A deadline is hard if the results have is hard if the results have no value or if their use will result in a
no value or if their use will result in a catastrophic event. catastrophic event. In contrast, results which are produced after a soft
In contrast, results which are produced after a soft deadline deadline may have some value.
may have some value.
Another distinguishing requirement of real-time Another distinguishing requirement of real-time application systems is the
application systems is the ability to coordinate or manage a ability to coordinate or manage a large number of concurrent activities. Since
large number of concurrent activities. Since software is a software is a synchronous entity, this presents special problems. One
synchronous entity, this presents special problems. One instruction follows another in a repeating synchronous cycle. Even though
instruction follows another in a repeating synchronous cycle. mechanisms have been developed to allow for the processing of external
Even though mechanisms have been developed to allow for the asynchronous events, the software design efforts required to process and manage
processing of external asynchronous events, the software design these events and tasks are growing more complicated.
efforts required to process and manage these events and tasks
are growing more complicated.
The design process is complicated further by The design process is complicated further by spreading this activity over a set
spreading this activity over a set of processors instead of a of processors instead of a single processor. The challenges associated with
single processor. The challenges associated with designing and designing and building real-time application systems become very complex when
building real-time application systems become very complex when multiple processors are involved. New requirements such as interprocessor
multiple processors are involved. New requirements such as communication channels and global resources that must be shared between
interprocessor communication channels and global resources that competing processors are introduced. The ramifications of multiple processors
must be shared between competing processors are introduced. The complicate each and every characteristic of a real-time system.
ramifications of multiple processors complicate each and every
characteristic of a real-time system.
Real-time Executive Real-time Executive
=================== ===================
Fortunately, real-time operating systems or real-time Fortunately, real-time operating systems or real-time executives serve as a
executives serve as a cornerstone on which to build the cornerstone on which to build the application system. A real-time multitasking
application system. A real-time multitasking executive allows executive allows an application to be cast into a set of logical, autonomous
an application to be cast into a set of logical, autonomous processes or tasks which become quite manageable. Each task is internally
processes or tasks which become quite manageable. Each task is synchronous, but different tasks execute independently, resulting in an
internally synchronous, but different tasks execute asynchronous processing stream. Tasks can be dynamically paused for many
independently, resulting in an asynchronous processing stream. reasons resulting in a different task being allowed to execute for a period of
Tasks can be dynamically paused for many reasons resulting in a time. The executive also provides an interface to other system components such
different task being allowed to execute for a period of time. as interrupt handlers and device drivers. System components may request the
The executive also provides an interface to other system executive to allocate and coordinate resources, and to wait for and trigger
components such as interrupt handlers and device drivers. synchronizing conditions. The executive system calls effectively extend the
System components may request the executive to allocate and CPU instruction set to support efficient multitasking. By causing tasks to
coordinate resources, and to wait for and trigger synchronizing travel through well-defined state transitions, system calls permit an
conditions. The executive system calls effectively extend the application to demand-switch between tasks in response to real-time events.
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 By proper grouping of responses to stimuli into separate tasks, a system can
separate tasks, a system can now asynchronously switch between now asynchronously switch between independent streams of execution, directly
independent streams of execution, directly responding to responding to external stimuli as they occur. This allows the system design to
external stimuli as they occur. This allows the system design meet critical performance specifications which are typically measured by
to meet critical performance specifications which are typically guaranteed response time and transaction throughput. The multiprocessor
measured by guaranteed response time and transaction throughput. extensions of RTEMS provide the features necessary to manage the extra
The multiprocessor extensions of RTEMS provide the features requirements introduced by a system distributed across several processors. It
necessary to manage the extra requirements introduced by a removes the physical barriers of processor boundaries from the world of the
system distributed across several processors. It removes the system designer, enabling more critical aspects of the system to receive the
physical barriers of processor boundaries from the world of the required attention. Such a system, based on an efficient real-time,
system designer, enabling more critical aspects of the system to multiprocessor executive, is a more realistic model of the outside world or
receive the required attention. Such a system, based on an environment for which it is designed. As a result, the system will always be
efficient real-time, multiprocessor executive, is a more more logical, efficient, and reliable.
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 By using the directives provided by RTEMS, the real-time applications developer
real-time applications developer is freed from the problem of is freed from the problem of controlling and synchronizing multiple tasks and
controlling and synchronizing multiple tasks and processors. In processors. In addition, one need not develop, test, debug, and document
addition, one need not develop, test, debug, and document routines to manage memory, pass messages, or provide mutual exclusion. The
routines to manage memory, pass messages, or provide mutual developer is then able to concentrate solely on the application. By using
exclusion. The developer is then able to concentrate solely on standard software components, the time and cost required to develop
the application. By using standard software components, the sophisticated real-time applications is significantly reduced.
time and cost required to develop sophisticated real-time
applications is significantly reduced.
RTEMS Application Architecture RTEMS Application Architecture
============================== ==============================
One important design goal of RTEMS was to provide a One important design goal of RTEMS was to provide a bridge between two critical
bridge between two critical layers of typical real-time systems. layers of typical real-time systems. As shown in the following figure, RTEMS
As shown in the following figure, RTEMS serves as a buffer between the serves as a buffer between the project dependent application code and the
project dependent application code and the target hardware. target hardware. Most hardware dependencies for real-time applications can be
Most hardware dependencies for real-time applications can be
localized to the low level device drivers. localized to the low level device drivers.
.. code:: c .. COMMENT: .. code:: c
.. COMMENT:
.. COMMENT: +-----------------------------------------------------------+
.. COMMENT: | Application Dependent Software |
.. COMMENT: | +----------------------------------------+ |
.. COMMENT: | | Standard Application Components | |
.. COMMENT: | | +-------------+---+ |
.. COMMENT: | +---+-----------+ | | |
.. COMMENT: | | Board Support | | RTEMS | |
.. COMMENT: | | Package | | | |
.. COMMENT: +----+---------------+--------------+-----------------+-----|
.. COMMENT: | Target Hardware |
.. COMMENT: +-----------------------------------------------------------+
+-----------------------------------------------------------+ .. figure:: rtemsarc.png
| Application Dependent Software | :width: 488
| +----------------------------------------+ | :height: 100px
| | Standard Application Components | | :align: center
| | +-------------+---+ | :alt: RTEMS Application Architecture
| +---+-----------+ | | |
| | Board Support | | RTEMS | |
| | Package | | | |
+----+---------------+--------------+-----------------+-----|
| Target Hardware |
+-----------------------------------------------------------+
The RTEMS I/O interface manager provides an efficient tool for incorporating The RTEMS I/O interface manager provides an efficient tool for incorporating
these hardware dependencies into the system while simultaneously these hardware dependencies into the system while simultaneously providing a
providing a general mechanism to the application code that general mechanism to the application code that accesses them. A well designed
accesses them. A well designed real-time system can benefit real-time system can benefit from this architecture by building a rich library
from this architecture by building a rich library of standard of standard application components which can be used repeatedly in other
application components which can be used repeatedly in other
real-time projects. real-time projects.
RTEMS Internal Architecture RTEMS Internal Architecture
=========================== ===========================
RTEMS can be viewed as a set of layered components that work in RTEMS can be viewed as a set of layered components that work in harmony to
harmony to provide a set of services to a real-time application provide a set of services to a real-time application system. The executive
system. The executive interface presented to the application is interface presented to the application is formed by grouping directives into
formed by grouping directives into logical sets called resource managers. logical sets called resource managers. Functions utilized by multiple managers
Functions utilized by multiple managers such as scheduling, such as scheduling, dispatching, and object management are provided in the
dispatching, and object management are provided in the executive executive core. The executive core depends on a small set of CPU dependent
core. The executive core depends on a small set of CPU dependent routines. routines. Together these components provide a powerful run time environment
Together these components provide a powerful run time that promotes the development of efficient real-time application systems. The
environment that promotes the development of efficient real-time following figure illustrates this organization:
application systems. The following figure illustrates this organization:
.. code:: c .. COMMENT: .. code:: c
.. COMMENT:
.. COMMENT: +-----------------------------------------------+
.. COMMENT: | RTEMS Executive Interface |
.. COMMENT: +-----------------------------------------------+
.. COMMENT: | RTEMS Core |
.. COMMENT: +-----------------------------------------------+
.. COMMENT: | CPU Dependent Code |
.. COMMENT: +-----------------------------------------------+
+-----------------------------------------------+ .. figure:: rtemspie.png
| RTEMS Executive Interface | :width: 70%
+-----------------------------------------------+ :align: center
| RTEMS Core | :alt: RTEMS Internal Architecture
+-----------------------------------------------+
| CPU Dependent Code |
+-----------------------------------------------+
Subsequent chapters present a detailed description of the capabilities Subsequent chapters present a detailed description of the capabilities provided
provided by each of the following RTEMS managers: by each of the following RTEMS managers:
- initialization - initialization
@ -223,112 +215,96 @@ provided by each of the following RTEMS managers:
User Customization and Extensibility User Customization and Extensibility
==================================== ====================================
As thirty-two bit microprocessors have decreased in As thirty-two bit microprocessors have decreased in cost, they have become
cost, they have become increasingly common in a variety of increasingly common in a variety of embedded systems. A wide range of custom
embedded systems. A wide range of custom and general-purpose and general-purpose processor boards are based on various thirty-two bit
processor boards are based on various thirty-two bit processors. processors. RTEMS was designed to make no assumptions concerning the
RTEMS was designed to make no assumptions concerning the characteristics of individual microprocessor families or of specific support
characteristics of individual microprocessor families or of hardware. In addition, RTEMS allows the system developer a high degree of
specific support hardware. In addition, RTEMS allows the system freedom in customizing and extending its features.
developer a high degree of freedom in customizing and extending
its features.
RTEMS assumes the existence of a supported RTEMS assumes the existence of a supported microprocessor and sufficient memory
microprocessor and sufficient memory for both RTEMS and the for both RTEMS and the real-time application. Board dependent components such
real-time application. Board dependent components such as as clocks, interrupt controllers, or I/O devices can be easily integrated with
clocks, interrupt controllers, or I/O devices can be easily RTEMS. The customization and extensibility features allow RTEMS to efficiently
integrated with RTEMS. The customization and extensibility support as many environments as possible.
features allow RTEMS to efficiently support as many environments
as possible.
Portability Portability
=========== ===========
The issue of portability was the major factor in the The issue of portability was the major factor in the creation of RTEMS. Since
creation of RTEMS. Since RTEMS is designed to isolate the RTEMS is designed to isolate the hardware dependencies in the specific board
hardware dependencies in the specific board support packages, support packages, the real-time application should be easily ported to any
the real-time application should be easily ported to any other other processor. The use of RTEMS allows the development of real-time
processor. The use of RTEMS allows the development of real-time applications which can be completely independent of a particular microprocessor
applications which can be completely independent of a particular architecture.
microprocessor architecture.
Memory Requirements Memory Requirements
=================== ===================
Since memory is a critical resource in many real-time Since memory is a critical resource in many real-time embedded systems, RTEMS
embedded systems, RTEMS was specifically designed to automatically was specifically designed to automatically leave out all services that are not
leave out all services that are not required from the run-time required from the run-time environment. Features such as networking, various
environment. Features such as networking, various fileystems, fileystems, and many other features are completely optional. This allows the
and many other features are completely optional. This allows application designer the flexibility to tailor RTEMS to most efficiently meet
the application designer the flexibility to tailor RTEMS to most system requirements while still satisfying even the most stringent memory
efficiently meet system requirements while still satisfying even constraints. As a result, the size of the RTEMS executive is application
the most stringent memory constraints. As a result, the size dependent.
of the RTEMS executive is application dependent.
RTEMS requires RAM to manage each instance of an RTEMS object RTEMS requires RAM to manage each instance of an RTEMS object that is created.
that is created. Thus the more RTEMS objects an application Thus the more RTEMS objects an application needs, the more memory that must be
needs, the more memory that must be reserved. See `Configuring a System`_. reserved. See Configuring a System_.
RTEMS utilizes memory for both code and data space. RTEMS utilizes memory for both code and data space. Although RTEMS' data space
Although RTEMS' data space must be in RAM, its code space can be must be in RAM, its code space can be located in either ROM or RAM.
located in either ROM or RAM.
Audience Audience
======== ========
This manual was written for experienced real-time This manual was written for experienced real-time software developers.
software developers. Although some background is provided, it Although some background is provided, it is assumed that the reader is familiar
is assumed that the reader is familiar with the concepts of task with the concepts of task management as well as intertask communication and
management as well as intertask communication and synchronization. Since directives, user related data structures, and examples
synchronization. Since directives, user related data are presented in C, a basic understanding of the C programming language is
structures, and examples are presented in C, a basic required to fully understand the material presented. However, because of the
understanding of the C programming language similarity of the Ada and C RTEMS implementations, users will find that the use
is required to fully and behavior of the two implementations is very similar. A working knowledge
understand the material presented. However, because of the of the target processor is helpful in understanding some of RTEMS' features. A
similarity of the Ada and C RTEMS implementations, users will thorough understanding of the executive cannot be obtained without studying the
find that the use and behavior of the two implementations is entire manual because many of RTEMS' concepts and features are interrelated.
very similar. A working knowledge of the target processor is Experienced RTEMS users will find that the manual organization facilitates its
helpful in understanding some of RTEMS' features. A thorough use as a reference document.
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 Conventions
=========== ===========
The following conventions are used in this manual: The following conventions are used in this manual:
- Significant words or phrases as well as all directive - Significant words or phrases as well as all directive names are printed in
names are printed in bold type. bold type.
- Items in bold capital letters are constants defined by - Items in bold capital letters are constants defined by RTEMS. Each language
RTEMS. Each language interface provided by RTEMS includes a interface provided by RTEMS includes a file containing the standard set of
file containing the standard set of constants, data types, and constants, data types, and structure definitions which can be incorporated
structure definitions which can be incorporated into the user into the user application.
application.
- A number of type definitions are provided by RTEMS and - A number of type definitions are provided by RTEMS and can be found in
can be found in rtems.h. rtems.h.
- The characters "0x" preceding a number indicates that - The characters "0x" preceding a number indicates that the number is in
the number is in hexadecimal format. Any other numbers are hexadecimal format. Any other numbers are assumed to be in decimal format.
assumed to be in decimal format.
Manual Organization Manual Organization
=================== ===================
This first chapter has presented the introductory and This first chapter has presented the introductory and background material for
background material for the RTEMS executive. The remaining the RTEMS executive. The remaining chapters of this manual present a detailed
chapters of this manual present a detailed description of RTEMS description of RTEMS and the environment, including run time behavior, it
and the environment, including run time behavior, it creates for creates for the user.
the user.
A chapter is dedicated to each manager and provides a A chapter is dedicated to each manager and provides a detailed discussion of
detailed discussion of each RTEMS manager and the directives each RTEMS manager and the directives which it provides. The presentation
which it provides. The presentation format for each directive format for each directive includes the following sections:
includes the following sections:
- Calling sequence - Calling sequence
@ -338,152 +314,136 @@ includes the following sections:
- Notes - Notes
The following provides an overview of the remainder The following provides an overview of the remainder of this manual:
of this manual:
Chapter 2: Chapter 2:
Key Concepts: presents an introduction to the ideas which are common Key Concepts: presents an introduction to the ideas which are common across
across multiple RTEMS managers. multiple RTEMS managers.
Chapter 3: Chapter 3:
RTEMS Data Types: describes the fundamental data types shared RTEMS Data Types: describes the fundamental data types shared by the
by the services in the RTEMS Classic API. services in the RTEMS Classic API.
Chapter 4: Chapter 4:
Scheduling Concepts: details the various RTEMS scheduling algorithms Scheduling Concepts: details the various RTEMS scheduling algorithms and
and task state transitions. task state transitions.
Chapter 5: Chapter 5:
Initialization Manager: describes the functionality and directives Initialization Manager: describes the functionality and directives provided
provided by the Initialization Manager. by the Initialization Manager.
Chapter 6: Chapter 6:
Task Manager: describes the functionality and directives provided Task Manager: describes the functionality and directives provided by the
by the Task Manager. Task Manager.
Chapter 7: Chapter 7:
Interrupt Manager: describes the functionality and directives Interrupt Manager: describes the functionality and directives provided by
provided by the Interrupt Manager. the Interrupt Manager.
Chapter 8: Chapter 8:
Clock Manager: describes the functionality and directives Clock Manager: describes the functionality and directives provided by the
provided by the Clock Manager. Clock Manager.
Chapter 9: Chapter 9:
Timer Manager: describes the functionality and directives provided Timer Manager: describes the functionality and directives provided by the
by the Timer Manager. Timer Manager.
Chapter 10: Chapter 10:
Rate Monotonic Manager: describes the functionality and directives Rate Monotonic Manager: describes the functionality and directives provided
provided by the Rate Monotonic Manager. by the Rate Monotonic Manager.
Chapter 11: Chapter 11:
Semaphore Manager: describes the functionality and directives Semaphore Manager: describes the functionality and directives provided by
provided by the Semaphore Manager. the Semaphore Manager.
Chapter 12: Chapter 12:
Barrier Manager: describes the functionality and directives Barrier Manager: describes the functionality and directives provided by the
provided by the Barrier Manager. Barrier Manager.
Chapter 13: Chapter 13:
Message Manager: describes the functionality and directives Message Manager: describes the functionality and directives provided by the
provided by the Message Manager. Message Manager.
Chapter 14: Chapter 14:
Event Manager: describes the Event Manager: describes the functionality and directives provided by the
functionality and directives provided by the Event Manager. Event Manager.
Chapter 15: Chapter 15:
Signal Manager: describes the Signal Manager: describes the functionality and directives provided by the
functionality and directives provided by the Signal Manager. Signal Manager.
Chapter 16: Chapter 16:
Partition Manager: describes the Partition Manager: describes the functionality and directives provided by
functionality and directives provided by the Partition Manager. the Partition Manager.
Chapter 17: Chapter 17:
Region Manager: describes the Region Manager: describes the functionality and directives provided by the
functionality and directives provided by the Region Manager. Region Manager.
Chapter 18: Chapter 18:
Dual-Ported Memory Manager: describes Dual-Ported Memory Manager: describes the functionality and directives
the functionality and directives provided by the Dual-Ported provided by the Dual-Ported Memory Manager.
Memory Manager.
Chapter 19: Chapter 19:
I/O Manager: describes the I/O Manager: describes the functionality and directives provided by the I/O
functionality and directives provided by the I/O Manager. Manager.
Chapter 20: Chapter 20:
Fatal Error Manager: describes the functionality and directives Fatal Error Manager: describes the functionality and directives provided by
provided by the Fatal Error Manager. the Fatal Error Manager.
Chapter 21: Chapter 21:
Board Support Packages: defines the Board Support Packages: defines the functionality required of user-supplied
functionality required of user-supplied board support packages. board support packages.
Chapter 22: Chapter 22:
User Extensions: shows the user how to User Extensions: shows the user how to extend RTEMS to incorporate custom
extend RTEMS to incorporate custom features. features.
Chapter 23: Chapter 23:
Configuring a System: details the process by which one tailors RTEMS Configuring a System: details the process by which one tailors RTEMS for a
for a particular single-processor or multiprocessor application. particular single-processor or multiprocessor application.
Chapter 24: Chapter 24:
Multiprocessing Manager: presents a Multiprocessing Manager: presents a conceptual overview of the
conceptual overview of the multiprocessing capabilities provided multiprocessing capabilities provided by RTEMS as well as describing the
by RTEMS as well as describing the Multiprocessing Multiprocessing Communications Interface Layer and Multiprocessing Manager
Communications Interface Layer and Multiprocessing Manager
directives. directives.
Chapter 25: Chapter 25:
Stack Bounds Checker: presents the capabilities of the RTEMS Stack Bounds Checker: presents the capabilities of the RTEMS task stack
task stack checker which can report stack usage as well as detect checker which can report stack usage as well as detect bounds violations.
bounds violations.
Chapter 26: Chapter 26:
CPU Usage Statistics: presents the capabilities of the CPU Usage CPU Usage Statistics: presents the capabilities of the CPU Usage statistics
statistics gathered on a per task basis along with the mechanisms gathered on a per task basis along with the mechanisms for reporting and
for reporting and resetting the statistics. resetting the statistics.
Chapter 27: Chapter 27:
Object Services: presents a collection of helper services useful Object Services: presents a collection of helper services useful when
when manipulating RTEMS objects. These include methods to assist manipulating RTEMS objects. These include methods to assist in obtaining an
in obtaining an object's name in printable form. Additional services object's name in printable form. Additional services are provided to
are provided to decompose an object Id and determine which API decompose an object Id and determine which API and object class it belongs
and object class it belongs to. to.
Chapter 28: Chapter 28:
Chains: presents the methods provided to build, iterate and Chains: presents the methods provided to build, iterate and manipulate
manipulate doubly-linked chains. This manager makes the doubly-linked chains. This manager makes the chain implementation used
chain implementation used internally by RTEMS to user space internally by RTEMS to user space applications.
applications.
Chapter 29: Chapter 29:
Timespec Helpers: presents a set of helper services useful Timespec Helpers: presents a set of helper services useful when
when manipulating POSIX ``struct timespec`` instances. manipulating POSIX ``struct timespec`` instances.
Chapter 30: Chapter 30:
Constant Bandwidth Server Scheduler API. Constant Bandwidth Server Scheduler API.
Chapter 31: Chapter 31:
Directive Status Codes: provides a definition of each of the Directive Status Codes: provides a definition of each of the directive
directive status codes referenced in this manual. status codes referenced in this manual.
Chapter 32: Chapter 32:
Example Application: provides a template for simple RTEMS applications. Example Application: provides a template for simple RTEMS applications.
Chapter 33: Chapter 33:
Glossary: defines terms used throughout this manual. 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

283
c_user/preface.rst
View File

@ -1,144 +1,123 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Preface Preface
####### #######
In recent years, the cost required to develop a In recent years, the cost required to develop a software product has increased
software product has increased significantly while the target significantly while the target hardware costs have decreased. Now a larger
hardware costs have decreased. Now a larger portion of money is portion of money is expended in developing, using, and maintaining software.
expended in developing, using, and maintaining software. The The trend in computing costs is the complete dominance of software over
trend in computing costs is the complete dominance of software hardware costs. Because of this, it is necessary that formal disciplines be
over hardware costs. Because of this, it is necessary that established to increase the probability that software is characterized by a
formal disciplines be established to increase the probability high degree of correctness, maintainability, and portability. In addition,
that software is characterized by a high degree of correctness, these disciplines must promote practices that aid in the consistent and orderly
maintainability, and portability. In addition, these development of a software system within schedule and budgetary constraints. To
disciplines must promote practices that aid in the consistent be effective, these disciplines must adopt standards which channel individual
and orderly development of a software system within schedule and software efforts toward a common goal.
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 The push for standards in the software development field has been met with
field has been met with various degrees of success. The various degrees of success. The Microprocessor Operating Systems Interfaces
Microprocessor Operating Systems Interfaces (MOSI) effort has (MOSI) effort has experienced only limited success. As popular as the UNIX
experienced only limited success. As popular as the UNIX operating system has grown, the attempt to develop a standard interface
operating system has grown, the attempt to develop a standard definition to allow portable application development has only recently begun to
interface definition to allow portable application development produce the results needed in this area. Unfortunately, very little effort has
has only recently begun to produce the results needed in this been expended to provide standards addressing the needs of the real-time
area. Unfortunately, very little effort has been expended to community. Several organizations have addressed this need during recent years.
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) The Real Time Executive Interface Definition (RTEID) was developed by Motorola
was developed by Motorola with technical input from Software with technical input from Software Components Group. RTEID was adopted by the
Components Group. RTEID was adopted by the VMEbus International VMEbus International Trade Association (VITA) as a baseline draft for their
Trade Association (VITA) as a baseline draft for their proposed proposed standard multiprocessor, real-time executive interface, Open Real-Time
standard multiprocessor, real-time executive interface, Open Kernel Interface Definition (ORKID). These two groups are currently working
Real-Time Kernel Interface Definition (ORKID). These two groups together with the IEEE P1003.4 committee to insure that the functionality of
are currently working together with the IEEE P1003.4 committee their proposed standards is adopted as the real-time extensions to POSIX.
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 This emerging standard defines an interface for the development of real-time
development of real-time software to ease the writing of software to ease the writing of real-time application programs that are
real-time application programs that are directly portable across directly portable across multiple real-time executive implementations. This
multiple real-time executive implementations. This interface interface includes both the source code interfaces and run-time behavior as
includes both the source code interfaces and run-time behavior seen by a real-time application. It does not include the details of how a
as seen by a real-time application. It does not include the kernel implements these functions. The standard's goal is to serve as a
details of how a kernel implements these functions. The complete definition of external interfaces so that application code that
standard's goal is to serve as a complete definition of external conforms to these interfaces will execute properly in all real-time executive
interfaces so that application code that conforms to these environments. With the use of a standards compliant executive, routines that
interfaces will execute properly in all real-time executive acquire memory blocks, create and manage message queues, establish and use
environments. With the use of a standards compliant executive, semaphores, and send and receive signals need not be redeveloped for a
routines that acquire memory blocks, create and manage message different real-time environment as long as the new environment is compliant
queues, establish and use semaphores, and send and receive with the standard. Software developers need only concentrate on the hardware
signals need not be redeveloped for a different real-time dependencies of the real-time system. Furthermore, most hardware dependencies
environment as long as the new environment is compliant with the for real-time applications can be localized to the device drivers.
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 A compliant executive provides simple and flexible real-time multiprocessing.
real-time multiprocessing. It easily lends itself to both It easily lends itself to both tightly-coupled and loosely-coupled
tightly-coupled and loosely-coupled configurations (depending on configurations (depending on the system hardware configuration). Objects such
the system hardware configuration). Objects such as tasks, as tasks, queues, events, signals, semaphores, and memory blocks can be
queues, events, signals, semaphores, and memory blocks can be designated as global objects and accessed by any task regardless of which
designated as global objects and accessed by any task regardless processor the object and the accessing task reside.
of which processor the object and the accessing task reside.
The acceptance of a standard for real-time executives The acceptance of a standard for real-time executives will produce the same
will produce the same advantages enjoyed from the push for UNIX advantages enjoyed from the push for UNIX standardization by AT&T's System V
standardization by AT&T's System V Interface Definition and Interface Definition and IEEE's POSIX efforts. A compliant multiprocessing
IEEE's POSIX efforts. A compliant multiprocessing executive executive will allow close coupling between UNIX systems and real-time
will allow close coupling between UNIX systems and real-time executives to provide the many benefits of the UNIX development environment to
executives to provide the many benefits of the UNIX development be applied to real-time software development. Together they provide the
environment to be applied to real-time software development. necessary laboratory environment to implement real-time, distributed, embedded
Together they provide the necessary laboratory environment to systems using a wide variety of computer architectures.
implement real-time, distributed, embedded systems using a wide
variety of computer architectures.
A study was completed in 1988, within the Research, A study was completed in 1988, within the Research, Development, and
Development, and Engineering Center, U.S. Army Missile Command, Engineering Center, U.S. Army Missile Command, which compared the various
which compared the various aspects of the Ada programming aspects of the Ada programming language as they related to the application of
language as they related to the application of Ada code in Ada code in distributed and/or multiple processing systems. Several critical
distributed and/or multiple processing systems. Several conclusions were derived from the study. These conclusions have a major impact
critical conclusions were derived from the study. These on the way the Army develops application software for embedded
conclusions have a major impact on the way the Army develops applications. These impacts apply to both in-house software development and
application software for embedded applications. These impacts contractor developed software.
apply to both in-house software development and contractor
developed software.
A conclusion of the analysis, which has been A conclusion of the analysis, which has been previously recognized by other
previously recognized by other agencies attempting to utilize agencies attempting to utilize Ada in a distributed or multiprocessing
Ada in a distributed or multiprocessing environment, is that the environment, is that the Ada programming language does not adequately support
Ada programming language does not adequately support multiprocessing. Ada does provide a mechanism for multi-tasking, however, this
multiprocessing. Ada does provide a mechanism for capability exists only for a single processor system. The language also does
multi-tasking, however, this capability exists only for a single not have inherent capabilities to access global named variables, flags or
processor system. The language also does not have inherent program code. These critical features are essential in order for data to be
capabilities to access global named variables, flags or program shared between processors. However, these drawbacks do have workarounds which
code. These critical features are essential in order for data are sometimes awkward and defeat the intent of software maintainability and
to be shared between processors. However, these drawbacks do portability goals.
have workarounds which are sometimes awkward and defeat the
intent of software maintainability and portability goals.
Another conclusion drawn from the analysis, was that Another conclusion drawn from the analysis, was that the run time executives
the run time executives being delivered with the Ada compilers being delivered with the Ada compilers were too slow and inefficient to be used
were too slow and inefficient to be used in modern missile in modern missile systems. A run time executive is the core part of the run
systems. A run time executive is the core part of the run time time system code, or operating system code, that controls task scheduling,
system code, or operating system code, that controls task input/output management and memory management. Traditionally, whenever
scheduling, input/output management and memory management. efficient executive (also known as kernel) code was required by the
Traditionally, whenever efficient executive (also known as application, the user developed in-house software. This software was usually
kernel) code was required by the application, the user developed written in assembly language for optimization.
in-house software. This software was usually written in
assembly language for optimization.
Because of this shortcoming in the Ada programming Because of this shortcoming in the Ada programming language, software
language, software developers in research and development and developers in research and development and contractors for project managed
contractors for project managed systems, are mandated by systems, are mandated by technology to purchase and utilize off-the-shelf third
technology to purchase and utilize off-the-shelf third party party kernel code. The contractor, and eventually the Government, must pay a
kernel code. The contractor, and eventually the Government, licensing fee for every copy of the kernel code used in an embedded system.
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 The main drawback to this development environment is that the Government does
that the Government does not own, nor has the right to modify not own, nor has the right to modify code contained within the kernel. V&V
code contained within the kernel. V&V techniques in this techniques in this situation are more difficult than if the complete source
situation are more difficult than if the complete source code code were available. Responsibility for system failures due to faulty software
were available. Responsibility for system failures due to faulty is yet another area to be resolved under this environment.
software is yet another area to be resolved under this
environment.
The Guidance and Control Directorate began a software The Guidance and Control Directorate began a software development effort to
development effort to address these problems. A project to address these problems. A project to develop an experimental run time kernel
develop an experimental run time kernel was begun that will was begun that will eliminate the major drawbacks of the Ada programming
eliminate the major drawbacks of the Ada programming language language mentioned above. The Real Time Executive for Multiprocessor Systems
mentioned above. The Real Time Executive for Multiprocessor Systems (RTEMS) provides full capabilities for management of tasks, interrupts, time,
(RTEMS) provides full capabilities for management of tasks, and multiple processors in addition to those features typical of generic
interrupts, time, and multiple processors in addition to those operating systems. The code is Government owned, so no licensing fees are
features typical of generic operating systems. The code is necessary. RTEMS has been implemented in both the Ada and C programming
Government owned, so no licensing fees are necessary. RTEMS has languages. It has been ported to the following processor families:
been implemented in both the Ada and C programming languages.
It has been ported to the following processor families: - Adapteva Epiphany
- Altera NIOS II - Altera NIOS II
@ -162,6 +141,10 @@ It has been ported to the following processor families:
- MIPS - MIPS
- Moxie Processor
- OpenRISC
- PowerPC - PowerPC
- Renesas (formerly Hitachi) SuperH - Renesas (formerly Hitachi) SuperH
@ -172,38 +155,20 @@ It has been ported to the following processor families:
- SPARC v7, v8, and V9 - SPARC v7, v8, and V9
Support for other processor families, including RISC, CISC, and DSP, is Since almost all of RTEMS is written in a high level language, ports to
planned. Since almost all of RTEMS is written in a high level language, additional processor families require minimal effort.
ports to additional processor families require minimal effort.
RTEMS multiprocessor support is capable of handling RTEMS multiprocessor support is capable of handling either homogeneous or
either homogeneous or heterogeneous systems. The kernel heterogeneous systems. The kernel automatically compensates for architectural
automatically compensates for architectural differences (byte differences (byte swapping, etc.) between processors. This allows a much
swapping, etc.) between processors. This allows a much easier easier transition from one processor family to another without a major system
transition from one processor family to another without a major redesign.
system redesign.
Since the proposed standards are still in draft form, Since the proposed standards are still in draft form, RTEMS cannot and does not
RTEMS cannot and does not claim compliance. However, the status claim compliance. However, the status of the standard is being carefully
of the standard is being carefully monitored to guarantee that monitored to guarantee that RTEMS provides the functionality specified in the
RTEMS provides the functionality specified in the standard. standard. Once approved, RTEMS will be made compliant.
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
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.

1116
c_user/rate_monotonic_manager.rst
View File

File diff suppressed because it is too large Load Diff

487
c_user/rtems_data_types.rst
View File

@ -1,379 +1,386 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
RTEMS Data Types RTEMS Data Types
################ ################
Introduction Introduction
============ ============
This chapter contains a complete list of the RTEMS primitive This chapter contains a complete list of the RTEMS primitive data types in
data types in alphabetical order. This is intended to be alphabetical order. This is intended to be an overview and the user is
an overview and the user is encouraged to look at the appropriate encouraged to look at the appropriate chapters in the manual for more
chapters in the manual for more information about the information about the usage of the various data types.
usage of the various data types.
List of Data Types List of Data Types
================== ==================
The following is a complete list of the RTEMS primitive The following is a complete list of the RTEMS primitive data types in
data types in alphabetical order: alphabetical order:
- .. index:: rtems_address .. index:: rtems_address
``rtems_address`` is the data type used to manage ``rtems_address``
addresses. It is equivalent to The data type used to manage addresses. It is equivalent to a ``void *``
a "void \*" pointer. pointer.
- .. index:: rtems_asr .. index:: rtems_asr
``rtems_asr`` is the return type for an ``rtems_asr``
RTEMS ASR. The return type for an RTEMS ASR.
- .. index:: rtems_asr_entry .. index:: rtems_asr_entry
``rtems_asr_entry`` is the address of ``rtems_asr_entry``
the entry point to an RTEMS ASR. The address of the entry point to an RTEMS ASR.
- .. index:: rtems_attribute .. index:: rtems_attribute
``rtems_attribute`` is the data type used ``rtems_attribute``
to manage the attributes for RTEMS objects. It is primarily The data type used to manage the attributes for RTEMS objects. It is
used as an argument to object create routines to specify primarily used as an argument to object create routines to specify
characteristics of the new object. characteristics of the new object.
- .. index:: rtems_boolean .. index:: rtems_boolean
``rtems_boolean`` may only take on the ``rtems_boolean``
values of ``TRUE`` and ``FALSE``. May only take on the values of ``TRUE`` and ``FALSE``. This type is
This type is deprecated. Use "bool" instead. deprecated. Use ``bool`` instead.
- .. index:: rtems_context .. index:: rtems_context
``rtems_context`` is the CPU dependent ``rtems_context``
data structure used to manage the integer and system The CPU dependent data structure used to manage the integer and system
register portion of each task's context. register portion of each task's context.
- .. index:: rtems_context_fp .. index:: rtems_context_fp
``rtems_context_fp`` is the CPU dependent ``rtems_context_fp``
data structure used to manage the floating point portion of The CPU dependent data structure used to manage the floating point portion of
each task's context. each task's context.
- .. index:: rtems_device_driver .. index:: rtems_device_driver
``rtems_device_driver`` is the ``rtems_device_driver``
return type for a RTEMS device driver routine. The return type for a RTEMS device driver routine.
- .. index:: rtems_device_driver_entry .. index:: rtems_device_driver_entry
``rtems_device_driver_entry`` is the ``rtems_device_driver_entry``
entry point to a RTEMS device driver routine. The entry point to a RTEMS device driver routine.
- .. index:: rtems_device_major_number .. index:: rtems_device_major_number
``rtems_device_major_number`` is the ``rtems_device_major_number``
data type used to manage device major numbers. The data type used to manage device major numbers.
- .. index:: rtems_device_minor_number .. index:: rtems_device_minor_number
``rtems_device_minor_number`` is the ``rtems_device_minor_number``
data type used to manage device minor numbers. The data type used to manage device minor numbers.
- .. index:: rtems_double .. index:: rtems_double
``rtems_double`` is the RTEMS data ``rtems_double``
type that corresponds to double precision floating point The RTEMS data type that corresponds to double precision floating point on
on the target hardware. the target hardware. This type is deprecated. Use ``double`` instead.
This type is deprecated. Use "double" instead.
- .. index:: rtems_event_set .. index:: rtems_event_set
``rtems_event_set`` is the data ``rtems_event_set``
type used to manage and manipulate RTEMS event sets The data type used to manage and manipulate RTEMS event sets with the Event
with the Event Manager. Manager.
- .. index:: rtems_extension .. index:: rtems_extension
``rtems_extension`` is the return type ``rtems_extension``
for RTEMS user extension routines. The return type for RTEMS user extension routines.
- .. index:: rtems_fatal_extension .. index:: rtems_fatal_extension
``rtems_fatal_extension`` is the ``rtems_fatal_extension``
entry point for a fatal error user extension handler routine.
- .. index:: rtems_id The entry point for a fatal error user extension handler routine.
``rtems_id`` is the data type used .. index:: rtems_id
to manage and manipulate RTEMS object IDs.
- .. index:: rtems_interrupt_frame ``rtems_id``
The data type used to manage and manipulate RTEMS object IDs.
``rtems_interrupt_frame`` is the .. index:: rtems_interrupt_frame
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_frame``
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.
``rtems_interrupt_level`` is the .. index:: rtems_interrupt_level
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_interrupt_level``
``rtems_interval`` is the data The data structure used with the ``rtems_interrupt_disable``,
type used to manage and manipulate time intervals. ``rtems_interrupt_enable``, and ``rtems_interrupt_flash`` routines. This
Intervals are non-negative integers used to measure data type is CPU dependent and usually corresponds to the contents of the
the length of time in clock ticks. processor register containing the interrupt mask level.
- .. index:: rtems_isr .. index:: rtems_interval
``rtems_isr`` is the return type ``rtems_interval``
of a function implementing an RTEMS ISR. 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_entry .. index:: rtems_isr
``rtems_isr_entry`` is the address of ``rtems_isr``
the entry point to an RTEMS ISR. It is equivalent to the The return type of a function implementing an RTEMS ISR.
.. index:: rtems_isr_entry
``rtems_isr_entry``
The address of the entry point to an RTEMS ISR. It is equivalent to the
entry point of the function implementing the ISR. entry point of the function implementing the ISR.
- .. index:: rtems_mp_packet_classes .. index:: rtems_mp_packet_classes
``rtems_mp_packet_classes`` is the ``rtems_mp_packet_classes``
enumerated type which specifies the categories of The enumerated type which specifies the categories of multiprocessing
multiprocessing messages. For example, one of the messages. For example, one of the classes is for messages that must be
classes is for messages that must be processed by processed by the Task Manager.
the Task Manager.
- .. index:: rtems_mode .. index:: rtems_mode
``rtems_mode`` is the data type ``rtems_mode``
used to manage and dynamically manipulate the execution The data type used to manage and dynamically manipulate the execution mode of
mode of an RTEMS task. an RTEMS task.
- .. index:: rtems_mpci_entry .. index:: rtems_mpci_entry
``rtems_mpci_entry`` is the return type ``rtems_mpci_entry``
of an RTEMS MPCI routine. The return type of an RTEMS MPCI routine.
- .. index:: rtems_mpci_get_packet_entry .. index:: rtems_mpci_get_packet_entry
``rtems_mpci_get_packet_entry`` is the address of ``rtems_mpci_get_packet_entry``
the entry point to the get packet routine for an MPCI implementation. The address of the entry point to the get packet routine for an MPCI
implementation.
- .. index:: rtems_mpci_initialization_entry .. index:: rtems_mpci_initialization_entry
``rtems_mpci_initialization_entry`` is the address of ``rtems_mpci_initialization_entry``
the entry point to the initialization routine for an MPCI implementation. The address of the entry point to the initialization routine for an MPCI
implementation.
- .. index:: rtems_mpci_receive_packet_entry .. index:: rtems_mpci_receive_packet_entry
``rtems_mpci_receive_packet_entry`` is the address of ``rtems_mpci_receive_packet_entry``
the entry point to the receive packet routine for an MPCI implementation. The address of the entry point to the receive packet routine for an MPCI
implementation.
- .. index:: rtems_mpci_return_packet_entry .. index:: rtems_mpci_return_packet_entry
``rtems_mpci_return_packet_entry`` is the address of ``rtems_mpci_return_packet_entry``
the entry point to the return packet routine for an MPCI implementation. The address of the entry point to the return packet routine for an MPCI
implementation.
- .. index:: rtems_mpci_send_packet_entry .. index:: rtems_mpci_send_packet_entry
``rtems_mpci_send_packet_entry`` is the address of ``rtems_mpci_send_packet_entry``
the entry point to the send packet routine for an MPCI implementation. The address of the entry point to the send packet routine for an MPCI
implementation.
- .. index:: rtems_mpci_table .. index:: rtems_mpci_table
``rtems_mpci_table`` is the data structure ``rtems_mpci_table``
containing the configuration information for an MPCI. The data structure containing the configuration information for an MPCI.
- .. index:: rtems_name .. index:: rtems_name
``rtems_name`` is the data type used to ``rtems_name``
contain the name of a Classic API object. It is an unsigned The data type used to contain the name of a Classic API object. It is an
thirty-two bit integer which can be treated as a numeric unsigned thirty-two bit integer which can be treated as a numeric value or
value or initialized using ``rtems_build_name`` to initialized using ``rtems_build_name`` to contain four ASCII characters.
contain four ASCII characters.
- .. index:: rtems_option .. index:: rtems_option
``rtems_option`` is the data type ``rtems_option``
used to specify which behavioral options the caller desires. The data type used to specify which behavioral options the caller desires.
It is commonly used with potentially blocking directives to specify It is commonly used with potentially blocking directives to specify whether
whether the caller is willing to block or return immediately with an error the caller is willing to block or return immediately with an error indicating
indicating that the resource was not available. that the resource was not available.
- .. index:: rtems_packet_prefix .. index:: rtems_packet_prefix
``rtems_packet_prefix`` is the data structure ``rtems_packet_prefix``
that defines the first bytes in every packet sent between nodes The data structure that defines the first bytes in every packet sent between
in an RTEMS multiprocessor system. It contains routing information nodes in an RTEMS multiprocessor system. It contains routing information
that is expected to be used by the MPCI layer. that is expected to be used by the MPCI layer.
- .. index:: rtems_signal_set .. index:: rtems_signal_set
``rtems_signal_set`` is the data ``rtems_signal_set``
type used to manage and manipulate RTEMS signal sets The data type used to manage and manipulate RTEMS signal sets with the Signal
with the Signal Manager. Manager.
- .. index:: int8_t .. index:: int8_t
``int8_t`` is the C99 data type that corresponds to signed eight ``int8_t``
bit integers. This data type is defined by RTEMS in a manner that The C99 data type that corresponds to signed eight bit integers. This data
ensures it is portable across different target processors. type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: int16_t .. index:: int16_t
``int16_t`` is the C99 data type that corresponds to signed ``int16_t``
sixteen bit integers. This data type is defined by RTEMS in a manner The C99 data type that corresponds to signed sixteen bit integers. This data
that ensures it is portable across different target processors. type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: int32_t .. index:: int32_t
``int32_t`` is the C99 data type that corresponds to signed ``int32_t``
thirty-two bit integers. This data type is defined by RTEMS in a manner The C99 data type that corresponds to signed thirty-two bit integers. This
that ensures it is portable across different target processors. data type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: int64_t .. index:: int64_t
``int64_t`` is the C99 data type that corresponds to signed ``int64_t``
sixty-four bit integers. This data type is defined by RTEMS in a manner The C99 data type that corresponds to signed sixty-four bit integers. This
that ensures it is portable across different target processors. data type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: rtems_single .. index:: rtems_single
``rtems_single`` is the RTEMS data ``rtems_single``
type that corresponds to single precision floating point The RTEMS data type that corresponds to single precision floating point on
on the target hardware. the target hardware. This type is deprecated. Use ``float`` instead.
This type is deprecated. Use "float" instead.
- .. index:: rtems_status_codes .. index:: rtems_status_codes
``rtems_status_codes`` is the return type for most ``rtems_status_codes``
RTEMS services. This is an enumerated type of approximately twenty-five The return type for most RTEMS services. This is an enumerated type of
values. In general, when a service returns a particular status code, it approximately twenty-five values. In general, when a service returns a
indicates that a very specific error condition has occurred. particular status code, it indicates that a very specific error condition has
occurred.
- .. index:: rtems_task .. index:: rtems_task
``rtems_task`` is the return type for an ``rtems_task``
RTEMS Task. The return type for an RTEMS Task.
- .. index:: rtems_task_argument .. index:: rtems_task_argument
``rtems_task_argument`` is the data ``rtems_task_argument``
type for the argument passed to each RTEMS task. In RTEMS 4.7 The data type for the argument passed to each RTEMS task. In RTEMS 4.7 and
and older, this is an unsigned thirty-two bit integer. In older, this is an unsigned thirty-two bit integer. In RTEMS 4.8 and newer,
RTEMS 4.8 and newer, this is based upon the C99 type ``uintptr_t`` this is based upon the C99 type ``uintptr_t`` which is guaranteed to be an
which is guaranteed to be an integer large enough to hold a integer large enough to hold a pointer on the target architecture.
pointer on the target architecture.
- .. index:: rtems_task_begin_extension .. index:: rtems_task_begin_extension
``rtems_task_begin_extension`` is the ``rtems_task_begin_extension``
entry point for a task beginning execution user extension handler routine. The entry point for a task beginning execution user extension handler
routine.
- .. index:: rtems_task_create_extension .. index:: rtems_task_create_extension
``rtems_task_create_extension`` is the ``rtems_task_create_extension``
entry point for a task creation execution user extension handler routine. The entry point for a task creation execution user extension handler routine.
- .. index:: rtems_task_delete_extension .. index:: rtems_task_delete_extension
``rtems_task_delete_extension`` is the ``rtems_task_delete_extension``
entry point for a task deletion user extension handler routine. The entry point for a task deletion user extension handler routine.
- .. index:: rtems_task_entry .. index:: rtems_task_entry
``rtems_task_entry`` is the address of ``rtems_task_entry``
the entry point to an RTEMS ASR. It is equivalent to the The address of the entry point to an RTEMS ASR. It is equivalent to the
entry point of the function implementing the ASR. entry point of the function implementing the ASR.
- .. index:: rtems_task_exitted_extension .. index:: rtems_task_exitted_extension
``rtems_task_exitted_extension`` is the ``rtems_task_exitted_extension``
entry point for a task exitted user extension handler routine. The entry point for a task exitted user extension handler routine.
- .. index:: rtems_task_priority .. index:: rtems_task_priority
``rtems_task_priority`` is the data type ``rtems_task_priority``
used to manage and manipulate task priorities. The data type used to manage and manipulate task priorities.
- .. index:: rtems_task_restart_extension .. index:: rtems_task_restart_extension
``rtems_task_restart_extension`` is the ``rtems_task_restart_extension``
entry point for a task restart user extension handler routine. The entry point for a task restart user extension handler routine.
- .. index:: rtems_task_start_extension .. index:: rtems_task_start_extension
``rtems_task_start_extension`` is the ``rtems_task_start_extension``
entry point for a task start user extension handler routine. The entry point for a task start user extension handler routine.
- .. index:: rtems_task_switch_extension .. index:: rtems_task_switch_extension
``rtems_task_switch_extension`` is the ``rtems_task_switch_extension``
entry point for a task context switch user extension handler routine. The entry point for a task context switch user extension handler routine.
- .. index:: rtems_tcb .. index:: rtems_tcb
``rtems_tcb`` is the data structure associated ``rtems_tcb``
with each task in an RTEMS system. The data structure associated with each task in an RTEMS system.
- .. index:: rtems_time_of_day .. index:: rtems_time_of_day
``rtems_time_of_day`` is the data structure ``rtems_time_of_day``
used to manage and manipulate calendar time in RTEMS. The data structure used to manage and manipulate calendar time in RTEMS.
- .. index:: rtems_timer_service_routine .. index:: rtems_timer_service_routine
``rtems_timer_service_routine`` is the ``rtems_timer_service_routine``
return type for an RTEMS Timer Service Routine. The return type for an RTEMS Timer Service Routine.
- .. index:: rtems_timer_service_routine_entry .. index:: rtems_timer_service_routine_entry
``rtems_timer_service_routine_entry`` is the address of ``rtems_timer_service_routine_entry``
the entry point to an RTEMS TSR. It is equivalent to the The address of the entry point to an RTEMS TSR. It is equivalent to the
entry point of the function implementing the TSR. entry point of the function implementing the TSR.
- .. index:: rtems_vector_number .. index:: rtems_vector_number
``rtems_vector_number`` is the data ``rtems_vector_number``
type used to manage and manipulate interrupt vector numbers. The data type used to manage and manipulate interrupt vector numbers.
- .. index:: uint8_t .. index:: uint8_t
``uint8_t`` is the C99 data type that corresponds to unsigned ``uint8_t``
eight bit integers. This data type is defined by RTEMS in a manner that The C99 data type that corresponds to unsigned eight bit integers. This data
ensures it is portable across different target processors. type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: uint16_t .. index:: uint16_t
``uint16_t`` is the C99 data type that corresponds to unsigned ``uint16_t``
sixteen bit integers. This data type is defined by RTEMS in a manner The C99 data type that corresponds to unsigned sixteen bit integers. This
that ensures it is portable across different target processors. data type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: uint32_t .. index:: uint32_t
``uint32_t`` is the C99 data type that corresponds to unsigned ``uint32_t``
thirty-two bit integers. This data type is defined by RTEMS in a manner The C99 data type that corresponds to unsigned thirty-two bit integers. This
that ensures it is portable across different target processors. data type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: uint64_t .. index:: uint64_t
``uint64_t`` is the C99 data type that corresponds to unsigned ``uint64_t``
sixty-four bit integers. This data type is defined by RTEMS in a manner The C99 data type that corresponds to unsigned sixty-four bit integers. This
that ensures it is portable across different target processors. data type is defined by RTEMS in a manner that ensures it is portable across
different target processors.
- .. index:: uintptr_t .. 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.
``uintptr_t``
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.

BIN
c_user/rtemsarc.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.6 KiB

BIN
c_user/rtemspie.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

640
c_user/scheduling_concepts.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Scheduling Concepts Scheduling Concepts
################### ###################
@ -7,102 +11,101 @@ Scheduling Concepts
Introduction Introduction
============ ============
The concept of scheduling in real-time systems dictates the ability to The concept of scheduling in real-time systems dictates the ability to provide
provide immediate response to specific external events, particularly immediate response to specific external events, particularly the necessity of
the necessity of scheduling tasks to run within a specified time limit scheduling tasks to run within a specified time limit after the occurrence of
after the occurrence of an event. For example, software embedded in an event. For example, software embedded in life-support systems used to
life-support systems used to monitor hospital patients must take instant monitor hospital patients must take instant action if a change in the patient's
action if a change in the patient's status is detected. status is detected.
The component of RTEMS responsible for providing this capability is The component of RTEMS responsible for providing this capability is
appropriately called the scheduler. The scheduler's sole purpose is appropriately called the scheduler. The scheduler's sole purpose is to
to allocate the all important resource of processor time to the various allocate the all important resource of processor time to the various tasks
tasks competing for attention. competing for attention.
Scheduling Algorithms Scheduling Algorithms
===================== =====================
.. index:: scheduling algorithms .. index:: scheduling algorithms
RTEMS provides a plugin framework which allows it to support RTEMS provides a plugin framework which allows it to support multiple
multiple scheduling algorithms. RTEMS now includes multiple scheduling algorithms. RTEMS now includes multiple scheduling algorithms in the
scheduling algorithms in the SuperCore and the user can select which SuperCore and the user can select which of these they wish to use in their
of these they wish to use in their application. In addition, application. In addition, the user can implement their own scheduling
the user can implement their own scheduling algorithm and algorithm and configure RTEMS to use it.
configure RTEMS to use it.
Supporting multiple scheduling algorithms gives the end user the Supporting multiple scheduling algorithms gives the end user the option to
option to select the algorithm which is most appropriate to their use select the algorithm which is most appropriate to their use case. Most
case. Most real-time operating systems schedule tasks using a priority real-time operating systems schedule tasks using a priority based algorithm,
based algorithm, possibly with preemption control. The classic possibly with preemption control. The classic RTEMS scheduling algorithm which
RTEMS scheduling algorithm which was the only algorithm available was the only algorithm available in RTEMS 4.10 and earlier, is a priority based
in RTEMS 4.10 and earlier, is a priority based scheduling algorithm. scheduling algorithm. This scheduling algoritm is suitable for single core
This scheduling algoritm is suitable for single core (e.g. non-SMP) (e.g. non-SMP) systems and is now known as the *Deterministic Priority
systems and is now known as the *Deterministic Priority Scheduler*. Scheduler*. Unless the user configures another scheduling algorithm, RTEMS
Unless the user configures another scheduling algorithm, RTEMS will use will use this on single core systems.
this on single core systems.
Priority Scheduling Priority Scheduling
------------------- -------------------
.. index:: priority scheduling .. index:: priority scheduling
When using priority based scheduling, RTEMS allocates the processor using When using priority based scheduling, RTEMS allocates the processor using a
a priority-based, preemptive algorithm augmented to provide round-robin priority-based, preemptive algorithm augmented to provide round-robin
characteristics within individual priority groups. The goal of this characteristics within individual priority groups. The goal of this algorithm
algorithm is to guarantee that the task which is executing on the is to guarantee that the task which is executing on the processor at any point
processor at any point in time is the one with the highest priority in time is the one with the highest priority among all tasks in the ready
among all tasks in the ready state. state.
When a task is added to the ready chain, it is placed behind all other When a task is added to the ready chain, it is placed behind all other tasks of
tasks of the same priority. This rule provides a round-robin within the same priority. This rule provides a round-robin within priority group
priority group scheduling characteristic. This means that in a group of scheduling characteristic. This means that in a group of equal priority tasks,
equal priority tasks, tasks will execute in the order they become ready tasks will execute in the order they become ready or FIFO order. Even though
or FIFO order. Even though there are ways to manipulate and adjust task there are ways to manipulate and adjust task priorities, the most important
priorities, the most important rule to remember is: rule to remember is:
- *Priority based scheduling algorithms will always select the .. note::
highest priority task that is ready to run when allocating the processor
to a task.*
Priority scheduling is the most commonly used scheduling algorithm. Priority based scheduling algorithms will always select the highest priority
It should be used by applications in which multiple tasks contend for task that is ready to run when allocating the processor to a task.
CPU time or other resources and there is a need to ensure certain tasks
are given priority over other tasks. 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 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. 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 - The least efficient method is to randomly place tasks in the ready chain
chain forcing the scheduler to scan the entire chain to determine which forcing the scheduler to scan the entire chain to determine which task
task receives the processor. receives the processor.
- A more efficient method is to schedule the task by placing it - A more efficient method is to schedule the task by placing it in the proper
in the proper place on the ready chain based on the designated scheduling place on the ready chain based on the designated scheduling criteria at the
criteria at the time it enters the ready state. Thus, when the processor time it enters the ready state. Thus, when the processor is free, the first
is free, the first task on the ready chain is allocated the processor. task on the ready chain is allocated the processor.
- Another mechanism is to maintain a list of FIFOs per priority. - Another mechanism is to maintain a list of FIFOs per priority. When a task
When a task is readied, it is placed on the rear of the FIFO for its is readied, it is placed on the rear of the FIFO for its priority. This
priority. This method is often used with a bitmap to assist in locating method is often used with a bitmap to assist in locating which FIFOs have
which FIFOs have ready tasks on them. ready tasks on them.
RTEMS currently includes multiple priority based scheduling algorithms RTEMS currently includes multiple priority based scheduling algorithms as well
as well as other algorithms which incorporate deadline. Each algorithm as other algorithms which incorporate deadline. Each algorithm is discussed in
is discussed in the following sections. the following sections.
Deterministic Priority Scheduler Deterministic Priority Scheduler
-------------------------------- --------------------------------
This is the scheduler implementation which has always been in RTEMS. This is the scheduler implementation which has always been in RTEMS. After the
After the 4.10 release series, it was factored into pluggable scheduler 4.10 release series, it was factored into pluggable scheduler selection. It
selection. It schedules tasks using a priority based algorithm which schedules tasks using a priority based algorithm which takes into account
takes into account preemption. It is implemented using an array of FIFOs preemption. It is implemented using an array of FIFOs with a FIFO per
with a FIFO per priority. It maintains a bitmap which is used to track priority. It maintains a bitmap which is used to track which priorities have
which priorities have ready tasks. ready tasks.
This algorithm is deterministic (e.g. predictable and fixed) in execution This algorithm is deterministic (e.g. predictable and fixed) in execution time.
time. This comes at the cost of using slightly over three (3) kilobytes This comes at the cost of using slightly over three (3) kilobytes of RAM on a
of RAM on a system configured to support 256 priority levels. system configured to support 256 priority levels.
This scheduler is only aware of a single core. This scheduler is only aware of a single core.
@ -110,94 +113,92 @@ Simple Priority Scheduler
------------------------- -------------------------
This scheduler implementation has the same behaviour as the Deterministic This scheduler implementation has the same behaviour as the Deterministic
Priority Scheduler but uses only one linked list to manage all ready Priority Scheduler but uses only one linked list to manage all ready tasks.
tasks. When a task is readied, a linear search of that linked list is When a task is readied, a linear search of that linked list is performed to
performed to determine where to insert the newly readied task. determine where to insert the newly readied task.
This algorithm uses much less RAM than the Deterministic Priority This algorithm uses much less RAM than the Deterministic Priority Scheduler but
Scheduler but is *O(n)* where *n* is the number of ready tasks. is *O(n)* where *n* is the number of ready tasks. In a small system with a
In a small system with a small number of tasks, this will not be a small number of tasks, this will not be a performance issue. Reducing RAM
performance issue. Reducing RAM consumption is often critical in small consumption is often critical in small systems which are incapable of
systems which are incapable of supporting a large number of tasks. supporting a large number of tasks.
This scheduler is only aware of a single core. This scheduler is only aware of a single core.
Simple SMP Priority Scheduler Simple SMP Priority Scheduler
----------------------------- -----------------------------
This scheduler is based upon the Simple Priority Scheduler and is designed This scheduler is based upon the Simple Priority Scheduler and is designed to
to have the same behaviour on a single core system. But this scheduler have the same behaviour on a single core system. But this scheduler is capable
is capable of scheduling threads across multiple cores in an SMP system. of scheduling threads across multiple cores in an SMP system. When given a
When given a choice of replacing one of two threads at equal priority choice of replacing one of two threads at equal priority on different cores,
on different cores, this algorithm favors replacing threads which are this algorithm favors replacing threads which are preemptible and have executed
preemptible and have executed the longest. the longest.
This algorithm is non-deterministic. When scheduling, it must consider This algorithm is non-deterministic. When scheduling, it must consider which
which tasks are to be executed on each core while avoiding superfluous tasks are to be executed on each core while avoiding superfluous task
task migrations. migrations.
Earliest Deadline First Scheduler Earliest Deadline First Scheduler
--------------------------------- ---------------------------------
.. index:: earliest deadline first scheduling .. index:: earliest deadline first scheduling
This is an alternative scheduler in RTEMS for single core applications. This is an alternative scheduler in RTEMS for single core applications. The
The primary EDF advantage is high total CPU utilization (theoretically primary EDF advantage is high total CPU utilization (theoretically up to
up to 100%). It assumes that tasks have priorities equal to deadlines. 100%). It assumes that tasks have priorities equal to deadlines.
This EDF is initially preemptive, however, individual tasks may be declared This EDF is initially preemptive, however, individual tasks may be declared
not-preemptive. Deadlines are declared using only Rate Monotonic manager which not-preemptive. Deadlines are declared using only Rate Monotonic manager which
goal is to handle periodic behavior. Period is always equal to deadline. All 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. ready tasks reside in a single ready queue implemented using a red-black tree.
This implementation of EDF schedules two different types of task This implementation of EDF schedules two different types of task priority types
priority types while each task may switch between the two types within while each task may switch between the two types within its execution. If a
its execution. If a task does have a deadline declared using the Rate task does have a deadline declared using the Rate Monotonic manager, the task
Monotonic manager, the task is deadline-driven and its priority is equal is deadline-driven and its priority is equal to deadline. On the contrary if a
to deadline. On the contrary if a task does not have any deadline or task does not have any deadline or the deadline is cancelled using the Rate
the deadline is cancelled using the Rate Monotonic manager, the task is Monotonic manager, the task is considered a background task with priority equal
considered a background task with priority equal to that assigned to that assigned upon initialization in the same manner as for priority
upon initialization in the same manner as for priority scheduler. Each scheduler. Each background task is of a lower importance than each
background task is of a lower importance than each deadline-driven one deadline-driven one and is scheduled when no deadline-driven task and no higher
and is scheduled when no deadline-driven task and no higher priority priority background task is ready to run.
background task is ready to run.
Every deadline-driven scheduling algorithm requires means for tasks Every deadline-driven scheduling algorithm requires means for tasks to claim a
to claim a deadline. The Rate Monotonic Manager is responsible for deadline. The Rate Monotonic Manager is responsible for handling periodic
handling periodic execution. In RTEMS periods are equal to deadlines, execution. In RTEMS periods are equal to deadlines, thus if a task announces a
thus if a task announces a period, it has to be finished until the period, it has to be finished until the end of this period. The call of
end of this period. The call of ``rtems_rate_monotonic_period`` ``rtems_rate_monotonic_period`` passes the scheduler the length of oncoming
passes the scheduler the length of oncoming deadline. Moreover, the``rtems_rate_monotonic_cancel`` and ``rtems_rate_monotonic_delete`` deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and
calls clear the deadlines assigned to the task. ``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task.
Constant Bandwidth Server Scheduling (CBS) Constant Bandwidth Server Scheduling (CBS)
------------------------------------------ ------------------------------------------
.. index:: constant bandwidth server scheduling .. index:: constant bandwidth server scheduling
This is an alternative scheduler in RTEMS for single core applications. This is an alternative scheduler in RTEMS for single core applications. The
The CBS is a budget aware extension of EDF scheduler. The main goal of this 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 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 execution in terms of meeting deadlines must not be influenced by other tasks
tasks as if they were run on multiple independent processors. as if they were run on multiple independent processors.
Each task can be assigned a server (current implementation supports only Each task can be assigned a server (current implementation supports only one
one task per server). The server is characterized by period (deadline) task per server). The server is characterized by period (deadline) and
and computation time (budget). The ratio budget/period yields bandwidth, computation time (budget). The ratio budget/period yields bandwidth, which is
which is the fraction of CPU to be reserved by the scheduler for each the fraction of CPU to be reserved by the scheduler for each subsequent period.
subsequent period.
The CBS is equipped with a set of rules applied to tasks attached to servers 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. ensuring that deadline miss because of another task cannot occur. In case a
In case a task breaks one of the rules, its priority is pulled to background task breaks one of the rules, its priority is pulled to background until the
until the end of its period and then restored again. The rules are: end of its period and then restored again. The rules are:
- Task cannot exceed its registered budget, - Task cannot exceed its registered budget,
- Task cannot be - Task cannot be unblocked when a ratio between remaining budget and remaining
unblocked when a ratio between remaining budget and remaining deadline deadline is higher than declared bandwidth.
is higher than declared bandwidth.
The CBS provides an extensive API. Unlike EDF, the``rtems_rate_monotonic_period`` does not declare a deadline because The CBS provides an extensive API. Unlike EDF, the
it is carried out using CBS API. This call only announces next period. ``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 Scheduling Modification Mechanisms
================================== ==================================
@ -215,268 +216,249 @@ scheduling decisions:
- manual round-robin selection - manual round-robin selection
Each of these methods provides a powerful capability to customize sets Each of these methods provides a powerful capability to customize sets of tasks
of tasks to satisfy the unique and particular requirements encountered to satisfy the unique and particular requirements encountered in custom
in custom real-time applications. Although each mechanism operates real-time applications. Although each mechanism operates independently, there
independently, there is a precedence relationship which governs the is a precedence relationship which governs the effects of scheduling
effects of scheduling modifications. The evaluation order for scheduling modifications. The evaluation order for scheduling characteristics is always
characteristics is always priority, preemption mode, and timeslicing. priority, preemption mode, and timeslicing. When reading the descriptions of
When reading the descriptions of timeslicing and manual round-robin timeslicing and manual round-robin it is important to keep in mind that
it is important to keep in mind that preemption (if enabled) of a task preemption (if enabled) of a task by higher priority tasks will occur as
by higher priority tasks will occur as required, overriding the other required, overriding the other factors presented in the description.
factors presented in the description.
Task Priority and Scheduling Task Priority and Scheduling
---------------------------- ----------------------------
.. index:: task priority .. index:: task priority
The most significant task scheduling modification mechanism is the ability The most significant task scheduling modification mechanism is the ability for
for the user to assign a priority level to each individual task when it the user to assign a priority level to each individual task when it is created
is created and to alter a task's priority at run-time. RTEMS supports and to alter a task's priority at run-time. RTEMS supports up to 255 priority
up to 255 priority levels. Level 255 is the lowest priority and level levels. Level 255 is the lowest priority and level 1 is the highest.
1 is the highest.
Preemption Preemption
----------.. index:: preemption ----------
.. index:: preemption
Another way the user can alter the basic scheduling algorithm is by Another way the user can alter the basic scheduling algorithm is by
manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual
of individual tasks. If preemption is disabled for a task tasks. If preemption is disabled for a task (``RTEMS_NO_PREEMPT``), then the
(``RTEMS_NO_PREEMPT``), then the task will not relinquish task will not relinquish control of the processor until it terminates, blocks,
control of the processor until it terminates, blocks, or re-enables or re-enables preemption. Even tasks which become ready to run and possess
preemption. Even tasks which become ready to run and possess higher higher priority levels will not be allowed to execute. Note that the
priority levels will not be allowed to execute. Note that the preemption preemption setting has no effect on the manner in which a task is scheduled.
setting has no effect on the manner in which a task is scheduled.
It only applies once a task has control of the processor. It only applies once a task has control of the processor.
Timeslicing Timeslicing
-----------.. index:: timeslicing -----------
.. index:: timeslicing
.. index:: round robin scheduling .. index:: round robin scheduling
Timeslicing or round-robin scheduling is an additional method which Timeslicing or round-robin scheduling is an additional method which can be used
can be used to alter the basic scheduling algorithm. Like preemption, to alter the basic scheduling algorithm. Like preemption, timeslicing is
timeslicing is specified on a task by task basis using the timeslicing specified on a task by task basis using the timeslicing mode flag
mode flag (``RTEMS_TIMESLICE_MASK``). If timeslicing is (``RTEMS_TIMESLICE_MASK``). If timeslicing is enabled for a task
enabled for a task (``RTEMS_TIMESLICE``), then RTEMS will (``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can
limit the amount of time the task can execute before the processor is execute before the processor is allocated to another task. Each tick of the
allocated to another task. Each tick of the real-time clock reduces real-time clock reduces the currently running task's timeslice. When the
the currently running task's timeslice. When the execution time equals execution time equals the timeslice, RTEMS will dispatch another task of the
the timeslice, RTEMS will dispatch another task of the same priority same priority to execute. If there are no other tasks of the same priority
to execute. If there are no other tasks of the same priority ready to ready to execute, then the current task is allocated an additional timeslice
execute, then the current task is allocated an additional timeslice and and continues to run. Remember that a higher priority task will preempt the
continues to run. Remember that a higher priority task will preempt task (unless preemption is disabled) as soon as it is ready to run, even if the
the task (unless preemption is disabled) as soon as it is ready to run, task has not used up its entire timeslice.
even if the task has not used up its entire timeslice.
Manual Round-Robin Manual Round-Robin
------------------.. index:: manual round robin ------------------
.. index:: manual round robin
The final mechanism for altering the RTEMS scheduling algorithm is The final mechanism for altering the RTEMS scheduling algorithm is called
called manual round-robin. Manual round-robin is invoked by using the``rtems_task_wake_after`` directive with a time interval manual round-robin. Manual round-robin is invoked by using
of ``RTEMS_YIELD_PROCESSOR``. This allows a task to give the ``rtems_task_wake_after`` directive with a time interval of
up the processor and be immediately returned to the ready chain at the ``RTEMS_YIELD_PROCESSOR``. This allows a task to give up the processor and be
end of its priority group. If no other tasks of the same priority are immediately returned to the ready chain at the end of its priority group. If
ready to run, then the task does not lose control of the processor. no other tasks of the same priority are ready to run, then the task does not
lose control of the processor.
Dispatching Tasks Dispatching Tasks
=================.. index:: dispatching =================
.. index:: dispatching
The dispatcher is the RTEMS component responsible for The dispatcher is the RTEMS component responsible for allocating the processor
allocating the processor to a ready task. In order to allocate to a ready task. In order to allocate the processor to one task, it must be
the processor to one task, it must be deallocated or retrieved deallocated or retrieved from the task currently using it. This involves a
from the task currently using it. This involves a concept concept called a context switch. To perform a context switch, the dispatcher
called a context switch. To perform a context switch, the saves the context of the current task and restores the context of the task
dispatcher saves the context of the current task and restores which has been allocated to the processor. Saving and restoring a task's
the context of the task which has been allocated to the context is the storing/loading of all the essential information about a task to
processor. Saving and restoring a task's context is the enable it to continue execution without any effects of the interruption. For
storing/loading of all the essential information about a task to example, the contents of a task's register set must be the same when it is
enable it to continue execution without any effects of the given the processor as they were when it was taken away. All of the
interruption. For example, the contents of a task's register information that must be saved or restored for a context switch is located
set must be the same when it is given the processor as they were either in the TCB or on the task's stacks.
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 Tasks that utilize a numeric coprocessor and are created with the
operations during a context switch. These additional operations ``RTEMS_FLOATING_POINT`` attribute require additional operations during a
are necessary to save and restore the floating point context of``RTEMS_FLOATING_POINT`` tasks. To avoid unnecessary save context switch. These additional operations are necessary to save and restore
and restore operations, the state of the numeric coprocessor is only the floating point context of ``RTEMS_FLOATING_POINT`` tasks. To avoid
saved when a ``RTEMS_FLOATING_POINT`` task is dispatched unnecessary save and restore operations, the state of the numeric coprocessor
and that task was not the last task to utilize the 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 Task State Transitions
======================.. index:: task state transitions ======================
.. index:: task state transitions
Tasks in an RTEMS system must always be in one of the Tasks in an RTEMS system must always be in one of the five allowable task
five allowable task states. These states are: executing, ready, states. These states are: executing, ready, blocked, dormant, and
blocked, dormant, and non-existent. non-existent.
A task occupies the non-existent state before A task occupies the non-existent state before a ``rtems_task_create`` has been
a ``rtems_task_create`` has been issued on its behalf. issued on its behalf. A task enters the non-existent state from any other
A task enters the non-existent state from any other state in the system state in the system when it is deleted with the ``rtems_task_delete``
when it is deleted with the ``rtems_task_delete`` directive. directive. While a task occupies this state it does not have a TCB or a task
While a task occupies this state it does not have a TCB or a task ID ID assigned to it; therefore, no other tasks in the system may reference this
assigned to it; therefore, no other tasks in the system may reference task.
this task.
When a task is created via the ``rtems_task_create`` When a task is created via the ``rtems_task_create`` directive it enters the
directive it enters the dormant state. This state is not entered through dormant state. This state is not entered through any other means. Although
any other means. Although the task exists in the system, it cannot the task exists in the system, it cannot actively compete for system resources.
actively compete for system resources. It will remain in the dormant It will remain in the dormant state until it is started via the
state until it is started via the ``rtems_task_start`` ``rtems_task_start`` directive, at which time it enters the ready state. The
directive, at which time it enters the ready state. The task is now task is now permitted to be scheduled for the processor and to compete for
permitted to be scheduled for the processor and to compete for other other system resources.
system resources.
.. code:: c .. COMMENT: .. code:: c
.. COMMENT:
.. COMMENT: +-------------------------------------------------------------+
.. COMMENT: | Non-existent |
.. COMMENT: | +-------------------------------------------------------+ |
.. COMMENT: | | | |
.. COMMENT: | | | |
.. COMMENT: | | Creating +---------+ Deleting | |
.. COMMENT: | | -------------------> | Dormant | -------------------> | |
.. COMMENT: | | +---------+ | |
.. COMMENT: | | | | |
.. COMMENT: | | Starting | | |
.. COMMENT: | | | | |
.. COMMENT: | | V Deleting | |
.. COMMENT: | | +-------> +-------+ -------------------> | |
.. COMMENT: | | Yielding / +----- | Ready | ------+ | |
.. COMMENT: | | / / +-------+ <--+ \\ | |
.. COMMENT: | | / / \\ \\ Blocking | |
.. COMMENT: | | / / Dispatching Readying \\ \\ | |
.. COMMENT: | | / V \\ V | |
.. COMMENT: | | +-----------+ Blocking +---------+ | |
.. COMMENT: | | | Executing | --------------> | Blocked | | |
.. COMMENT: | | +-----------+ +---------+ | |
.. COMMENT: | | | |
.. COMMENT: | | | |
.. COMMENT: | +-------------------------------------------------------+ |
.. COMMENT: | Non-existent |
.. COMMENT: +-------------------------------------------------------------+
+-------------------------------------------------------------+ .. figure:: states.png
| Non-existent | :width: 70%
| +-------------------------------------------------------+ | :align: center
| | | | :alt: Task State Transitions
| | | |
| | 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 A task occupies the blocked state whenever it is unable to be scheduled to run.
to run. A running task may block itself or be blocked by other tasks in A running task may block itself or be blocked by other tasks in the system.
the system. The running task blocks itself through voluntary operations The running task blocks itself through voluntary operations that cause the task
that cause the task to wait. The only way a task can block a task other to wait. The only way a task can block a task other than itself is with the
than itself is with the ``rtems_task_suspend`` directive. ``rtems_task_suspend`` directive. A task enters the blocked state due to any
A task enters the blocked state due to any of the following conditions: of the following conditions:
- A task issues a ``rtems_task_suspend`` directive - A task issues a ``rtems_task_suspend`` directive which blocks either itself
which blocks either itself or another task in the system. or another task in the system.
- The running task issues a ``rtems_barrier_wait`` - The running task issues a ``rtems_barrier_wait`` directive.
directive.
- The running task issues a ``rtems_message_queue_receive`` - The running task issues a ``rtems_message_queue_receive`` directive with the
directive with the wait option and the message queue is empty. wait option and the message queue is empty.
- The running task issues an ``rtems_event_receive`` - The running task issues an ``rtems_event_receive`` directive with the wait
directive with the wait option and the currently pending events do not option and the currently pending events do not satisfy the request.
satisfy the request.
- The running task issues a ``rtems_semaphore_obtain`` - The running task issues a ``rtems_semaphore_obtain`` directive with the wait
directive with the wait option and the requested semaphore is unavailable. option and the requested semaphore is unavailable.
- The running task issues a ``rtems_task_wake_after`` - The running task issues a ``rtems_task_wake_after`` directive which blocks
directive which blocks the task for the given time interval. If the time the task for the given time interval. If the time interval specified is
interval specified is zero, the task yields the processor and remains zero, the task yields the processor and remains in the ready state.
in the ready state.
- The running task issues a ``rtems_task_wake_when`` - The running task issues a ``rtems_task_wake_when`` directive which blocks the
directive which blocks the task until the requested date and time arrives. task until the requested date and time arrives.
- The running task issues a ``rtems_rate_monotonic_period`` - The running task issues a ``rtems_rate_monotonic_period`` directive and must
directive and must wait for the specified rate monotonic period wait for the specified rate monotonic period to conclude.
to conclude.
- The running task issues a ``rtems_region_get_segment`` - The running task issues a ``rtems_region_get_segment`` directive with the
directive with the wait option and there is not an available segment large wait option and there is not an available segment large enough to satisfy the
enough to satisfy the task's request. task's request.
A blocked task may also be suspended. Therefore, both the suspension A blocked task may also be suspended. Therefore, both the suspension and the
and the blocking condition must be removed before the task becomes ready blocking condition must be removed before the task becomes ready to run again.
to run again.
A task occupies the ready state when it is able to be scheduled to run, A task occupies the ready state when it is able to be scheduled to run, but
but currently does not have control of the processor. Tasks of the same currently does not have control of the processor. Tasks of the same or higher
or higher priority will yield the processor by either becoming blocked, priority will yield the processor by either becoming blocked, completing their
completing their timeslice, or being deleted. All tasks with the same timeslice, or being deleted. All tasks with the same priority will execute in
priority will execute in FIFO order. A task enters the ready state due FIFO order. A task enters the ready state due to any of the following
to any of the following conditions: conditions:
- A running task issues a ``rtems_task_resume`` - A running task issues a ``rtems_task_resume`` directive for a task that is
directive for a task that is suspended and the task is not blocked suspended and the task is not blocked waiting on any resource.
waiting on any resource.
- A running task issues a ``rtems_message_queue_send``,``rtems_message_queue_broadcast``, or a``rtems_message_queue_urgent`` directive - A running task issues a ``rtems_message_queue_send``,
which posts a message to the queue on which the blocked task is ``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. waiting.
- A running task issues an ``rtems_event_send`` - A running task issues an ``rtems_event_send`` directive which sends an event
directive which sends an event condition to a task which is blocked condition to a task which is blocked waiting on that event condition.
waiting on that event condition.
- A running task issues a ``rtems_semaphore_release`` - A running task issues a ``rtems_semaphore_release`` directive which releases
directive which releases the semaphore on which the blocked task is the semaphore on which the blocked task is waiting.
waiting.
- A timeout interval expires for a task which was blocked - A timeout interval expires for a task which was blocked by a call to the
by a call to the ``rtems_task_wake_after`` directive. ``rtems_task_wake_after`` directive.
- A timeout period expires for a task which blocked by a - A timeout period expires for a task which blocked by a call to the
call to the ``rtems_task_wake_when`` directive. ``rtems_task_wake_when`` directive.
- A running task issues a ``rtems_region_return_segment`` - A running task issues a ``rtems_region_return_segment`` directive which
directive which releases a segment to the region on which the blocked task releases a segment to the region on which the blocked task is waiting and a
is waiting and a resulting segment is large enough to satisfy resulting segment is large enough to satisfy the task's request.
the task's request.
- A rate monotonic period expires for a task which blocked - A rate monotonic period expires for a task which blocked by a call to the
by a call to the ``rtems_rate_monotonic_period`` directive. ``rtems_rate_monotonic_period`` directive.
- A timeout interval expires for a task which was blocked - A timeout interval expires for a task which was blocked waiting on a message,
waiting on a message, event, semaphore, or segment with a event, semaphore, or segment with a timeout specified.
timeout specified.
- A running task issues a directive which deletes a - A running task issues a directive which deletes a message queue, a semaphore,
message queue, a semaphore, or a region on which the blocked or a region on which the blocked task is waiting.
task is waiting.
- A running task issues a ``rtems_task_restart`` - A running task issues a ``rtems_task_restart`` directive for the blocked
directive for the blocked task. task.
- The running task, with its preemption mode enabled, may - The running task, with its preemption mode enabled, may be made ready by
be made ready by issuing any of the directives that may unblock issuing any of the directives that may unblock a task with a higher priority.
a task with a higher priority. This directive may be issued This directive may be issued from the running task itself or from an ISR. A
from the running task itself or from an ISR. ready task occupies the executing state when it has control of the CPU. A
A ready task occupies the executing state when it has task enters the executing state due to any of the following conditions:
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 - The task is the highest priority ready task in the system.
system.
- The running task blocks and the task is next in the - The running task blocks and the task is next in the scheduling queue. The
scheduling queue. The task may be of equal priority as in task may be of equal priority as in round-robin scheduling or the task may
round-robin scheduling or the task may possess the highest possess the highest priority of the remaining ready tasks.
priority of the remaining ready tasks.
- The running task may reenable its preemption mode and a - The running task may reenable its preemption mode and a task exists in the
task exists in the ready queue that has a higher priority than ready queue that has a higher priority than the running task.
the running task.
- The running task lowers its own priority and another - The running task lowers its own priority and another task is of higher
task is of higher priority as a result. 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.
- The running task raises the priority of a task above its own and the running
task is in preemption mode.

BIN
c_user/states.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

1558
c_user/task_manager.rst
View File

File diff suppressed because it is too large Load Diff

569
c_user/timer_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Timer Manager Timer Manager
############# #############
@ -9,25 +13,25 @@ Introduction
The timer manager provides support for timer The timer manager provides support for timer
facilities. The directives provided by the timer manager are: facilities. The directives provided by the timer manager are:
- ``rtems_timer_create`` - Create a timer - rtems_timer_create_ - Create a timer
- ``rtems_timer_ident`` - Get ID of a timer - rtems_timer_ident_ - Get ID of a timer
- ``rtems_timer_cancel`` - Cancel a timer - rtems_timer_cancel_ - Cancel a timer
- ``rtems_timer_delete`` - Delete a timer - rtems_timer_delete_ - Delete a timer
- ``rtems_timer_fire_after`` - Fire timer after interval - rtems_timer_fire_after_ - Fire timer after interval
- ``rtems_timer_fire_when`` - Fire timer when specified - rtems_timer_fire_when_ - Fire timer when specified
- ``rtems_timer_initiate_server`` - Initiate server for task-based timers - rtems_timer_initiate_server_ - Initiate server for task-based timers
- ``rtems_timer_server_fire_after`` - Fire task-based timer after interval - rtems_timer_server_fire_after_ - Fire task-based timer after interval
- ``rtems_timer_server_fire_when`` - Fire task-based timer when specified - rtems_timer_server_fire_when_ - Fire task-based timer when specified
- ``rtems_timer_reset`` - Reset an interval timer - rtems_timer_reset_ - Reset an interval timer
Background Background
========== ==========
@ -40,65 +44,60 @@ A clock tick is required to support the functionality provided by this manager.
Timers Timers
------ ------
A timer is an RTEMS object which allows the A timer is an RTEMS object which allows the application to schedule operations
application to schedule operations to occur at specific times in to occur at specific times in the future. User supplied timer service routines
the future. User supplied timer service routines are invoked by are invoked by either the ``rtems_clock_tick`` directive or a special Timer
either the ``rtems_clock_tick`` directive or Server task when the timer fires. Timer service routines may perform any
a special Timer Server task when the timer fires. Timer service operations or directives which normally would be performed by the application
routines may perform any operations or directives which normally code which invoked the ``rtems_clock_tick`` directive.
would be performed by the application code which invoked the``rtems_clock_tick`` directive.
The timer can be used to implement watchdog routines The timer can be used to implement watchdog routines which only fire to denote
which only fire to denote that an application error has that an application error has occurred. The timer is reset at specific points
occurred. The timer is reset at specific points in the in the application to ensure that the watchdog does not fire. Thus, if the
application to ensure that the watchdog does not fire. Thus, if application does not reset the watchdog timer, then the timer service routine
the application does not reset the watchdog timer, then the will fire to indicate that the application has failed to reach a reset point.
timer service routine will fire to indicate that the application This use of a timer is sometimes referred to as a "keep alive" or a "deadman"
has failed to reach a reset point. This use of a timer is timer.
sometimes referred to as a "keep alive" or a "deadman" timer.
Timer Server Timer Server
------------ ------------
The Timer Server task is responsible for executing the timer The Timer Server task is responsible for executing the timer service routines
service routines associated with all task-based timers. associated with all task-based timers. This task executes at a priority higher
This task executes at a priority higher than any RTEMS application than any RTEMS application task, and is created non-preemptible, and thus can
task, and is created non-preemptible, and thus can be viewed logically as be viewed logically as the lowest priority interrupt.
the lowest priority interrupt.
By providing a mechanism where timer service routines execute By providing a mechanism where timer service routines execute in task rather
in task rather than interrupt space, the application is than interrupt space, the application is allowed a bit more flexibility in what
allowed a bit more flexibility in what operations a timer operations a timer service routine can perform. For example, the Timer Server
service routine can perform. For example, the Timer Server can be configured to have a floating point context in which case it would be
can be configured to have a floating point context in which case safe to perform floating point operations from a task-based timer. Most of the
it would be safe to perform floating point operations time, executing floating point instructions from an interrupt service routine
from a task-based timer. Most of the time, executing floating is not considered safe. However, since the Timer Server task is
point instructions from an interrupt service routine non-preemptible, only directives allowed from an ISR can be called in the timer
is not considered safe. However, since the Timer Server task service routine.
is non-preemptible, only directives allowed from an ISR can be
called in the timer service routine.
The Timer Server is designed to remain blocked until a The Timer Server is designed to remain blocked until a task-based timer fires.
task-based timer fires. This reduces the execution overhead This reduces the execution overhead of the Timer Server.
of the Timer Server.
Timer Service Routines Timer Service Routines
---------------------- ----------------------
The timer service routine should adhere to C calling The timer service routine should adhere to C calling conventions and have a
conventions and have a prototype similar to the following:.. index:: rtems_timer_service_routine prototype similar to the following:
.. index:: rtems_timer_service_routine
.. code:: c .. code:: c
rtems_timer_service_routine user_routine( rtems_timer_service_routine user_routine(
rtems_id timer_id, rtems_id timer_id,
void \*user_data void *user_data
); );
Where the timer_id parameter is the RTEMS object ID Where the timer_id parameter is the RTEMS object ID of the timer which is being
of the timer which is being fired and user_data is a pointer to fired and user_data is a pointer to user-defined information which may be
user-defined information which may be utilized by the timer utilized by the timer service routine. The argument user_data may be NULL.
service routine. The argument user_data may be NULL.
Operations Operations
========== ==========
@ -106,95 +105,89 @@ Operations
Creating a Timer Creating a Timer
---------------- ----------------
The ``rtems_timer_create`` directive creates a timer by The ``rtems_timer_create`` directive creates a timer by allocating a Timer
allocating a Timer Control Block (TMCB), assigning the timer a Control Block (TMCB), assigning the timer a user-specified name, and assigning
user-specified name, and assigning it a timer ID. Newly created it a timer ID. Newly created timers do not have a timer service routine
timers do not have a timer service routine associated with them associated with them and are not active.
and are not active.
Obtaining Timer IDs Obtaining Timer IDs
------------------- -------------------
When a timer is created, RTEMS generates a unique When a timer is created, RTEMS generates a unique timer ID and assigns it to
timer ID and assigns it to the created timer until it is the created timer until it is deleted. The timer ID may be obtained by either
deleted. The timer ID may be obtained by either of two methods. of two methods. First, as the result of an invocation of the
First, as the result of an invocation of the``rtems_timer_create`` ``rtems_timer_create`` directive, the timer ID is stored in a user provided
directive, the timer ID is stored in a user provided location. location. Second, the timer ID may be obtained later using the
Second, the timer ID may be obtained later using the``rtems_timer_ident`` directive. The timer ID ``rtems_timer_ident`` directive. The timer ID is used by other directives to
is used by other directives to manipulate this timer. manipulate this timer.
Initiating an Interval Timer Initiating an Interval Timer
---------------------------- ----------------------------
The ``rtems_timer_fire_after`` The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives
and ``rtems_timer_server_fire_after`` initiate a timer to fire a user provided timer service routine after the
directives initiate a timer to fire a user provided specified number of clock ticks have elapsed. When the interval has elapsed,
timer service routine after the specified the timer service routine will be invoked from the ``rtems_clock_tick``
number of clock ticks have elapsed. When the interval has directive if it was initiated by the ``rtems_timer_fire_after`` directive and
elapsed, the timer service routine will be invoked from the``rtems_clock_tick`` directive if it was initiated from the Timer Server task if initiated by the
by the ``rtems_timer_fire_after`` directive ``rtems_timer_server_fire_after`` directive.
and from the Timer Server task if initiated by the``rtems_timer_server_fire_after`` directive.
Initiating a Time of Day Timer Initiating a Time of Day Timer
------------------------------ ------------------------------
The ``rtems_timer_fire_when`` The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive
and ``rtems_timer_server_fire_when`` initiate a timer to fire a user provided timer service routine when the
directive initiate a timer to specified time of day has been reached. When the interval has elapsed, the
fire a user provided timer service routine when the specified timer service routine will be invoked from the ``rtems_clock_tick`` directive
time of day has been reached. When the interval has elapsed, by the ``rtems_timer_fire_when`` directive and from the Timer Server task if
the timer service routine will be invoked from the``rtems_clock_tick`` directive initiated by the ``rtems_timer_server_fire_when`` directive.
by the ``rtems_timer_fire_when`` directive
and from the Timer Server task if initiated by the``rtems_timer_server_fire_when`` directive.
Canceling a Timer Canceling a Timer
----------------- -----------------
The ``rtems_timer_cancel`` directive is used to halt the The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once
specified timer. Once canceled, the timer service routine will canceled, the timer service routine will not fire unless the timer is
not fire unless the timer is reinitiated. The timer can be reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``,
reinitiated using the ``rtems_timer_reset``,``rtems_timer_fire_after``, and``rtems_timer_fire_when`` directives. ``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives.
Resetting a Timer Resetting a Timer
----------------- -----------------
The ``rtems_timer_reset`` directive is used to restore an The ``rtems_timer_reset`` directive is used to restore an interval timer
interval timer initiated by a previous invocation of``rtems_timer_fire_after`` or``rtems_timer_server_fire_after`` to initiated by a previous invocation of ``rtems_timer_fire_after`` or
its original interval length. If the ``rtems_timer_server_fire_after`` to its original interval length. If the
timer has not been used or the last usage of this timer timer has not been used or the last usage of this timer was by the
was by the ``rtems_timer_fire_when`` ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then
or ``rtems_timer_server_fire_when`` an error is returned. The timer service routine is not changed or fired by
directive, then an error is returned. The timer service routine this directive.
is not changed or fired by this directive.
Initiating the Timer Server Initiating the Timer Server
--------------------------- ---------------------------
The ``rtems_timer_initiate_server`` directive is used to The ``rtems_timer_initiate_server`` directive is used to allocate and start the
allocate and start the execution of the Timer Server task. The execution of the Timer Server task. The application can specify both the stack
application can specify both the stack size and attributes of the size and attributes of the Timer Server. The Timer Server executes at a
Timer Server. The Timer Server executes at a priority higher than priority higher than any application task and thus the user can expect to be
any application task and thus the user can expect to be preempted preempted as the result of executing the ``rtems_timer_initiate_server``
as the result of executing the ``rtems_timer_initiate_server``
directive. directive.
Deleting a Timer Deleting a Timer
---------------- ----------------
The ``rtems_timer_delete`` directive is used to delete a timer. The ``rtems_timer_delete`` directive is used to delete a timer. If the timer
If the timer is running and has not expired, the timer is is running and has not expired, the timer is automatically canceled. The
automatically canceled. The timer's control block is returned timer's control block is returned to the TMCB free list when it is deleted. A
to the TMCB free list when it is deleted. A timer can be timer can be deleted by a task other than the task which created the timer.
deleted by a task other than the task which created the timer.
Any subsequent references to the timer's name and ID are invalid. Any subsequent references to the timer's name and ID are invalid.
Directives Directives
========== ==========
This section details the timer manager's directives. This section details the timer manager's directives. A subsection is dedicated
A subsection is dedicated to each of this manager's directives to each of this manager's directives and describes the calling sequence,
and describes the calling sequence, related constants, usage, related constants, usage, and status codes.
and status codes.
.. _rtems_timer_create:
TIMER_CREATE - Create a timer TIMER_CREATE - Create a timer
----------------------------- -----------------------------
@ -207,29 +200,36 @@ TIMER_CREATE - Create a timer
.. code:: c .. code:: c
rtems_status_code rtems_timer_create( rtems_status_code rtems_timer_create(
rtems_name name, rtems_name name,
rtems_id \*id rtems_id *id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer created successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL timer created successfully
``RTEMS_INVALID_NAME`` - invalid timer name
``RTEMS_TOO_MANY`` - too many timers created ``RTEMS_INVALID_ADDRESS``
``id`` is NULL
``RTEMS_INVALID_NAME``
invalid timer name
``RTEMS_TOO_MANY``
too many timers created
**DESCRIPTION:** **DESCRIPTION:**
This directive creates a timer. The assigned timer This directive creates a timer. The assigned timer id is returned in id. This
id is returned in id. This id is used to access the timer with id is used to access the timer with other timer manager directives. For
other timer manager directives. For control and maintenance of control and maintenance of the timer, RTEMS allocates a TMCB from the local
the timer, RTEMS allocates a TMCB from the local TMCB free pool TMCB free pool and initializes it.
and initializes it.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be This directive will not cause the calling task to be preempted.
preempted.
.. _rtems_timer_ident:
TIMER_IDENT - Get ID of a timer TIMER_IDENT - Get ID of a timer
------------------------------- -------------------------------
@ -242,29 +242,34 @@ TIMER_IDENT - Get ID of a timer
.. code:: c .. code:: c
rtems_status_code rtems_timer_ident( rtems_status_code rtems_timer_ident(
rtems_name name, rtems_name name,
rtems_id \*id rtems_id *id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer identified successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL timer identified successfully
``RTEMS_INVALID_NAME`` - timer name not found
``RTEMS_INVALID_ADDRESS``
``id`` is NULL
``RTEMS_INVALID_NAME``
timer name not found
**DESCRIPTION:** **DESCRIPTION:**
This directive obtains the timer id associated with This directive obtains the timer id associated with the timer name to be
the timer name to be acquired. If the timer name is not unique, acquired. If the timer name is not unique, then the timer id will match one of
then the timer id will match one of the timers with that name. the timers with that name. However, this timer id is not guaranteed to
However, this timer id is not guaranteed to correspond to the correspond to the desired timer. The timer id is used to access this timer in
desired timer. The timer id is used to access this timer in
other timer related directives. other timer related directives.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
.. _rtems_timer_cancel:
TIMER_CANCEL - Cancel a timer TIMER_CANCEL - Cancel a timer
----------------------------- -----------------------------
@ -277,23 +282,29 @@ TIMER_CANCEL - Cancel a timer
.. code:: c .. code:: c
rtems_status_code rtems_timer_cancel( rtems_status_code rtems_timer_cancel(
rtems_id id rtems_id id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer canceled successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ID`` - invalid timer id timer canceled successfully
``RTEMS_INVALID_ID``
invalid timer id
**DESCRIPTION:** **DESCRIPTION:**
This directive cancels the timer id. This timer will This directive cancels the timer id. This timer will be reinitiated by the
be reinitiated by the next invocation of ``rtems_timer_reset``,``rtems_timer_fire_after``, or``rtems_timer_fire_when`` with this id. next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``, or
``rtems_timer_fire_when`` with this id.
**NOTES:** **NOTES:**
This directive will not cause the running task to be preempted. This directive will not cause the running task to be preempted.
.. _rtems_timer_delete:
TIMER_DELETE - Delete a timer TIMER_DELETE - Delete a timer
----------------------------- -----------------------------
.. index:: delete a timer .. index:: delete a timer
@ -305,27 +316,30 @@ TIMER_DELETE - Delete a timer
.. code:: c .. code:: c
rtems_status_code rtems_timer_delete( rtems_status_code rtems_timer_delete(
rtems_id id rtems_id id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer deleted successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ID`` - invalid timer id timer deleted successfully
``RTEMS_INVALID_ID``
invalid timer id
**DESCRIPTION:** **DESCRIPTION:**
This directive deletes the timer specified by id. If This directive deletes the timer specified by id. If the timer is running, it
the timer is running, it is automatically canceled. The TMCB is automatically canceled. The TMCB for the deleted timer is reclaimed by
for the deleted timer is reclaimed by RTEMS. RTEMS.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
A timer can be deleted by a task other than the task A timer can be deleted by a task other than the task which created the timer.
which created the timer.
.. _rtems_timer_fire_after:
TIMER_FIRE_AFTER - Fire timer after interval TIMER_FIRE_AFTER - Fire timer after interval
-------------------------------------------- --------------------------------------------
@ -338,32 +352,38 @@ TIMER_FIRE_AFTER - Fire timer after interval
.. code:: c .. code:: c
rtems_status_code rtems_timer_fire_after( rtems_status_code rtems_timer_fire_after(
rtems_id id, rtems_id id,
rtems_interval ticks, rtems_interval ticks,
rtems_timer_service_routine_entry routine, rtems_timer_service_routine_entry routine,
void \*user_data void *user_data
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer initiated successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL timer initiated successfully
``RTEMS_INVALID_ID`` - invalid timer id
``RTEMS_INVALID_NUMBER`` - invalid interval ``RTEMS_INVALID_ADDRESS``
``routine`` is NULL
``RTEMS_INVALID_ID``
invalid timer id
``RTEMS_INVALID_NUMBER``
invalid interval
**DESCRIPTION:** **DESCRIPTION:**
This directive initiates the timer specified by id. This directive initiates the timer specified by id. If the timer is running,
If the timer is running, it is automatically canceled before it is automatically canceled before being initiated. The timer is scheduled to
being initiated. The timer is scheduled to fire after an fire after an interval ticks clock ticks has passed. When the timer fires, the
interval ticks clock ticks has passed. When the timer fires, timer service routine routine will be invoked with the argument user_data.
the timer service routine routine will be invoked with the
argument user_data.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
.. _rtems_timer_fire_when:
TIMER_FIRE_WHEN - Fire timer when specified TIMER_FIRE_WHEN - Fire timer when specified
------------------------------------------- -------------------------------------------
@ -376,34 +396,44 @@ TIMER_FIRE_WHEN - Fire timer when specified
.. code:: c .. code:: c
rtems_status_code rtems_timer_fire_when( rtems_status_code rtems_timer_fire_when(
rtems_id id, rtems_id id,
rtems_time_of_day \*wall_time, rtems_time_of_day *wall_time,
rtems_timer_service_routine_entry routine, rtems_timer_service_routine_entry routine,
void \*user_data void *user_data
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer initiated successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL timer initiated successfully
``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL
``RTEMS_INVALID_ID`` - invalid timer id ``RTEMS_INVALID_ADDRESS``
``RTEMS_NOT_DEFINED`` - system date and time is not set ``routine`` is NULL
``RTEMS_INVALID_CLOCK`` - invalid time of day
``RTEMS_INVALID_ADDRESS``
``wall_time`` is NULL
``RTEMS_INVALID_ID``
invalid timer id
``RTEMS_NOT_DEFINED``
system date and time is not set
``RTEMS_INVALID_CLOCK``
invalid time of day
**DESCRIPTION:** **DESCRIPTION:**
This directive initiates the timer specified by id. This directive initiates the timer specified by id. If the timer is running,
If the timer is running, it is automatically canceled before it is automatically canceled before being initiated. The timer is scheduled to
being initiated. The timer is scheduled to fire at the time of fire at the time of day specified by wall_time. When the timer fires, the
day specified by wall_time. When the timer fires, the timer timer service routine routine will be invoked with the argument user_data.
service routine routine will be invoked with the argument
user_data.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
.. _rtems_timer_initiate_server:
TIMER_INITIATE_SERVER - Initiate server for task-based timers TIMER_INITIATE_SERVER - Initiate server for task-based timers
------------------------------------------------------------- -------------------------------------------------------------
@ -416,32 +446,38 @@ TIMER_INITIATE_SERVER - Initiate server for task-based timers
.. code:: c .. code:: c
rtems_status_code rtems_timer_initiate_server( rtems_status_code rtems_timer_initiate_server(
uint32_t priority, uint32_t priority,
uint32_t stack_size, uint32_t stack_size,
rtems_attribute attribute_set rtems_attribute attribute_set
) )
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - Timer Server initiated successfully ``RTEMS_SUCCESSFUL``
``RTEMS_TOO_MANY`` - too many tasks created Timer Server initiated successfully
``RTEMS_TOO_MANY``
too many tasks created
**DESCRIPTION:** **DESCRIPTION:**
This directive initiates the Timer Server task. This task This directive initiates the Timer Server task. This task is responsible for
is responsible for executing all timers initiated via the``rtems_timer_server_fire_after`` or``rtems_timer_server_fire_when`` directives. executing all timers initiated via the ``rtems_timer_server_fire_after`` or
``rtems_timer_server_fire_when`` directives.
**NOTES:** **NOTES:**
This directive could cause the calling task to be preempted. This directive could cause the calling task to be preempted.
The Timer Server task is created using the``rtems_task_create`` service and must be accounted The Timer Server task is created using the ``rtems_task_create`` service and
for when configuring the system. must be accounted for when configuring the system.
Even through this directive invokes the ``rtems_task_create`` Even through this directive invokes the ``rtems_task_create`` and
and ``rtems_task_start`` directives, it should only fail ``rtems_task_start`` directives, it should only fail due to resource allocation
due to resource allocation problems. problems.
.. _rtems_timer_server_fire_after:
TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
-------------------------------------------------------------- --------------------------------------------------------------
@ -454,35 +490,44 @@ TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
.. code:: c .. code:: c
rtems_status_code rtems_timer_server_fire_after( rtems_status_code rtems_timer_server_fire_after(
rtems_id id, rtems_id id,
rtems_interval ticks, rtems_interval ticks,
rtems_timer_service_routine_entry routine, rtems_timer_service_routine_entry routine,
void \*user_data void *user_data
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer initiated successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL timer initiated successfully
``RTEMS_INVALID_ID`` - invalid timer id
``RTEMS_INVALID_NUMBER`` - invalid interval ``RTEMS_INVALID_ADDRESS``
``RTEMS_INCORRECT_STATE`` - Timer Server not initiated ``routine`` is NULL
``RTEMS_INVALID_ID``
invalid timer id
``RTEMS_INVALID_NUMBER``
invalid interval
``RTEMS_INCORRECT_STATE``
Timer Server not initiated
**DESCRIPTION:** **DESCRIPTION:**
This directive initiates the timer specified by id and specifies This directive initiates the timer specified by id and specifies that when it
that when it fires it will be executed by the Timer Server. fires it will be executed by the Timer Server.
If the timer is running, it is automatically canceled before If the timer is running, it is automatically canceled before being initiated.
being initiated. The timer is scheduled to fire after an The timer is scheduled to fire after an interval ticks clock ticks has passed.
interval ticks clock ticks has passed. When the timer fires, When the timer fires, the timer service routine routine will be invoked with
the timer service routine routine will be invoked with the the argument user_data.
argument user_data.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
.. _rtems_timer_server_fire_when:
TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
------------------------------------------------------------- -------------------------------------------------------------
@ -495,37 +540,50 @@ TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
.. code:: c .. code:: c
rtems_status_code rtems_timer_server_fire_when( rtems_status_code rtems_timer_server_fire_when(
rtems_id id, rtems_id id,
rtems_time_of_day \*wall_time, rtems_time_of_day *wall_time,
rtems_timer_service_routine_entry routine, rtems_timer_service_routine_entry routine,
void \*user_data void *user_data
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer initiated successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL timer initiated successfully
``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL
``RTEMS_INVALID_ID`` - invalid timer id ``RTEMS_INVALID_ADDRESS``
``RTEMS_NOT_DEFINED`` - system date and time is not set ``routine`` is NULL
``RTEMS_INVALID_CLOCK`` - invalid time of day
``RTEMS_INCORRECT_STATE`` - Timer Server not initiated ``RTEMS_INVALID_ADDRESS``
``wall_time`` is NULL
``RTEMS_INVALID_ID``
invalid timer id
``RTEMS_NOT_DEFINED``
system date and time is not set
``RTEMS_INVALID_CLOCK``
invalid time of day
``RTEMS_INCORRECT_STATE``
Timer Server not initiated
**DESCRIPTION:** **DESCRIPTION:**
This directive initiates the timer specified by id and specifies This directive initiates the timer specified by id and specifies that when it
that when it fires it will be executed by the Timer Server. fires it will be executed by the Timer Server.
If the timer is running, it is automatically canceled before If the timer is running, it is automatically canceled before being initiated.
being initiated. The timer is scheduled to fire at the time of The timer is scheduled to fire at the time of day specified by wall_time. When
day specified by wall_time. When the timer fires, the timer the timer fires, the timer service routine routine will be invoked with the
service routine routine will be invoked with the argument argument user_data.
user_data.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
.. _rtems_timer_reset:
TIMER_RESET - Reset an interval timer TIMER_RESET - Reset an interval timer
------------------------------------- -------------------------------------
@ -538,45 +596,36 @@ TIMER_RESET - Reset an interval timer
.. code:: c .. code:: c
rtems_status_code rtems_timer_reset( rtems_status_code rtems_timer_reset(
rtems_id id rtems_id id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - timer reset successfully ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ID`` - invalid timer id timer reset successfully
``RTEMS_NOT_DEFINED`` - attempted to reset a when or newly created timer
``RTEMS_INVALID_ID``
invalid timer id
``RTEMS_NOT_DEFINED``
attempted to reset a when or newly created timer
**DESCRIPTION:** **DESCRIPTION:**
This directive resets the timer associated with id. This directive resets the timer associated with id. This timer must have been
This timer must have been previously initiated with either the``rtems_timer_fire_after`` or``rtems_timer_server_fire_after`` previously initiated with either the ``rtems_timer_fire_after`` or
directive. If active the timer is canceled, ``rtems_timer_server_fire_after`` directive. If active the timer is canceled,
after which the timer is reinitiated using the same interval and after which the timer is reinitiated using the same interval and timer service
timer service routine which the original``rtems_timer_fire_after````rtems_timer_server_fire_after`` routine which the original ``rtems_timer_fire_after`` or
directive used. ``rtems_timer_server_fire_after`` directive used.
**NOTES:** **NOTES:**
If the timer has not been used or the last usage of this timer If the timer has not been used or the last usage of this timer was by a
was by a ``rtems_timer_fire_when`` or``rtems_timer_server_fire_when`` ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then
directive, then the ``RTEMS_NOT_DEFINED`` error is the ``RTEMS_NOT_DEFINED`` error is returned.
returned.
Restarting a cancelled after timer results in the timer being Restarting a cancelled after timer results in the timer being reinitiated with
reinitiated with its previous timer service routine and interval. its previous timer service routine and interval.
This directive will not cause the running task to be preempted. This directive will not cause the running task to be preempted.
.. COMMENT: COPYRIGHT (c) 1988-2013.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. COMMENT: Open Issues
.. COMMENT: - nicen up the tables
.. COMMENT: - use math mode to print formulas