Timer Manager
#############
.. index:: timers
Introduction
============
The timer manager provides support for timer
facilities. The directives provided by the timer manager are:
- ``rtems.timer_create`` - Create a timer
- ``rtems.timer_ident`` - Get ID of a timer
- ``rtems.timer_cancel`` - Cancel a timer
- ``rtems.timer_delete`` - Delete a timer
- ``rtems.timer_fire_after`` - Fire timer after interval
- ``rtems.timer_fire_when`` - Fire timer when specified
- ``rtems.timer_initiate_server`` - Initiate server for task-based timers
- ``rtems.timer_server_fire_after`` - Fire task-based timer after interval
- ``rtems.timer_server_fire_when`` - Fire task-based timer when specified
- ``rtems.timer_reset`` - Reset an interval timer
Background
==========
Required Support
----------------
A clock tick is required to support the functionality provided by this manager.
Timers
------
A timer is an RTEMS object which allows the
application to schedule operations to occur at specific times in
the future. User supplied timer service routines are invoked by
either the ``rtems.clock_tick`` directive or
a special Timer Server task when the timer fires. Timer service
routines may perform any operations or directives which normally
would be performed by the application code which invoked the``rtems.clock_tick`` directive.
The timer can be used to implement watchdog routines
which only fire to denote that an application error has
occurred. The timer is reset at specific points in the
application to ensure that the watchdog does not fire. Thus, if
the application does not reset the watchdog timer, then the
timer service routine will fire to indicate that the application
has failed to reach a reset point. This use of a timer is
sometimes referred to as a "keep alive" or a "deadman" timer.
Timer Server
------------
The Timer Server task is responsible for executing the timer
service routines associated with all task-based timers.
This task executes at a priority higher than any RTEMS application
task, and is created non-preemptible, and thus can be viewed logically as
the lowest priority interrupt.
By providing a mechanism where timer service routines execute
in task rather than interrupt space, the application is
allowed a bit more flexibility in what operations a timer
service routine can perform. For example, the Timer Server
can be configured to have a floating point context in which case
it would be safe to perform floating point operations
from a task-based timer. Most of the time, executing floating
point instructions from an interrupt service routine
is not considered safe. However, since the Timer Server task
is non-preemptible, only directives allowed from an ISR can be
called in the timer service routine.
The Timer Server is designed to remain blocked until a
task-based timer fires. This reduces the execution overhead
of the Timer Server.
Timer Service Routines
----------------------
The timer service routine should adhere to Ada calling
conventions and have a prototype similar to the following:
.. code:: c
procedure User_Routine(
Timer_ID : in RTEMS.ID;
User_Data : in System.Address
);
Where the timer_id parameter is the RTEMS object ID
of the timer which is being fired and user_data is a pointer to
user-defined information which may be utilized by the timer
service routine. The argument user_data may be NULL.
Operations
==========
Creating a Timer
----------------
The ``rtems.timer_create`` directive creates a timer by
allocating a Timer Control Block (TMCB), assigning the timer a
user-specified name, and assigning it a timer ID. Newly created
timers do not have a timer service routine associated with them
and are not active.
Obtaining Timer IDs
-------------------
When a timer is created, RTEMS generates a unique
timer ID and assigns it to the created timer until it is
deleted. The timer ID may be obtained by either of two methods.
First, as the result of an invocation of the``rtems.timer_create``
directive, the timer ID is stored in a user provided location.
Second, the timer ID may be obtained later using the``rtems.timer_ident`` directive. The timer ID
is used by other directives to manipulate this timer.
Initiating an Interval Timer
----------------------------
The ``rtems.timer_fire_after``
and ``rtems.timer_server_fire_after``
directives initiate a timer to fire a user provided
timer service routine after the specified
number of clock ticks have elapsed. When the interval has
elapsed, the timer service routine will be invoked from the``rtems.clock_tick`` directive if it was initiated
by the ``rtems.timer_fire_after`` directive
and from the Timer Server task if initiated by the``rtems.timer_server_fire_after`` directive.
Initiating a Time of Day Timer
------------------------------
The ``rtems.timer_fire_when``
and ``rtems.timer_server_fire_when``
directive initiate a timer to
fire a user provided timer service routine when the specified
time of day has been reached. When the interval has elapsed,
the timer service routine will be invoked from the``rtems.clock_tick`` directive
by the ``rtems.timer_fire_when`` directive
and from the Timer Server task if initiated by the``rtems.timer_server_fire_when`` directive.
Canceling a Timer
-----------------
The ``rtems.timer_cancel`` directive is used to halt the
specified timer. Once canceled, the timer service routine will
not fire unless the timer is reinitiated. The timer can be
reinitiated using the ``rtems.timer_reset``,``rtems.timer_fire_after``, and``rtems.timer_fire_when`` directives.
Resetting a Timer
-----------------
The ``rtems.timer_reset`` directive is used to restore an
interval timer initiated by a previous invocation of``rtems.timer_fire_after`` or``rtems.timer_server_fire_after`` to
its original interval length. If the
timer has not been used or the last usage of this timer
was by the ``rtems.timer_fire_when``
or ``rtems.timer_server_fire_when``
directive, then an error is returned. The timer service routine
is not changed or fired by this directive.
Initiating the Timer Server
---------------------------
The ``rtems.timer_initiate_server`` directive is used to
allocate and start the execution of the Timer Server task. The
application can specify both the stack size and attributes of the
Timer Server. The Timer Server executes at a priority higher than
any application task and thus the user can expect to be preempted
as the result of executing the ``rtems.timer_initiate_server``
directive.
Deleting a Timer
----------------
The ``rtems.timer_delete`` directive is used to delete a timer.
If the timer is running and has not expired, the timer is
automatically canceled. The timer’s control block is returned
to the TMCB free list when it is deleted. A timer can be
deleted by a task other than the task which created the timer.
Any subsequent references to the timer’s name and ID are invalid.
Directives
==========
This section details the timer manager’s directives.
A subsection is dedicated to each of this manager’s directives
and describes the calling sequence, related constants, usage,
and status codes.
TIMER_CREATE - Create a timer
-----------------------------
.. index:: create a timer
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Create (
Name : in RTEMS.Name;
ID : out RTEMS.ID;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer created successfully
``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS.INVALID_NAME`` - invalid timer name
``RTEMS.TOO_MANY`` - too many timers created
**DESCRIPTION:**
This directive creates a timer. The assigned timer
id is returned in id. This id is used to access the timer with
other timer manager directives. For control and maintenance of
the timer, RTEMS allocates a TMCB from the local TMCB free pool
and initializes it.
**NOTES:**
This directive will not cause the calling task to be
preempted.
TIMER_IDENT - Get ID of a timer
-------------------------------
.. index:: obtain the ID of a timer
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Ident (
Name : in RTEMS.Name;
ID : out RTEMS.ID;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer identified successfully
``RTEMS.INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS.INVALID_NAME`` - timer name not found
**DESCRIPTION:**
This directive obtains the timer id associated with
the timer name to be acquired. If the timer name is not unique,
then the timer id will match one of the timers with that name.
However, this timer id is not guaranteed to correspond to the
desired timer. The timer id is used to access this timer in
other timer related directives.
**NOTES:**
This directive will not cause the running task to be
preempted.
TIMER_CANCEL - Cancel a timer
-----------------------------
.. index:: cancel a timer
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Cancel (
ID : in RTEMS.ID;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer canceled successfully
``RTEMS.INVALID_ID`` - invalid timer id
**DESCRIPTION:**
This directive cancels the timer id. This timer will
be reinitiated by the next invocation of ``rtems.timer_reset``,``rtems.timer_fire_after``, or``rtems.timer_fire_when`` with this id.
**NOTES:**
This directive will not cause the running task to be preempted.
TIMER_DELETE - Delete a timer
-----------------------------
.. index:: delete a timer
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Delete (
ID : in RTEMS.ID;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer deleted successfully
``RTEMS.INVALID_ID`` - invalid timer id
**DESCRIPTION:**
This directive deletes the timer specified by id. If
the timer is running, it is automatically canceled. The TMCB
for the deleted timer is reclaimed by RTEMS.
**NOTES:**
This directive will not cause the running task to be
preempted.
A timer can be deleted by a task other than the task
which created the timer.
TIMER_FIRE_AFTER - Fire timer after interval
--------------------------------------------
.. index:: fire a timer after an interval
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Fire_After (
ID : in RTEMS.ID;
Ticks : in RTEMS.Interval;
Routine : in RTEMS.Timer_Service_Routine;
User_Data : in RTEMS.Address;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer initiated successfully
``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
``RTEMS.INVALID_ID`` - invalid timer id
``RTEMS.INVALID_NUMBER`` - invalid interval
**DESCRIPTION:**
This directive initiates the timer specified by id.
If the timer is running, it is automatically canceled before
being initiated. The timer is scheduled to fire after an
interval ticks clock ticks has passed. When the timer fires,
the timer service routine routine will be invoked with the
argument user_data.
**NOTES:**
This directive will not cause the running task to be
preempted.
TIMER_FIRE_WHEN - Fire timer when specified
-------------------------------------------
.. index:: fire a timer at wall time
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Fire_When (
ID : in RTEMS.ID;
Wall_Time : in RTEMS.Time_Of_Day;
Routine : in RTEMS.Timer_Service_Routine;
User_Data : in RTEMS.Address;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer initiated successfully
``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
``RTEMS.INVALID_ADDRESS`` - ``wall_time`` is NULL
``RTEMS.INVALID_ID`` - invalid timer id
``RTEMS.NOT_DEFINED`` - system date and time is not set
``RTEMS.INVALID_CLOCK`` - invalid time of day
**DESCRIPTION:**
This directive initiates the timer specified by id.
If the timer is running, it is automatically canceled before
being initiated. The timer is scheduled to fire at the time of
day specified by wall_time. When the timer fires, the timer
service routine routine will be invoked with the argument
user_data.
**NOTES:**
This directive will not cause the running task to be
preempted.
TIMER_INITIATE_SERVER - Initiate server for task-based timers
-------------------------------------------------------------
.. index:: initiate the Timer Server
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Initiate_Server (
Server_Priority : in RTEMS.Task_Priority;
Stack_Size : in RTEMS.Unsigned32;
Attribute_Set : in RTEMS.Attribute;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - Timer Server initiated successfully
``RTEMS.TOO_MANY`` - too many tasks created
**DESCRIPTION:**
This directive initiates the Timer Server task. This task
is responsible for executing all timers initiated via the``rtems.timer_server_fire_after`` or``rtems.timer_server_fire_when`` directives.
**NOTES:**
This directive could cause the calling task to be preempted.
The Timer Server task is created using the``rtems.task_create`` service and must be accounted
for when configuring the system.
Even through this directive invokes the ``rtems.task_create``
and ``rtems.task_start`` directives, it should only fail
due to resource allocation problems.
TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
--------------------------------------------------------------
.. index:: fire task-based a timer after an interval
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Fire_Server_After (
ID : in RTEMS.ID;
Ticks : in RTEMS.Interval;
Routine : in RTEMS.Timer_Service_Routine;
User_Data : in RTEMS.Address;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer initiated successfully
``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
``RTEMS.INVALID_ID`` - invalid timer id
``RTEMS.INVALID_NUMBER`` - invalid interval
``RTEMS.INCORRECT_STATE`` - Timer Server not initiated
**DESCRIPTION:**
This directive initiates the timer specified by id and specifies
that when it fires it will be executed by the Timer Server.
If the timer is running, it is automatically canceled before
being initiated. The timer is scheduled to fire after an
interval ticks clock ticks has passed. When the timer fires,
the timer service routine routine will be invoked with the
argument user_data.
**NOTES:**
This directive will not cause the running task to be
preempted.
TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
-------------------------------------------------------------
.. index:: fire a task-based timer at wall time
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Fire_Server_When (
ID : in RTEMS.ID;
Wall_Time : in RTEMS.Time_Of_Day;
Routine : in RTEMS.Timer_Service_Routine;
User_Data : in RTEMS.Address;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer initiated successfully
``RTEMS.INVALID_ADDRESS`` - ``routine`` is NULL
``RTEMS.INVALID_ADDRESS`` - ``wall_time`` is NULL
``RTEMS.INVALID_ID`` - invalid timer id
``RTEMS.NOT_DEFINED`` - system date and time is not set
``RTEMS.INVALID_CLOCK`` - invalid time of day
``RTEMS.INCORRECT_STATE`` - Timer Server not initiated
**DESCRIPTION:**
This directive initiates the timer specified by id and specifies
that when it fires it will be executed by the Timer Server.
If the timer is running, it is automatically canceled before
being initiated. The timer is scheduled to fire at the time of
day specified by wall_time. When the timer fires, the timer
service routine routine will be invoked with the argument
user_data.
**NOTES:**
This directive will not cause the running task to be
preempted.
TIMER_RESET - Reset an interval timer
-------------------------------------
.. index:: reset a timer
**CALLING SEQUENCE:**
.. code:: c
procedure Timer_Reset (
ID : in RTEMS.ID;
Result : out RTEMS.Status_Codes
);
**DIRECTIVE STATUS CODES:**
``RTEMS.SUCCESSFUL`` - timer reset successfully
``RTEMS.INVALID_ID`` - invalid timer id
``RTEMS.NOT_DEFINED`` - attempted to reset a when or newly created timer
**DESCRIPTION:**
This directive resets the timer associated with id.
This timer must have been previously initiated with either the``rtems.timer_fire_after`` or``rtems.timer_server_fire_after``
directive. If active the timer is canceled,
after which the timer is reinitiated using the same interval and
timer service routine which the original``rtems.timer_fire_after````rtems.timer_server_fire_after``
directive used.
**NOTES:**
If the timer has not been used or the last usage of this timer
was by a ``rtems.timer_fire_when`` or``rtems.timer_server_fire_when``
directive, then the ``RTEMS.NOT_DEFINED`` error is
returned.
Restarting a cancelled after timer results in the timer being
reinitiated with its previous timer service routine and interval.
This directive will not cause the running task to be preempted.
.. COMMENT: COPYRIGHT (c) 1988-2007.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.