source: rtems/cpukit/include/rtems/rtems/timer.h @ 6abdd89

Last change on this file since 6abdd89 was 6abdd89, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 14, 2021 at 7:57:51 AM

Use a common phrase for pointer parameters

Mention the type of the pointer in the parameter description. Use the
more general term "object" instead of "variable".

Update #3993.

  • Property mode set to 100644
File size: 24.8 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @ingroup RTEMSImplClassicTimer
7 *
8 * @brief This header file provides the Timer Manager API.
9 */
10
11/*
12 * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
13 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
14 *
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
17 * are met:
18 * 1. Redistributions of source code must retain the above copyright
19 *    notice, this list of conditions and the following disclaimer.
20 * 2. Redistributions in binary form must reproduce the above copyright
21 *    notice, this list of conditions and the following disclaimer in the
22 *    documentation and/or other materials provided with the distribution.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
28 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 * POSSIBILITY OF SUCH DAMAGE.
35 */
36
37/*
38 * This file is part of the RTEMS quality process and was automatically
39 * generated.  If you find something that needs to be fixed or
40 * worded better please post a report or patch to an RTEMS mailing list
41 * or raise a bug report:
42 *
43 * https://www.rtems.org/bugs.html
44 *
45 * For information on updating and regenerating please refer to the How-To
46 * section in the Software Requirements Engineering chapter of the
47 * RTEMS Software Engineering manual.  The manual is provided as a part of
48 * a release.  For development sources please refer to the online
49 * documentation at:
50 *
51 * https://docs.rtems.org
52 */
53
54/* Generated from spec:/rtems/timer/if/header */
55
56#ifndef _RTEMS_RTEMS_TIMER_H
57#define _RTEMS_RTEMS_TIMER_H
58
59#include <stddef.h>
60#include <rtems/rtems/attr.h>
61#include <rtems/rtems/status.h>
62#include <rtems/rtems/types.h>
63#include <rtems/score/watchdogticks.h>
64
65#ifdef __cplusplus
66extern "C" {
67#endif
68
69/* Generated from spec:/rtems/timer/if/group */
70
71/**
72 * @defgroup RTEMSAPIClassicTimer Timer Manager
73 *
74 * @ingroup RTEMSAPIClassic
75 *
76 * @brief The Timer Manager provides support for timer facilities.
77 */
78
79/* Generated from spec:/rtems/timer/if/class-bit-not-dormant */
80
81/**
82 * @ingroup RTEMSAPIClassicTimer
83 *
84 * @brief This timer class bit indicates that the timer is not dormant.
85 */
86#define TIMER_CLASS_BIT_NOT_DORMANT 0x4
87
88/* Generated from spec:/rtems/timer/if/class-bit-on-task */
89
90/**
91 * @ingroup RTEMSAPIClassicTimer
92 *
93 * @brief This timer class bit indicates that the timer routine executes in a
94 *   task context.
95 */
96#define TIMER_CLASS_BIT_ON_TASK 0x2
97
98/* Generated from spec:/rtems/timer/if/class-bit-time-of-day */
99
100/**
101 * @ingroup RTEMSAPIClassicTimer
102 *
103 * @brief This timer class bit indicates that the timer uses a time of day.
104 */
105#define TIMER_CLASS_BIT_TIME_OF_DAY 0x1
106
107/* Generated from spec:/rtems/timer/if/classes */
108
109/**
110 * @ingroup RTEMSAPIClassicTimer
111 *
112 * @brief The timer class indicates how the timer was most recently fired.
113 */
114typedef enum {
115  /**
116   * @brief This timer class indicates that the timer was never in use.
117   */
118  TIMER_DORMANT,
119
120  /**
121   * @brief This timer class indicates that the timer is currently in use as an
122   *   interval timer which will fire in the context of the clock tick ISR.
123   */
124  TIMER_INTERVAL = TIMER_CLASS_BIT_NOT_DORMANT,
125
126  /**
127   * @brief This timer class indicates that the timer is currently in use as an
128   *   interval timer which will fire in the context of the Timer Server task.
129   */
130  TIMER_INTERVAL_ON_TASK = TIMER_CLASS_BIT_NOT_DORMANT |
131    TIMER_CLASS_BIT_ON_TASK,
132
133  /**
134   * @brief This timer class indicates that the timer is currently in use as an
135   *   time of day timer which will fire in the context of the clock tick ISR.
136   */
137  TIMER_TIME_OF_DAY = TIMER_CLASS_BIT_NOT_DORMANT |
138    TIMER_CLASS_BIT_TIME_OF_DAY,
139
140  /**
141   * @brief This timer class indicates that the timer is currently in use as an
142   *   time of day timer which will fire in the context of the Timer Server task.
143   */
144  TIMER_TIME_OF_DAY_ON_TASK = TIMER_CLASS_BIT_NOT_DORMANT |
145    TIMER_CLASS_BIT_TIME_OF_DAY |
146    TIMER_CLASS_BIT_ON_TASK
147} Timer_Classes;
148
149/* Generated from spec:/rtems/timer/if/information */
150
151/**
152 * @ingroup RTEMSAPIClassicTimer
153 *
154 * @brief The structure contains information about a timer.
155 */
156typedef struct {
157  /**
158   * @brief The timer class member indicates how the timer was most recently
159   *   fired.
160   */
161  Timer_Classes the_class;
162
163  /**
164   * @brief This member indicates the initial requested interval.
165   */
166  Watchdog_Interval initial;
167
168  /**
169   * @brief This member indicates the time the timer was initially scheduled.
170   *
171   * The time is in clock ticks since the clock driver initialization or the last
172   * clock tick counter overflow.
173   */
174  Watchdog_Interval start_time;
175
176  /**
177   * @brief This member indicates the time the timer was scheduled to fire.
178   *
179   * The time is in clock ticks since the clock driver initialization or the last
180   * clock tick counter overflow.
181   */
182  Watchdog_Interval stop_time;
183} rtems_timer_information;
184
185/* Generated from spec:/rtems/timer/if/get-information */
186
187/**
188 * @ingroup RTEMSAPIClassicTimer
189 *
190 * @brief Gets information about the timer.
191 *
192 * @param id is the timer identifier.
193 *
194 * @param[out] the_info is the pointer to an rtems_timer_information object.
195 *   When the directive call is successful, the information about the timer
196 *   will be stored in this object.
197 *
198 * This directive returns information about the timer.
199 *
200 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
201 *
202 * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
203 *
204 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
205 *   specified by ``id``.
206 *
207 * @par Constraints
208 * @parblock
209 * The following constraints apply to this directive:
210 *
211 * * The directive may be called from within interrupt context.
212 *
213 * * The directive may be called from within device driver initialization
214 *   context.
215 *
216 * * The directive may be called from within task context.
217 *
218 * * The directive will not cause the calling task to be preempted.
219 * @endparblock
220 */
221rtems_status_code rtems_timer_get_information(
222  rtems_id                 id,
223  rtems_timer_information *the_info
224);
225
226/* Generated from spec:/rtems/timer/if/server-default-priority */
227
228/**
229 * @ingroup RTEMSAPIClassicTimer
230 *
231 * @brief This constant represents the default value for the task priority of
232 *   the Timer Server.
233 *
234 * When given this priority, a special high priority not accessible via the
235 * Classic API is used.
236 */
237#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY ( (rtems_task_priority) -1 )
238
239/* Generated from spec:/rtems/timer/if/service-routine */
240
241/**
242 * @ingroup RTEMSAPIClassicTimer
243 *
244 * @brief This type defines the return type of routines which can be fired by
245 *   directives of the Timer Manager.
246 *
247 * This type can be used to document timer service routines in the source code.
248 */
249typedef void rtems_timer_service_routine;
250
251/* Generated from spec:/rtems/timer/if/service-routine-entry */
252
253/**
254 * @ingroup RTEMSAPIClassicTimer
255 *
256 * @brief This type defines the prototype of routines which can be fired by
257 *   directives of the Timer Manager.
258 */
259typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtems_id, void * );
260
261/* Generated from spec:/rtems/timer/if/create */
262
263/**
264 * @ingroup RTEMSAPIClassicTimer
265 *
266 * @brief Creates a timer.
267 *
268 * @param name is the object name of the timer.
269 *
270 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
271 *   call is successful, the identifier of the created timer will be stored in
272 *   this object.
273 *
274 * This directive creates a timer which resides on the local node.  The timer
275 * has the user-defined object name specified in ``name``.  The assigned object
276 * identifier is returned in ``id``.  This identifier is used to access the
277 * timer with other timer related directives.
278 *
279 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
280 *
281 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
282 *
283 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
284 *
285 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
286 *   timer.  The number of timers available to the application is configured
287 *   through the #CONFIGURE_MAXIMUM_TIMERS application configuration option.
288 *
289 * @par Notes
290 * @parblock
291 * The processor used to maintain the timer is the processor of the calling
292 * task at some point during the timer creation.
293 *
294 * For control and maintenance of the timer, RTEMS allocates a TMCB from the
295 * local TMCB free pool and initializes it.
296 * @endparblock
297 *
298 * @par Constraints
299 * @parblock
300 * The following constraints apply to this directive:
301 *
302 * * The directive may be called from within device driver initialization
303 *   context.
304 *
305 * * The directive may be called from within task context.
306 *
307 * * The directive may obtain and release the object allocator mutex.  This may
308 *   cause the calling task to be preempted.
309 *
310 * * The number of timers available to the application is configured through
311 *   the #CONFIGURE_MAXIMUM_TIMERS application configuration option.
312 *
313 * * Where the object class corresponding to the directive is configured to use
314 *   unlimited objects, the directive may allocate memory from the RTEMS
315 *   Workspace.
316 * @endparblock
317 */
318rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
319
320/* Generated from spec:/rtems/timer/if/ident */
321
322/**
323 * @ingroup RTEMSAPIClassicTimer
324 *
325 * @brief Identifies a timer by the object name.
326 *
327 * @param name is the object name to look up.
328 *
329 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
330 *   call is successful, the object identifier of an object with the specified
331 *   name will be stored in this object.
332 *
333 * This directive obtains a timer identifier associated with the timer name
334 * specified in ``name``.
335 *
336 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
337 *
338 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
339 *
340 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
341 *
342 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
343 *   the local node.
344 *
345 * @par Notes
346 * @parblock
347 * If the timer name is not unique, then the timer identifier will match the
348 * first timer with that name in the search order.  However, this timer
349 * identifier is not guaranteed to correspond to the desired timer.
350 *
351 * The objects are searched from lowest to the highest index.  Only the local
352 * node is searched.
353 *
354 * The timer identifier is used with other timer related directives to access
355 * the timer.
356 * @endparblock
357 *
358 * @par Constraints
359 * @parblock
360 * The following constraints apply to this directive:
361 *
362 * * The directive may be called from within any runtime context.
363 *
364 * * The directive will not cause the calling task to be preempted.
365 * @endparblock
366 */
367rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );
368
369/* Generated from spec:/rtems/timer/if/cancel */
370
371/**
372 * @ingroup RTEMSAPIClassicTimer
373 *
374 * @brief Cancels the timer.
375 *
376 * @param id is the timer identifier.
377 *
378 * This directive cancels the timer specified by ``id``.  This timer will be
379 * reinitiated by the next invocation of rtems_timer_reset(),
380 * rtems_timer_fire_after(), rtems_timer_fire_when(),
381 * rtems_timer_server_fire_after(), or rtems_timer_server_fire_when() with the
382 * same timer identifier.
383 *
384 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
385 *
386 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
387 *   specified by ``id``.
388 *
389 * @par Constraints
390 * @parblock
391 * The following constraints apply to this directive:
392 *
393 * * The directive may be called from within interrupt context.
394 *
395 * * The directive may be called from within device driver initialization
396 *   context.
397 *
398 * * The directive may be called from within task context.
399 *
400 * * The directive will not cause the calling task to be preempted.
401 * @endparblock
402 */
403rtems_status_code rtems_timer_cancel( rtems_id id );
404
405/* Generated from spec:/rtems/timer/if/delete */
406
407/**
408 * @ingroup RTEMSAPIClassicTimer
409 *
410 * @brief Deletes the timer.
411 *
412 * @param id is the timer identifier.
413 *
414 * This directive deletes the timer specified by ``id``.  If the timer is
415 * running, it is automatically canceled.
416 *
417 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
418 *
419 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
420 *   specified by ``id``.
421 *
422 * @par Notes
423 * The TMCB for the deleted timer is reclaimed by RTEMS.
424 *
425 * @par Constraints
426 * @parblock
427 * The following constraints apply to this directive:
428 *
429 * * The directive may be called from within device driver initialization
430 *   context.
431 *
432 * * The directive may be called from within task context.
433 *
434 * * The directive may obtain and release the object allocator mutex.  This may
435 *   cause the calling task to be preempted.
436 *
437 * * The calling task does not have to be the task that created the object.
438 *   Any local task that knows the object identifier can delete the object.
439 *
440 * * Where the object class corresponding to the directive is configured to use
441 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
442 * @endparblock
443 */
444rtems_status_code rtems_timer_delete( rtems_id id );
445
446/* Generated from spec:/rtems/timer/if/fire-after */
447
448/**
449 * @ingroup RTEMSAPIClassicTimer
450 *
451 * @brief Fires the timer after the interval.
452 *
453 * @param id is the timer identifier.
454 *
455 * @param ticks is the interval until the routine is fired in clock ticks.
456 *
457 * @param routine is the routine to schedule.
458 *
459 * @param user_data is the argument passed to the routine when it is fired.
460 *
461 * This directive initiates the timer specified by ``id``.  If the timer is
462 * running, it is automatically canceled before being initiated.  The timer is
463 * scheduled to fire after an interval of clock ticks has passed specified by
464 * ``ticks``.  When the timer fires, the timer service routine ``routine`` will
465 * be invoked with the argument ``user_data`` in the context of the clock tick
466 * ISR.
467 *
468 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
469 *
470 * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0.
471 *
472 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
473 *
474 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
475 *   specified by ``id``.
476 *
477 * @par Constraints
478 * @parblock
479 * The following constraints apply to this directive:
480 *
481 * * The directive may be called from within interrupt context.
482 *
483 * * The directive may be called from within device driver initialization
484 *   context.
485 *
486 * * The directive may be called from within task context.
487 *
488 * * The directive will not cause the calling task to be preempted.
489 * @endparblock
490 */
491rtems_status_code rtems_timer_fire_after(
492  rtems_id                          id,
493  rtems_interval                    ticks,
494  rtems_timer_service_routine_entry routine,
495  void                             *user_data
496);
497
498/* Generated from spec:/rtems/timer/if/fire-when */
499
500/**
501 * @ingroup RTEMSAPIClassicTimer
502 *
503 * @brief Fires the timer at the time of day.
504 *
505 * @param id is the timer identifier.
506 *
507 * @param wall_time is the time of day when the routine is fired.
508 *
509 * @param routine is the routine to schedule.
510 *
511 * @param user_data is the argument passed to the routine when it is fired.
512 *
513 * This directive initiates the timer specified by ``id``.  If the timer is
514 * running, it is automatically canceled before being initiated.  The timer is
515 * scheduled to fire at the time of day specified by ``wall_time``.  When the
516 * timer fires, the timer service routine ``routine`` will be invoked with the
517 * argument ``user_data`` in the context of the clock tick ISR.
518 *
519 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
520 *
521 * @retval ::RTEMS_NOT_DEFINED The system date and time was not set.
522 *
523 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
524 *
525 * @retval ::RTEMS_INVALID_ADDRESS The ``wall_time`` parameter was NULL.
526 *
527 * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid.
528 *
529 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
530 *   specified by ``id``.
531 *
532 * @par Constraints
533 * @parblock
534 * The following constraints apply to this directive:
535 *
536 * * The directive may be called from within interrupt context.
537 *
538 * * The directive may be called from within device driver initialization
539 *   context.
540 *
541 * * The directive may be called from within task context.
542 *
543 * * The directive will not cause the calling task to be preempted.
544 * @endparblock
545 */
546rtems_status_code rtems_timer_fire_when(
547  rtems_id                          id,
548  const rtems_time_of_day          *wall_time,
549  rtems_timer_service_routine_entry routine,
550  void                             *user_data
551);
552
553/* Generated from spec:/rtems/timer/if/initiate-server */
554
555/**
556 * @ingroup RTEMSAPIClassicTimer
557 *
558 * @brief Initiates the Timer Server.
559 *
560 * @param priority is the task priority.
561 *
562 * @param stack_size is the task stack size in bytes.
563 *
564 * @param attribute_set is the task attribute set.
565 *
566 * This directive initiates the Timer Server task.  This task is responsible
567 * for executing all timers initiated via the rtems_timer_server_fire_after()
568 * or rtems_timer_server_fire_when() directives.
569 *
570 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
571 *
572 * @retval ::RTEMS_INCORRECT_STATE The Timer Server was already initiated.
573 *
574 * @retval ::RTEMS_INVALID_PRIORITY The task priority was invalid.
575 *
576 * @retval ::RTEMS_TOO_MANY There was no inactive task object available to
577 *   create the Timer Server task.
578 *
579 * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task
580 *   storage area.  The task storage area contains the task stack, the
581 *   thread-local storage, and the floating point context.
582 *
583 * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to
584 *   create the Timer Server task.
585 *
586 * @par Notes
587 * The Timer Server task is created using the rtems_task_create() directive and
588 * must be accounted for when configuring the system.
589 *
590 * @par Constraints
591 * @parblock
592 * The following constraints apply to this directive:
593 *
594 * * The directive may obtain and release the object allocator mutex.  This may
595 *   cause the calling task to be preempted.
596 *
597 * * The directive may be called from within device driver initialization
598 *   context.
599 *
600 * * The directive may be called from within task context.
601 *
602 * * The number of timers available to the application is configured through
603 *   the #CONFIGURE_MAXIMUM_TIMERS application configuration option.
604 *
605 * * Where the object class corresponding to the directive is configured to use
606 *   unlimited objects, the directive may allocate memory from the RTEMS
607 *   Workspace.
608 * @endparblock
609 */
610rtems_status_code rtems_timer_initiate_server(
611  rtems_task_priority priority,
612  size_t              stack_size,
613  rtems_attribute     attribute_set
614);
615
616/* Generated from spec:/rtems/timer/if/server-fire-after */
617
618/**
619 * @ingroup RTEMSAPIClassicTimer
620 *
621 * @brief Fires the timer after the interval using the Timer Server.
622 *
623 * @param id is the timer identifier.
624 *
625 * @param ticks is the interval until the routine is fired in clock ticks.
626 *
627 * @param routine is the routine to schedule.
628 *
629 * @param user_data is the argument passed to the routine when it is fired.
630 *
631 * This directive initiates the timer specified by ``id``.  If the timer is
632 * running, it is automatically canceled before being initiated.  The timer is
633 * scheduled to fire after an interval of clock ticks has passed specified by
634 * ``ticks``.  When the timer fires, the timer service routine ``routine`` will
635 * be invoked with the argument ``user_data`` in the context of the Timer
636 * Server task.
637 *
638 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
639 *
640 * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated.
641 *
642 * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0.
643 *
644 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
645 *
646 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
647 *   specified by ``id``.
648 *
649 * @par Constraints
650 * @parblock
651 * The following constraints apply to this directive:
652 *
653 * * The directive may be called from within interrupt context.
654 *
655 * * The directive may be called from within device driver initialization
656 *   context.
657 *
658 * * The directive may be called from within task context.
659 *
660 * * The directive will not cause the calling task to be preempted.
661 * @endparblock
662 */
663rtems_status_code rtems_timer_server_fire_after(
664  rtems_id                          id,
665  rtems_interval                    ticks,
666  rtems_timer_service_routine_entry routine,
667  void                             *user_data
668);
669
670/* Generated from spec:/rtems/timer/if/server-fire-when */
671
672/**
673 * @ingroup RTEMSAPIClassicTimer
674 *
675 * @brief Fires the timer at the time of day using the Timer Server.
676 *
677 * @param id is the timer identifier.
678 *
679 * @param wall_time is the time of day when the routine is fired.
680 *
681 * @param routine is the routine to schedule.
682 *
683 * @param user_data is the argument passed to the routine when it is fired.
684 *
685 * This directive initiates the timer specified by ``id``.  If the timer is
686 * running, it is automatically canceled before being initiated.  The timer is
687 * scheduled to fire at the time of day specified by ``wall_time``.  When the
688 * timer fires, the timer service routine ``routine`` will be invoked with the
689 * argument ``user_data`` in the context of the Timer Server task.
690 *
691 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
692 *
693 * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated.
694 *
695 * @retval ::RTEMS_NOT_DEFINED The system date and time was not set.
696 *
697 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
698 *
699 * @retval ::RTEMS_INVALID_ADDRESS The ``wall_time`` parameter was NULL.
700 *
701 * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid.
702 *
703 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
704 *   specified by ``id``.
705 *
706 * @par Constraints
707 * @parblock
708 * The following constraints apply to this directive:
709 *
710 * * The directive may be called from within interrupt context.
711 *
712 * * The directive may be called from within device driver initialization
713 *   context.
714 *
715 * * The directive may be called from within task context.
716 *
717 * * The directive will not cause the calling task to be preempted.
718 * @endparblock
719 */
720rtems_status_code rtems_timer_server_fire_when(
721  rtems_id                          id,
722  const rtems_time_of_day          *wall_time,
723  rtems_timer_service_routine_entry routine,
724  void                             *user_data
725);
726
727/* Generated from spec:/rtems/timer/if/reset */
728
729/**
730 * @ingroup RTEMSAPIClassicTimer
731 *
732 * @brief Resets the timer.
733 *
734 * @param id is the timer identifier.
735 *
736 * This directive resets the timer specified by ``id``.  This timer must have
737 * been previously initiated with either the rtems_timer_fire_after() or
738 * rtems_timer_server_fire_after() directive.  If active the timer is canceled,
739 * after which the timer is reinitiated using the same interval and timer
740 * service routine which the original rtems_timer_fire_after() or
741 * rtems_timer_server_fire_after() directive used.
742 *
743 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
744 *
745 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
746 *   specified by ``id``.
747 *
748 * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class.
749 *
750 * @par Notes
751 * @parblock
752 * If the timer has not been used or the last usage of this timer was by a
753 * rtems_timer_fire_when() or rtems_timer_server_fire_when() directive, then
754 * the ::RTEMS_NOT_DEFINED error is returned.
755 *
756 * Restarting a cancelled after timer results in the timer being reinitiated
757 * with its previous timer service routine and interval.
758 * @endparblock
759 *
760 * @par Constraints
761 * @parblock
762 * The following constraints apply to this directive:
763 *
764 * * The directive may be called from within interrupt context.
765 *
766 * * The directive may be called from within device driver initialization
767 *   context.
768 *
769 * * The directive may be called from within task context.
770 *
771 * * The directive will not cause the calling task to be preempted.
772 * @endparblock
773 */
774rtems_status_code rtems_timer_reset( rtems_id id );
775
776#ifdef __cplusplus
777}
778#endif
779
780#endif /* _RTEMS_RTEMS_TIMER_H */
Note: See TracBrowser for help on using the repository browser.