source: rtems/cpukit/rtems/include/rtems/rtems/timer.h @ c499856

4.115
Last change on this file since c499856 was c499856, checked in by Chris Johns <chrisj@…>, on 03/20/14 at 21:10:47

Change all references of rtems.com to rtems.org.

  • Property mode set to 100644
File size: 10.7 KB
Line 
1/**
2 * @file rtems/rtems/timer.h
3 *
4 * @defgroup ClassicTimer Timers
5 *
6 * @ingroup ClassicRTEMS
7 * @brief Instantiate RTEMS Timer Data
8 *
9 * This include file contains all the constants, structures, and
10 * prototypes associated with the Timer Manager. This manager provides
11 * facilities to configure, initiate, cancel, and delete timers which will
12 * fire at specified intervals of time.
13 *
14 * Directives provided are:
15 *
16 * - create a timer
17 * - get an ID of a timer
18 * - delete a timer
19 * - set timer to fire in context of clock tick
20 * - after a number of ticks have passed
21 * - when a specified date and time has been reached
22 * - initiate the timer server task
23 * - set timer to fire in context of the timer server task
24 * - after a number of ticks have passed
25 * - when a specified date and time has been reached
26 * - reset a timer
27 * - cancel a time
28 */
29
30/*
31 * COPYRIGHT (c) 1989-2011.
32 * On-Line Applications Research Corporation (OAR).
33 *
34 * Copyright (c) 2009 embedded brains GmbH.
35 *
36 * The license and distribution terms for this file may be
37 * found in the file LICENSE in this distribution or at
38 * http://www.rtems.org/license/LICENSE.
39 */
40
41#ifndef _RTEMS_RTEMS_TIMER_H
42#define _RTEMS_RTEMS_TIMER_H
43
44#include <rtems/rtems/attr.h>
45#include <rtems/rtems/status.h>
46#include <rtems/rtems/types.h>
47
48#ifdef __cplusplus
49extern "C" {
50#endif
51
52/**
53 *  @defgroup ClassicTimer Timers
54 *
55 *  @ingroup ClassicRTEMS
56 *
57 *  This encapsulates functionality related to the Classic API Timer
58 *  Manager.  This manager provides functionality which allows the
59 *  application to schedule the execution of methods at a specified
60 *  time in the future.  These methods may be scheduled based upon
61 *  interval or wall time and may be executed in either the clock tick
62 *  ISR or in a special dedicated timer server task.
63 */
64/**@{*/
65
66/**
67 *  The following enumerated type details the classes to which a timer
68 *  may belong.
69 */
70typedef enum {
71  /**
72   * This value indicates the timer is currently in use as an interval
73   * timer which will fire in the clock tick ISR.
74   */
75  TIMER_INTERVAL,
76
77  /**
78   * This value indicates the timer is currently in use as an interval
79   * timer which will fire in the timer server task.
80   */
81  TIMER_INTERVAL_ON_TASK,
82
83  /**
84   * This value indicates the timer is currently in use as an time of day
85   * timer which will fire in the clock tick ISR.
86   */
87  TIMER_TIME_OF_DAY,
88
89  /**
90   * This value indicates the timer is currently in use as an time of day
91   * timer which will fire in the timer server task.
92   */
93  TIMER_TIME_OF_DAY_ON_TASK,
94
95  /**
96   * This value indicates the timer is currently not in use.
97   */
98  TIMER_DORMANT
99} Timer_Classes;
100
101/**
102 *  The following types define a pointer to a timer service routine.
103 */
104typedef void rtems_timer_service_routine;
105
106/**
107 *  This type defines the type used to manage and indirectly invoke
108 *  Timer Service Routines (TSRs).  This defines the prototype and interface
109 *  for a function which is to be used as a TSR.
110 */
111typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
112                 rtems_id,
113                 void *
114             );
115
116/**
117 *  The following records define the control block used to manage
118 *  each timer.
119 */
120typedef struct {
121  /** This field is the object management portion of a Timer instance. */
122  Objects_Control  Object;
123  /** This field is the Watchdog instance which will be the scheduled. */
124  Watchdog_Control Ticker;
125  /** This field indicates what type of timer this currently is. */
126  Timer_Classes    the_class;
127}   Timer_Control;
128
129/**
130 * @brief RTEMS Create Timer
131 *
132 * This routine implements the rtems_timer_create directive. The
133 * timer will have the name name. It returns the id of the
134 * created timer in ID.
135 *
136 * @param[in] name is the timer name
137 * @param[out] id is the pointer to timer id
138 *
139 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
140 */
141rtems_status_code rtems_timer_create(
142  rtems_name    name,
143  rtems_id     *id
144);
145
146/**
147 * @brief RTEMS Timer Name to Id
148 *
149 * This routine implements the rtems_timer_ident directive.
150 * This directive returns the timer ID associated with name.
151 * If more than one timer is named name, then the timer
152 * to which the ID belongs is arbitrary.
153 *
154 * @param[in] name is the user defined message queue name
155 * @param[in] id is the pointer to timer id
156 *
157 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
158 * id filled with the message queue id
159 */
160rtems_status_code rtems_timer_ident(
161  rtems_name    name,
162  rtems_id     *id
163);
164
165/**
166 *  @brief rtems_timer_cancel
167 *
168 *  This routine implements the rtems_timer_cancel directive.  It is used
169 *  to stop the timer associated with ID from firing.
170 */
171rtems_status_code rtems_timer_cancel(
172  rtems_id   id
173);
174
175/**
176 * @brief RTEMS Delete Timer
177 *
178 * This routine implements the rtems_timer_delete directive. The
179 * timer indicated by ID is deleted.
180 *
181 * @param[in] id is the timer id
182 *
183 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
184 *         error. Otherwise, a status code is returned indicating the
185 *         source of the error.
186 */
187rtems_status_code rtems_timer_delete(
188  rtems_id   id
189);
190
191/**
192 * @brief RTEMS Timer Fire After
193 *
194 * This routine implements the rtems_timer_fire_after directive. It
195 * initiates the timer associated with ID to fire in ticks clock ticks.
196 * When the timer fires, the routine will be invoked in the context
197 * of the rtems_clock_tick directive which is normally invoked as
198 * part of servicing a periodic interupt.
199 *
200 * @param[in] id is the timer id
201 * @param[in] ticks is the interval until routine is fired
202 * @param[in] routine is the routine to schedule
203 * @param[in] user_data is the passed as argument to routine when it is fired
204 *
205 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
206 *         error. Otherwise, a status code is returned indicating the
207 *         source of the error.
208 */
209rtems_status_code rtems_timer_fire_after(
210  rtems_id                           id,
211  rtems_interval                     ticks,
212  rtems_timer_service_routine_entry  routine,
213  void                              *user_data
214);
215
216/**
217 * @brief RTEMS Timer Server Fire After
218 *
219 * This routine implements the rtems_timer_server_fire_after directive. It
220 * initiates the timer associated with ID to fire in ticks clock
221 * ticks. When the timer fires, the routine will be invoked by the
222 * Timer Server in the context of a task NOT IN THE CONTEXT of the
223 * clock tick interrupt.
224 *
225 * @param[in] id is the timer id
226 * @param[in] ticks is the interval until routine is fired
227 * @param[in] routine is the routine to schedule
228 * @param[in] user_data is the passed as argument to routine when it is fired
229 *
230 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
231 *         error. Otherwise, a status code is returned indicating the
232 *         source of the error.
233 */
234rtems_status_code rtems_timer_server_fire_after(
235  rtems_id                           id,
236  rtems_interval                     ticks,
237  rtems_timer_service_routine_entry  routine,
238  void                              *user_data
239);
240
241/**
242 * @brief RTEMS Timer Fire When
243 *
244 * This routine implements the rtems_timer_fire_when directive. It
245 * initiates the timer associated with ID to fire at wall_time
246 * When the timer fires, the routine will be invoked in the context
247 * of the rtems_clock_tick directive which is normally invoked as
248 * part of servicing a periodic interupt.
249 *
250 * @param[in] id is the timer id
251 * @param[in] wall_time is the time of day to fire timer
252 * @param[in] routine is the routine to schedule
253 * @param[in] user_data is the passed as argument to routine when it is fired
254 *
255 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
256 *         error. Otherwise, a status code is returned indicating the
257 *         source of the error.
258 */
259rtems_status_code rtems_timer_fire_when(
260  rtems_id                            id,
261  rtems_time_of_day                  *wall_time,
262  rtems_timer_service_routine_entry   routine,
263  void                               *user_data
264);
265
266/**
267 *  @brief RTEMS Timer Server Fire When Directive
268 *
269 *  Timer Manager - RTEMS Timer Server Fire When Directive
270 *
271 *  This routine implements the rtems_timer_server_fire_when directive.  It
272 *  initiates the timer associated with ID to fire at wall_time
273 *  When the timer fires, the routine will be invoked by the
274 *  Timer Server in the context of a task NOT IN THE CONTEXT of the
275 *  clock tick interrupt.
276 */
277rtems_status_code rtems_timer_server_fire_when(
278  rtems_id                            id,
279  rtems_time_of_day                  *wall_time,
280  rtems_timer_service_routine_entry   routine,
281  void                               *user_data
282);
283
284/**
285 *  @brief RTEMS Timer Reset
286 *
287 *  Timer Manager - RTEMS Timer Reset
288 *
289 *  This routine implements the rtems_timer_reset directive.  It is used
290 *  to reinitialize the interval timer associated with ID just as if
291 *  rtems_timer_fire_after were re-invoked with the same arguments that
292 *  were used to initiate this timer.
293 */
294rtems_status_code rtems_timer_reset(
295  rtems_id   id
296);
297
298/**
299 *  @brief rtems_timer_initiate_server
300 *
301 *  This routine implements the rtems_timer_initiate_server directive.
302 *  It creates and starts the server that executes task-based timers.
303 *  It must be invoked before any task-based timers can be initiated.
304 */
305rtems_status_code rtems_timer_initiate_server(
306  uint32_t             priority,
307  uint32_t             stack_size,
308  rtems_attribute      attribute_set
309);
310
311/**
312 *  This is the default value for the priority of the Timer Server.
313 *  When given this priority, a special high priority not accessible
314 *  via the Classic API is used.
315 */
316#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY (uint32_t) -1
317
318/**
319 *  This is the structure filled in by the timer get information
320 *  service.
321 */
322typedef struct {
323  /** This indicates the current type of the timer. */
324  Timer_Classes      the_class;
325  /** This indicates the initial requested interval. */
326  Watchdog_Interval  initial;
327  /** This indicates the time the timer was initially scheduled. */
328  Watchdog_Interval  start_time;
329  /** This indicates the time the timer is scheduled to fire. */
330  Watchdog_Interval  stop_time;
331} rtems_timer_information;
332
333/**
334 * @brief RTEMS Get Timer Information
335 *
336 * This routine implements the rtems_timer_get_information directive.
337 * This directive returns information about the timer.
338 *
339 * @param[in] id is the timer id
340 * @param[in] the_info is the pointer to timer information block
341 *
342 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
343 *              *the_info region information block filled in
344 */
345rtems_status_code rtems_timer_get_information(
346  rtems_id                 id,
347  rtems_timer_information *the_info
348);
349
350/**@}*/
351
352#ifdef __cplusplus
353}
354#endif
355
356#endif
357/* end of include file */
Note: See TracBrowser for help on using the repository browser.