RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2001-01-17 Joel Sherrill <joel@OARcorp.com>

Browse Source 
* timer.t: Added task-based timer information including the
	new directives rtems_timer_initiate(), rtems_timer_server_fire_after(),
	and rtems_timer_server_fire_when().
This commit is contained in:
Joel Sherrill
2002-01-17 23:14:16 +00:00
parent 6449498bc7
commit 5cd3258390
2 changed files with 238 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/user/ChangeLog
View File

@@ -1,3 +1,9 @@
2001-01-17 Joel Sherrill <joel@OARcorp.com>
* timer.t: Added task-based timer information including the
new directives rtems_timer_initiate(), rtems_timer_server_fire_after(),
and rtems_timer_server_fire_when().
2000-08-10 Joel Sherrill <joel@OARcorp.com>
* ChangeLog: New file.

248
doc/user/timer.t
View File

@@ -22,6 +22,9 @@ facilities. The directives provided by the timer manager are:
@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
@@ -37,9 +40,9 @@ A clock tick is required to support the functionality provided by this manager.
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
the @code{@value{DIRPREFIX}clock_tick} directive
when the timer fires. Timer service routines may perform
any operations or directives which normally
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.
@@ -52,6 +55,27 @@ 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 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 save 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.
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
@@ -105,19 +129,29 @@ is used by other directives to manipulate this timer.
@subsection Initiating an Interval Timer
The @code{@value{DIRPREFIX}timer_fire_after} directive initiates a timer to
fire a user provided timer service routine after the specified
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.
@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} directive initiates a timer to
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.
@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
@@ -132,12 +166,24 @@ reinitiated using the @code{@value{DIRPREFIX}timer_reset},
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} to
@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 a @code{@value{DIRPREFIX}timer_fire_when} directive, then an error is
returned. The timer service routine is not changed or
fired by this directive.
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
@@ -288,7 +334,7 @@ procedure Timer_Cancel (
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 id.
@code{@value{DIRPREFIX}timer_fire_when} with this id.
@subheading NOTES:
@@ -447,6 +493,173 @@ user_data.
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(
unsigned32 stack_size,
rtems_attribute attribute_set
)
);
@end example
@end ifset
@ifset is-Ada
@example
procedure Timer_Initiate_Server (
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_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_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
@@ -483,18 +696,21 @@ procedure Timer_Reset (
@subheading DESCRIPTION:
This directive resets the timer associated with id.
This timer must have been previously initiated with a
@code{@value{DIRPREFIX}timer_fire_after}
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}
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.