mirror of
https://gitlab.rtems.org/rtems/rtos/rtems.git
synced 2025-11-16 12:34:45 +00:00
a570a14004
* user/barrier.t, user/clock.t, user/dpmem.t, user/msg.t, user/part.t, user/region.t, user/rtmon.t, user/sem.t, user/task.t, user/timer.t: Correct documentation typos noticed and thankfully reported by Fabrício de Novaes Kucinskis <fabricio@dea.inpe.br>
735 lines
21 KiB
Perl
735 lines
21 KiB
Perl
@c
|
|
@c COPYRIGHT (c) 1988-2008.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@chapter Timer Manager
|
|
|
|
@cindex timers
|
|
|
|
@section Introduction
|
|
|
|
The timer manager provides support for timer
|
|
facilities. The directives provided by the timer manager are:
|
|
|
|
@itemize @bullet
|
|
@item @code{@value{DIRPREFIX}timer_create} - Create a timer
|
|
@item @code{@value{DIRPREFIX}timer_ident} - Get ID of a timer
|
|
@item @code{@value{DIRPREFIX}timer_cancel} - Cancel a timer
|
|
@item @code{@value{DIRPREFIX}timer_delete} - Delete a timer
|
|
@item @code{@value{DIRPREFIX}timer_fire_after} - Fire timer after interval
|
|
@item @code{@value{DIRPREFIX}timer_fire_when} - Fire timer when specified
|
|
@item @code{@value{DIRPREFIX}timer_initiate_server} - Initiate server for task-based timers
|
|
@item @code{@value{DIRPREFIX}timer_server_fire_after} - Fire task-based timer after interval
|
|
@item @code{@value{DIRPREFIX}timer_server_fire_when} - Fire task-based timer when specified
|
|
@item @code{@value{DIRPREFIX}timer_reset} - Reset an interval timer
|
|
@end itemize
|
|
|
|
|
|
@section Background
|
|
|
|
@subsection Required Support
|
|
|
|
A clock tick is required to support the functionality provided by this manager.
|
|
|
|
@subsection 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 @code{@value{DIRPREFIX}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
|
|
@code{@value{DIRPREFIX}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.
|
|
|
|
@subsection 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.
|
|
|
|
@subsection Timer Service Routines
|
|
|
|
The timer service routine should adhere to @value{LANGUAGE} calling
|
|
conventions and have a prototype similar to the following:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_service_routine
|
|
@example
|
|
rtems_timer_service_routine user_routine(
|
|
rtems_id timer_id,
|
|
void *user_data
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure User_Routine(
|
|
Timer_ID : in RTEMS.ID;
|
|
User_Data : in System.Address
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
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.
|
|
|
|
@section Operations
|
|
|
|
@subsection Creating a Timer
|
|
|
|
The @code{@value{DIRPREFIX}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.
|
|
|
|
@subsection 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
|
|
@code{@value{DIRPREFIX}timer_create}
|
|
directive, the timer ID is stored in a user provided location.
|
|
Second, the timer ID may be obtained later using the
|
|
@code{@value{DIRPREFIX}timer_ident} directive. The timer ID
|
|
is used by other directives to manipulate this timer.
|
|
|
|
@subsection Initiating an Interval Timer
|
|
|
|
The @code{@value{DIRPREFIX}timer_fire_after}
|
|
and @code{@value{DIRPREFIX}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
|
|
@code{@value{DIRPREFIX}clock_tick} directive if it was initiated
|
|
by the @code{@value{DIRPREFIX}timer_fire_after} directive
|
|
and from the Timer Server task if initiated by the
|
|
@code{@value{DIRPREFIX}timer_server_fire_after} directive.
|
|
|
|
@subsection Initiating a Time of Day Timer
|
|
|
|
The @code{@value{DIRPREFIX}timer_fire_when}
|
|
and @code{@value{DIRPREFIX}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
|
|
@code{@value{DIRPREFIX}clock_tick} directive
|
|
by the @code{@value{DIRPREFIX}timer_fire_when} directive
|
|
and from the Timer Server task if initiated by the
|
|
@code{@value{DIRPREFIX}timer_server_fire_when} directive.
|
|
|
|
@subsection Canceling a Timer
|
|
|
|
The @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}timer_reset},
|
|
@code{@value{DIRPREFIX}timer_fire_after}, and
|
|
@code{@value{DIRPREFIX}timer_fire_when} directives.
|
|
|
|
@subsection Resetting a Timer
|
|
|
|
The @code{@value{DIRPREFIX}timer_reset} directive is used to restore an
|
|
interval timer initiated by a previous invocation of
|
|
@code{@value{DIRPREFIX}timer_fire_after} or
|
|
@code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}timer_fire_when}
|
|
or @code{@value{DIRPREFIX}timer_server_fire_when}
|
|
directive, then an error is returned. The timer service routine
|
|
is not changed or fired by this directive.
|
|
|
|
@subsection Initiating the Timer Server
|
|
|
|
The @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}timer_initiate_server}
|
|
directive.
|
|
|
|
@subsection Deleting a Timer
|
|
|
|
The @code{@value{DIRPREFIX}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.
|
|
|
|
@section 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.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_CREATE - Create a timer
|
|
|
|
@cindex create a timer
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_create
|
|
@example
|
|
rtems_status_code rtems_timer_create(
|
|
rtems_name name,
|
|
rtems_id *id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Timer_Create (
|
|
Name : in RTEMS.Name;
|
|
ID : out RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer created successfully@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_NAME} - invalid timer name@*
|
|
@code{@value{RPREFIX}TOO_MANY} - too many timers created
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the calling task to be
|
|
preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_IDENT - Get ID of a timer
|
|
|
|
@cindex obtain the ID of a timer
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_ident
|
|
@example
|
|
rtems_status_code rtems_timer_ident(
|
|
rtems_name name,
|
|
rtems_id *id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Timer_Ident (
|
|
Name : in RTEMS.Name;
|
|
ID : out RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer identified successfully@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_NAME} - timer name not found
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be
|
|
preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_CANCEL - Cancel a timer
|
|
|
|
@cindex cancel a timer
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_cancel
|
|
@example
|
|
rtems_status_code rtems_timer_cancel(
|
|
rtems_id id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Timer_Cancel (
|
|
ID : in RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer canceled successfully@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This directive cancels the timer id. This timer will
|
|
be reinitiated by the next invocation of @code{@value{DIRPREFIX}timer_reset},
|
|
@code{@value{DIRPREFIX}timer_fire_after}, or
|
|
@code{@value{DIRPREFIX}timer_fire_when} with this id.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_DELETE - Delete a timer
|
|
|
|
@cindex delete a timer
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_delete
|
|
@example
|
|
rtems_status_code rtems_timer_delete(
|
|
rtems_id id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Timer_Delete (
|
|
ID : in RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer deleted successfully@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id
|
|
|
|
@subheading 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.
|
|
|
|
@subheading 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.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_FIRE_AFTER - Fire timer after interval
|
|
|
|
@cindex fire a timer after an interval
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_fire_after
|
|
@example
|
|
rtems_status_code rtems_timer_fire_after(
|
|
rtems_id id,
|
|
rtems_interval ticks,
|
|
rtems_timer_service_routine_entry routine,
|
|
void *user_data
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
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
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
|
|
@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be
|
|
preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_FIRE_WHEN - Fire timer when specified
|
|
|
|
@cindex fire a timer at wall time
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_fire_when
|
|
@example
|
|
rtems_status_code rtems_timer_fire_when(
|
|
rtems_id id,
|
|
rtems_time_of_day *wall_time,
|
|
rtems_timer_service_routine_entry routine,
|
|
void *user_data
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
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
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{wall_time} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
|
|
@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
|
|
@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be
|
|
preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_INITIATE_SERVER - Initiate server for task-based timers
|
|
|
|
@cindex initiate the Timer Server
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_initiate_server
|
|
@example
|
|
rtems_status_code rtems_timer_initiate_server(
|
|
uint32_t priority,
|
|
uint32_t stack_size,
|
|
rtems_attribute attribute_set
|
|
)
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
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
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - Timer Server initiated successfully@*
|
|
@code{@value{RPREFIX}TOO_MANY} - too many tasks created
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This directive initiates the Timer Server task. This task
|
|
is responsible for executing all timers initiated via the
|
|
@code{@value{DIRPREFIX}timer_server_fire_after} or
|
|
@code{@value{DIRPREFIX}timer_server_fire_when} directives.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive could cause the calling task to be preempted.
|
|
|
|
The Timer Server task is created using the
|
|
@code{@value{DIRPREFIX}task_create} service and must be accounted
|
|
for when configuring the system.
|
|
|
|
Even through this directive invokes the @code{@value{DIRPREFIX}task_create}
|
|
and @code{@value{DIRPREFIX}task_start} directives, it should only fail
|
|
due to resource allocation problems.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
|
|
|
|
@cindex fire task-based a timer after an interval
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_server_fire_after
|
|
@example
|
|
rtems_status_code rtems_timer_server_fire_after(
|
|
rtems_id id,
|
|
rtems_interval ticks,
|
|
rtems_timer_service_routine_entry routine,
|
|
void *user_data
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
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
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
|
|
@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval@*
|
|
@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be
|
|
preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
|
|
|
|
@cindex fire a task-based timer at wall time
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_server_fire_when
|
|
@example
|
|
rtems_status_code rtems_timer_server_fire_when(
|
|
rtems_id id,
|
|
rtems_time_of_day *wall_time,
|
|
rtems_timer_service_routine_entry routine,
|
|
void *user_data
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
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
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{wall_time} is NULL@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
|
|
@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
|
|
@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day@*
|
|
@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be
|
|
preempted.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection TIMER_RESET - Reset an interval timer
|
|
|
|
@cindex reset a timer
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@findex rtems_timer_reset
|
|
@example
|
|
rtems_status_code rtems_timer_reset(
|
|
rtems_id id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Timer_Reset (
|
|
ID : in RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{@value{RPREFIX}SUCCESSFUL} - timer reset successfully@*
|
|
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
|
|
@code{@value{RPREFIX}NOT_DEFINED} - attempted to reset a when or newly created timer
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This directive resets the timer associated with id.
|
|
This timer must have been previously initiated with either the
|
|
@code{@value{DIRPREFIX}timer_fire_after} or
|
|
@code{@value{DIRPREFIX}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
|
|
@code{@value{DIRPREFIX}timer_fire_after}
|
|
@code{@value{DIRPREFIX}timer_server_fire_after}
|
|
directive used.
|
|
|
|
@subheading NOTES:
|
|
|
|
If the timer has not been used or the last usage of this timer
|
|
was by a @code{@value{DIRPREFIX}timer_fire_when} or
|
|
@code{@value{DIRPREFIX}timer_server_fire_when}
|
|
directive, then the @code{@value{RPREFIX}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.
|
|
|