summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2002-01-17 23:14:16 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2002-01-17 23:14:16 +0000
commit5cd32583903b91a79a851c587aff3829a46968e8 (patch)
tree45b3200ea6cea60d3439f768122f60ae80262be1 /doc/user
parent6449498bc7dea93900d6980a66af64c9116ef597 (diff)
downloadrtems-5cd32583903b91a79a851c587aff3829a46968e8.tar.bz2
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().
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/ChangeLog6
-rw-r--r--doc/user/timer.t248
2 files changed, 238 insertions, 16 deletions
diff --git a/doc/user/ChangeLog b/doc/user/ChangeLog
index 101734ce64..208d8431a1 100644
--- a/doc/user/ChangeLog
+++ b/doc/user/ChangeLog
@@ -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.
diff --git a/doc/user/timer.t b/doc/user/timer.t
index b1af56d6a1..0049c138d8 100644
--- a/doc/user/timer.t
+++ b/doc/user/timer.t
@@ -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:
@@ -451,6 +497,173 @@ preempted.
@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
+@page
@subsection TIMER_RESET - Reset an interval timer
@cindex reset a timer
@@ -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.