source: rtems-docs/c_user/timer_manager.rst @ 859f0b7

4.115
Last change on this file since 859f0b7 was 859f0b7, checked in by Chris Johns <chrisj@…>, on 01/27/16 at 00:27:31

Add an rtems-table class to wrap and align HTML tables.

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