source: rtems/doc/user/timer.t @ 1b03eed

4.8
Last change on this file since 1b03eed was 1b03eed, checked in by Glenn Humphrey <glenn.humphrey@…>, on 10/26/07 at 21:34:57

2007-10-26 Glenn Humphrey <glenn.humphrey@…>

  • user/rtmon.t: Fix report output.

2007-10-25 Glenn Humphrey <glenn.humphrey@…>

  • user/barrier.t, user/clock.t, user/concepts.t, user/cpuuse.t, user/init.t, user/intr.t, user/io.t, user/mp.t, user/rtmon.t, user/sem.t, user/stackchk.t, user/task.t, user/timer.t: Updated the Ada documentation to reflect the current binding.
  • Property mode set to 100644
File size: 20.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Timer Manager
10
11@cindex timers
12
13@section Introduction
14
15The timer manager provides support for timer
16facilities.  The directives provided by the timer manager are:
17
18@itemize @bullet
19@item @code{@value{DIRPREFIX}timer_create} - Create a timer
20@item @code{@value{DIRPREFIX}timer_ident} - Get ID of a timer
21@item @code{@value{DIRPREFIX}timer_cancel} - Cancel a timer
22@item @code{@value{DIRPREFIX}timer_delete} - Delete a timer
23@item @code{@value{DIRPREFIX}timer_fire_after} - Fire timer after interval
24@item @code{@value{DIRPREFIX}timer_fire_when} - Fire timer when specified
25@item @code{@value{DIRPREFIX}timer_initiate_server} - Initiate server for task-based timers
26@item @code{@value{DIRPREFIX}timer_server_fire_after} - Fire task-based timer after interval
27@item @code{@value{DIRPREFIX}timer_server_fire_when} - Fire task-based timer when specified
28@item @code{@value{DIRPREFIX}timer_reset} - Reset an interval timer
29@end itemize
30
31
32@section Background
33
34@subsection Required Support
35
36A clock tick is required to support the functionality provided by this manager.
37
38@subsection Timers
39
40A timer is an RTEMS object which allows the
41application to schedule operations to occur at specific times in
42the future.  User supplied timer service routines are invoked by
43either the @code{@value{DIRPREFIX}clock_tick} directive or
44a special Timer Server task when the timer fires.  Timer service
45routines may perform any operations or directives which normally
46would be performed by the application code which invoked the
47@code{@value{DIRPREFIX}clock_tick} directive.
48
49The timer can be used to implement watchdog routines
50which only fire to denote that an application error has
51occurred.  The timer is reset at specific points in the
52application to insure that the watchdog does not fire.  Thus, if
53the application does not reset the watchdog timer, then the
54timer service routine will fire to indicate that the application
55has failed to reach a reset point.  This use of a timer is
56sometimes referred to as a "keep alive" or a "deadman" timer.
57
58@subsection Timer Server
59
60The Timer Server task is responsible for executing the timer
61service routines associated with all task-based timers.
62This task executes at a priority higher than any RTEMS application
63task, and is created non-preemptible, and thus can be viewed logically as
64the lowest priority interrupt.
65
66By providing a mechanism where timer service routines execute
67in task rather than interrupt space, the application is
68allowed a bit more flexibility in what operations a timer
69service routine can perform.  For example, the Timer Server
70can be configured to have a floating point context in which case
71it would be save to perform floating point operations
72from a task-based timer.  Most of the time, executing floating
73point instructions from an interrupt service routine
74is not considered safe. However, since the Timer Server task
75is non-preemptible, only directives allowed from an ISR can be
76called in the timer service routine.
77
78The Timer Server is designed to remain blocked until a
79task-based timer fires.  This reduces the execution overhead
80of the Timer Server.
81
82@subsection Timer Service Routines
83
84The timer service routine should adhere to @value{LANGUAGE} calling
85conventions and have a prototype similar to the following:
86
87@ifset is-C
88@findex rtems_timer_service_routine
89@example
90rtems_timer_service_routine user_routine(
91  rtems_id   timer_id,
92  void      *user_data
93);
94@end example
95@end ifset
96
97@ifset is-Ada
98@example
99procedure User_Routine(
100  Timer_ID  : in     RTEMS.ID;
101  User_Data : in     System.Address
102);
103@end example
104@end ifset
105
106Where the timer_id parameter is the RTEMS object ID
107of the timer which is being fired and user_data is a pointer to
108user-defined information which may be utilized by the timer
109service routine.  The argument user_data may be NULL.
110
111@section Operations
112
113@subsection Creating a Timer
114
115The @code{@value{DIRPREFIX}timer_create} directive creates a timer by
116allocating a Timer Control Block (TMCB), assigning the timer a
117user-specified name, and assigning it a timer ID.  Newly created
118timers do not have a timer service routine associated with them
119and are not active.
120
121@subsection Obtaining Timer IDs
122
123When a timer is created, RTEMS generates a unique
124timer ID and assigns it to the created timer until it is
125deleted.  The timer ID may be obtained by either of two methods.
126First, as the result of an invocation of the
127@code{@value{DIRPREFIX}timer_create}
128directive, the timer ID is stored in a user provided location.
129Second, the timer ID may be obtained later using the
130@code{@value{DIRPREFIX}timer_ident} directive.  The timer ID
131is used by other directives to manipulate this timer.
132
133@subsection Initiating an Interval Timer
134
135The @code{@value{DIRPREFIX}timer_fire_after}
136and @code{@value{DIRPREFIX}timer_server_fire_after}
137directives initiate a timer to fire a user provided
138timer service routine after the specified
139number of clock ticks have elapsed.  When the interval has
140elapsed, the timer service routine will be invoked from the
141@code{@value{DIRPREFIX}clock_tick} directive if it was initiated
142by the @code{@value{DIRPREFIX}timer_fire_after} directive
143and from the Timer Server task if initiated by the
144@code{@value{DIRPREFIX}timer_server_fire_after} directive.
145
146@subsection Initiating a Time of Day Timer
147
148The @code{@value{DIRPREFIX}timer_fire_when}
149and @code{@value{DIRPREFIX}timer_server_fire_when}
150directive initiate a timer to
151fire a user provided timer service routine when the specified
152time of day has been reached.  When the interval has elapsed,
153the timer service routine will be invoked from the
154@code{@value{DIRPREFIX}clock_tick} directive
155by the @code{@value{DIRPREFIX}timer_fire_when} directive
156and from the Timer Server task if initiated by the
157@code{@value{DIRPREFIX}timer_server_fire_when} directive.
158
159@subsection Canceling a Timer
160
161The @code{@value{DIRPREFIX}timer_cancel} directive is used to halt the
162specified timer.  Once canceled, the timer service routine will
163not fire unless the timer is reinitiated.  The timer can be
164reinitiated using the @code{@value{DIRPREFIX}timer_reset},
165@code{@value{DIRPREFIX}timer_fire_after}, and
166@code{@value{DIRPREFIX}timer_fire_when} directives.
167
168@subsection Resetting a Timer
169
170The @code{@value{DIRPREFIX}timer_reset} directive is used to restore an
171interval timer initiated by a previous invocation of
172@code{@value{DIRPREFIX}timer_fire_after} or
173@code{@value{DIRPREFIX}timer_server_fire_after} to
174its original interval length.  If the
175timer has not been used or the last usage of this timer
176was by the @code{@value{DIRPREFIX}timer_fire_when}
177or @code{@value{DIRPREFIX}timer_server_fire_when}
178directive, then an error is returned.  The timer service routine
179is not changed or fired by this directive.
180
181@subsection Initiating the Timer Server
182
183The @code{@value{DIRPREFIX}timer_initiate_server} directive is used to
184allocate and start the execution of the Timer Server task.  The
185application can specify both the stack size and attributes of the
186Timer Server.  The Timer Server executes at a priority higher than
187any application task and thus the user can expect to be preempted
188as the result of executing the @code{@value{DIRPREFIX}timer_initiate_server}
189directive.
190
191@subsection Deleting a Timer
192
193The @code{@value{DIRPREFIX}timer_delete} directive is used to delete a timer.
194If the timer is running and has not expired, the timer is
195automatically canceled.  The timer's control block is returned
196to the TMCB free list when it is deleted.  A timer can be
197deleted by a task other than the task which created the timer.
198Any subsequent references to the timer's name and ID are invalid.
199
200@section Directives
201
202This section details the timer manager's directives.
203A subsection is dedicated to each of this manager's directives
204and describes the calling sequence, related constants, usage,
205and status codes.
206
207@c
208@c
209@c
210@page
211@subsection TIMER_CREATE - Create a timer
212
213@cindex create a timer
214
215@subheading CALLING SEQUENCE:
216
217@ifset is-C
218@findex rtems_timer_create
219@example
220rtems_status_code rtems_timer_create(
221  rtems_name  name,
222  rtems_id   *id
223);
224@end example
225@end ifset
226
227@ifset is-Ada
228@example
229procedure Timer_Create (
230   Name   : in     RTEMS.Name;
231   ID     :    out RTEMS.ID;
232   Result :    out RTEMS.Status_Codes
233);
234@end example
235@end ifset
236
237@subheading DIRECTIVE STATUS CODES:
238@code{@value{RPREFIX}SUCCESSFUL} - timer created successfully@*
239@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
240@code{@value{RPREFIX}INVALID_NAME} - invalid timer name@*
241@code{@value{RPREFIX}TOO_MANY} - too many timers created
242
243@subheading DESCRIPTION:
244
245This directive creates a timer.  The assigned timer
246id is returned in id.  This id is used to access the timer with
247other timer manager directives.  For control and maintenance of
248the timer, RTEMS allocates a TMCB from the local TMCB free pool
249and initializes it.
250
251@subheading NOTES:
252
253This directive will not cause the calling task to be
254preempted.
255
256@c
257@c
258@c
259@page
260@subsection TIMER_IDENT - Get ID of a timer
261
262@cindex obtain the ID of a timer
263
264@subheading CALLING SEQUENCE:
265
266@ifset is-C
267@findex rtems_timer_ident
268@example
269rtems_status_code rtems_timer_ident(
270  rtems_name  name,
271  rtems_id   *id
272);
273@end example
274@end ifset
275
276@ifset is-Ada
277@example
278procedure Timer_Ident (
279   Name   : in     RTEMS.Name;
280   ID     :    out RTEMS.ID;
281   Result :    out RTEMS.Status_Codes
282);
283@end example
284@end ifset
285
286@subheading DIRECTIVE STATUS CODES:
287@code{@value{RPREFIX}SUCCESSFUL} - timer identified successfully@*
288@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
289@code{@value{RPREFIX}INVALID_NAME} - timer name not found
290
291@subheading DESCRIPTION:
292
293This directive obtains the timer id associated with
294the timer name to be acquired.  If the timer name is not unique,
295then the timer id will match one of the timers with that name.
296However, this timer id is not guaranteed to correspond to the
297desired timer.  The timer id is used to access this timer in
298other timer related directives.
299
300@subheading NOTES:
301
302This directive will not cause the running task to be
303preempted.
304
305@c
306@c
307@c
308@page
309@subsection TIMER_CANCEL - Cancel a timer
310
311@cindex cancel a timer
312
313@subheading CALLING SEQUENCE:
314
315@ifset is-C
316@findex rtems_timer_cancel
317@example
318rtems_status_code rtems_timer_cancel(
319  rtems_id id
320);
321@end example
322@end ifset
323
324@ifset is-Ada
325@example
326procedure Timer_Cancel (
327   ID     : in     RTEMS.ID;
328   Result :    out RTEMS.Status_Codes
329);
330@end example
331@end ifset
332
333@subheading DIRECTIVE STATUS CODES:
334@code{@value{RPREFIX}SUCCESSFUL} - timer canceled successfully@*
335@code{@value{RPREFIX}INVALID_ID} - invalid timer id
336
337@subheading DESCRIPTION:
338
339This directive cancels the timer id.  This timer will
340be reinitiated by the next invocation of @code{@value{DIRPREFIX}timer_reset},
341@code{@value{DIRPREFIX}timer_fire_after}, or
342@code{@value{DIRPREFIX}timer_fire_when} with this id.
343
344@subheading NOTES:
345
346This directive will not cause the running task to be preempted.
347
348@c
349@c
350@c
351@page
352@subsection TIMER_DELETE - Delete a timer
353
354@cindex delete a timer
355
356@subheading CALLING SEQUENCE:
357
358@ifset is-C
359@findex rtems_timer_delete
360@example
361rtems_status_code rtems_timer_delete(
362  rtems_id id
363);
364@end example
365@end ifset
366
367@ifset is-Ada
368@example
369procedure Timer_Delete (
370   ID     : in     RTEMS.ID;
371   Result :    out RTEMS.Status_Codes
372);
373@end example
374@end ifset
375
376@subheading DIRECTIVE STATUS CODES:
377@code{@value{RPREFIX}SUCCESSFUL} - timer deleted successfully@*
378@code{@value{RPREFIX}INVALID_ID} - invalid timer id
379
380@subheading DESCRIPTION:
381
382This directive deletes the timer specified by id.  If
383the timer is running, it is automatically canceled.  The TMCB
384for the deleted timer is reclaimed by RTEMS.
385
386@subheading NOTES:
387
388This directive will not cause the running task to be
389preempted.
390
391A timer can be deleted by a task other than the task
392which created the timer.
393
394@c
395@c
396@c
397@page
398@subsection TIMER_FIRE_AFTER - Fire timer after interval
399
400@cindex fire a timer after an interval
401
402@subheading CALLING SEQUENCE:
403
404@ifset is-C
405@findex rtems_timer_fire_after
406@example
407rtems_status_code rtems_timer_fire_after(
408  rtems_id                           id,
409  rtems_interval                     ticks,
410  rtems_timer_service_routine_entry  routine,
411  void                              *user_data
412);
413@end example
414@end ifset
415
416@ifset is-Ada
417@example
418procedure Timer_Fire_After (
419   ID        : in     RTEMS.ID;
420   Ticks     : in     RTEMS.Interval;
421   Routine   : in     RTEMS.Timer_Service_Routine;
422   User_Data : in     RTEMS.Address;
423   Result    :    out RTEMS.Status_Codes
424);
425@end example
426@end ifset
427
428@subheading DIRECTIVE STATUS CODES:
429@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
430@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
431@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
432@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval
433
434@subheading DESCRIPTION:
435
436This directive initiates the timer specified by id.
437If the timer is running, it is automatically canceled before
438being initiated.  The timer is scheduled to fire after an
439interval ticks clock ticks has passed.  When the timer fires,
440the timer service routine routine will be invoked with the
441argument user_data.
442
443@subheading NOTES:
444
445This directive will not cause the running task to be
446preempted.
447
448@c
449@c
450@c
451@page
452@subsection TIMER_FIRE_WHEN - Fire timer when specified
453
454@cindex fire a timer at wall time
455
456@subheading CALLING SEQUENCE:
457
458@ifset is-C
459@findex rtems_timer_fire_when
460@example
461rtems_status_code rtems_timer_fire_when(
462  rtems_id                           id,
463  rtems_time_of_day                 *wall_time,
464  rtems_timer_service_routine_entry  routine,
465  void                              *user_data
466);
467@end example
468@end ifset
469
470@ifset is-Ada
471@example
472procedure Timer_Fire_When (
473   ID        : in     RTEMS.ID;
474   Wall_Time : in     RTEMS.Time_Of_Day;
475   Routine   : in     RTEMS.Timer_Service_Routine;
476   User_Data : in     RTEMS.Address;
477   Result    :    out RTEMS.Status_Codes
478);
479@end example
480@end ifset
481
482@subheading DIRECTIVE STATUS CODES:
483@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
484@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
485@code{@value{RPREFIX}INVALID_ADDRESS} - @code{wall_time} is NULL@*
486@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
487@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
488@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day
489
490@subheading DESCRIPTION:
491
492This directive initiates the timer specified by id.
493If the timer is running, it is automatically canceled before
494being initiated.  The timer is scheduled to fire at the time of
495day specified by wall_time.  When the timer fires, the timer
496service routine routine will be invoked with the argument
497user_data.
498
499@subheading NOTES:
500
501This directive will not cause the running task to be
502preempted.
503
504@c
505@c
506@c
507@page
508@subsection TIMER_INITIATE_SERVER - Initiate server for task-based timers
509
510@cindex initiate the Timer Server
511
512@subheading CALLING SEQUENCE:
513
514@ifset is-C
515@findex rtems_timer_initiate_server
516@example
517rtems_status_code rtems_timer_initiate_server(
518  rtems_unsigned32     priority,
519  rtems_unsigned32     stack_size,
520  rtems_attribute      attribute_set
521)
522);
523@end example
524@end ifset
525
526@ifset is-Ada
527@example
528procedure Timer_Initiate_Server (
529   Server_Priority : in     RTEMS.Task_Priority;
530   Stack_Size      : in     RTEMS.Unsigned32;
531   Attribute_Set   : in     RTEMS.Attribute;
532   Result          :    out RTEMS.Status_Codes
533);
534@end example
535@end ifset
536
537@subheading DIRECTIVE STATUS CODES:
538@code{@value{RPREFIX}SUCCESSFUL} - Timer Server initiated successfully@*
539@code{@value{RPREFIX}TOO_MANY} - too many tasks created
540
541@subheading DESCRIPTION:
542
543This directive initiates the Timer Server task.  This task
544is responsible for executing all timers initiated via the
545@code{@value{DIRPREFIX}timer_server_fire_after} or
546@code{@value{DIRPREFIX}timer_server_fire_when} directives.
547
548@subheading NOTES:
549
550This directive could cause the calling task to be preempted.
551
552The Timer Server task is created using the
553@code{@value{DIRPREFIX}task_create} service and must be accounted
554for when configuring the system.
555
556Even through this directive invokes the @code{@value{DIRPREFIX}task_create}
557and @code{@value{DIRPREFIX}task_start} directives, it should only fail
558due to resource allocation problems.
559
560@c
561@c
562@c
563@page
564@subsection TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
565
566@cindex fire task-based a timer after an interval
567
568@subheading CALLING SEQUENCE:
569
570@ifset is-C
571@findex rtems_timer_server_fire_after
572@example
573rtems_status_code rtems_timer_server_fire_after(
574  rtems_id                           id,
575  rtems_interval                     ticks,
576  rtems_timer_service_routine_entry  routine,
577  void                              *user_data
578);
579@end example
580@end ifset
581
582@ifset is-Ada
583@example
584procedure Timer_Fire_Server_After (
585   ID        : in     RTEMS.ID;
586   Ticks     : in     RTEMS.Interval;
587   Routine   : in     RTEMS.Timer_Service_Routine;
588   User_Data : in     RTEMS.Address;
589   Result    :    out RTEMS.Status_Codes
590);
591@end example
592@end ifset
593
594@subheading DIRECTIVE STATUS CODES:
595@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
596@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
597@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
598@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval@*
599@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated
600
601@subheading DESCRIPTION:
602
603This directive initiates the timer specified by id and specifies
604that when it fires it will be executed by the Timer Server.
605
606If the timer is running, it is automatically canceled before
607being initiated.  The timer is scheduled to fire after an
608interval ticks clock ticks has passed.  When the timer fires,
609the timer service routine routine will be invoked with the
610argument user_data.
611
612@subheading NOTES:
613
614This directive will not cause the running task to be
615preempted.
616
617@c
618@c
619@c
620@page
621@subsection TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
622
623@cindex fire a task-based timer at wall time
624
625@subheading CALLING SEQUENCE:
626
627@ifset is-C
628@findex rtems_timer_server_fire_when
629@example
630rtems_status_code rtems_timer_server_fire_when(
631  rtems_id                           id,
632  rtems_time_of_day                 *wall_time,
633  rtems_timer_service_routine_entry  routine,
634  void                              *user_data
635);
636@end example
637@end ifset
638
639@ifset is-Ada
640@example
641procedure Timer_Fire_Server_When (
642   ID        : in     RTEMS.ID;
643   Wall_Time : in     RTEMS.Time_Of_Day;
644   Routine   : in     RTEMS.Timer_Service_Routine;
645   User_Data : in     RTEMS.Address;
646   Result    :    out RTEMS.Status_Codes
647);
648@end example
649@end ifset
650
651@subheading DIRECTIVE STATUS CODES:
652@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
653@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
654@code{@value{RPREFIX}INVALID_ADDRESS} - @code{wall_time} is NULL@*
655@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
656@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
657@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day@*
658@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated
659
660@subheading DESCRIPTION:
661
662This directive initiates the timer specified by id and specifies
663that when it fires it will be executed by the Timer Server.
664
665If the timer is running, it is automatically canceled before
666being initiated.  The timer is scheduled to fire at the time of
667day specified by wall_time.  When the timer fires, the timer
668service routine routine will be invoked with the argument
669user_data.
670
671@subheading NOTES:
672
673This directive will not cause the running task to be
674preempted.
675
676@c
677@c
678@c
679@page
680@subsection TIMER_RESET - Reset an interval timer
681
682@cindex reset a timer
683
684@subheading CALLING SEQUENCE:
685
686@ifset is-C
687@findex rtems_timer_reset
688@example
689rtems_status_code rtems_timer_reset(
690  rtems_id   id
691);
692@end example
693@end ifset
694
695@ifset is-Ada
696@example
697procedure Timer_Reset (
698   ID     : in     RTEMS.ID;
699   Result :    out RTEMS.Status_Codes
700);
701@end example
702@end ifset
703
704@subheading DIRECTIVE STATUS CODES:
705@code{@value{RPREFIX}SUCCESSFUL} - timer reset successfully@*
706@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
707@code{@value{RPREFIX}NOT_DEFINED} - attempted to reset a when or newly created timer
708
709@subheading DESCRIPTION:
710
711This directive resets the timer associated with id.
712This timer must have been previously initiated with either the
713@code{@value{DIRPREFIX}timer_fire_after} or
714@code{@value{DIRPREFIX}timer_server_fire_after}
715directive.  If active the timer is canceled,
716after which the timer is reinitiated using the same interval and
717timer service routine which the original
718@code{@value{DIRPREFIX}timer_fire_after}
719@code{@value{DIRPREFIX}timer_server_fire_after}
720directive used.
721
722@subheading NOTES:
723
724If the timer has not been used or the last usage of this timer
725was by a @code{@value{DIRPREFIX}timer_fire_when} or
726@code{@value{DIRPREFIX}timer_server_fire_when}
727directive, then the @code{@value{RPREFIX}NOT_DEFINED} error is
728returned.
729
730Restarting a cancelled after timer results in the timer being
731reinitiated with its previous timer service routine and interval.
732
733This directive will not cause the running task to be preempted.
734
Note: See TracBrowser for help on using the repository browser.