diff options
Diffstat (limited to 'doc/user/timer.t')
| -rw-r--r-- | doc/user/timer.t | 248 |
1 files changed, 232 insertions, 16 deletions
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. |