source: rtems-docs/c_user/timer_manager.rst @ fd6dc8c8

4.115
Last change on this file since fd6dc8c8 was fd6dc8c8, checked in by Amar Takhar <amar@…>, on 01/18/16 at 00:19:43

Split document into seperate files by section.

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