source: rtems-docs/c-user/timer_manager.rst @ 39773ce

5
Last change on this file since 39773ce was 1161ed1, checked in by Sebastian Huber <sebastian.huber@…>, on 01/30/17 at 13:22:14

c-user: Update timer manager

Update #2554.

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