blob: 669dd3ef286f559c0b09c8aa96cf70f69ac6193c [file] [log] [blame]
Wolfgang Denkba94a1b2006-05-30 15:56:48 +02001/**
2 * @file IxTimerCtrl.h
3 * @brief
4 * This is the header file for the Timer Control component.
5 *
6 * The timer callback control component provides a mechanism by which different
7 * client components can start a timer and have a supplied callback function
8 * invoked when the timer expires.
9 * The callbacks are all dispatched from one thread inside this component.
10 * Any component that needs to be called periodically should use this facility
11 * rather than create its own task with a sleep loop.
12 *
13 * @par
14 *
15 * @par
16 * IXP400 SW Release version 2.0
17 *
18 * -- Copyright Notice --
19 *
20 * @par
21 * Copyright 2001-2005, Intel Corporation.
22 * All rights reserved.
23 *
24 * @par
25 * Redistribution and use in source and binary forms, with or without
26 * modification, are permitted provided that the following conditions
27 * are met:
28 * 1. Redistributions of source code must retain the above copyright
29 * notice, this list of conditions and the following disclaimer.
30 * 2. Redistributions in binary form must reproduce the above copyright
31 * notice, this list of conditions and the following disclaimer in the
32 * documentation and/or other materials provided with the distribution.
33 * 3. Neither the name of the Intel Corporation nor the names of its contributors
34 * may be used to endorse or promote products derived from this software
35 * without specific prior written permission.
36 *
37 * @par
38 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
39 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
41 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
42 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
43 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
44 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
45 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
46 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
47 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48 * SUCH DAMAGE.
49 *
50 * @par
51 * -- End of Copyright Notice --
52*/
53
54/**
55 * @defgroup IxTimerCtrl IXP400 Timer Control (IxTimerCtrl) API
56 *
57 * @brief The public API for the IXP400 Timer Control Component.
58 *
59 * @{
60 */
61
62#ifndef IxTimerCtrl_H
63#define IxTimerCtrl_H
64
65
66#include "IxTypes.h"
67/* #include "Ossl.h" */
68
69/*
70 * #defines and macros used in this file.
71 */
72
73/**
74 * @ingroup IxTimerCtrl
75 *
76 * @def IX_TIMERCTRL_NO_FREE_TIMERS
77 *
78 * @brief Timer schedule return code.
79 *
80 * Indicates that the request to start a timer failed because
81 * all available timer resources are used.
82 */
83#define IX_TIMERCTRL_NO_FREE_TIMERS 2
84
85
86/**
87 * @ingroup IxTimerCtrl
88 *
89 * @def IX_TIMERCTRL_PARAM_ERROR
90 *
91 * @brief Timer schedule return code.
92 *
93 * Indicates that the request to start a timer failed because
94 * the client has supplied invalid parameters.
95 */
96#define IX_TIMERCTRL_PARAM_ERROR 3
97
98
99/*
100 * Typedefs whose scope is limited to this file.
101 */
102
103/**
104 * @ingroup IxTimerCtrl
105 *
106 * @brief A typedef for a pointer to a timer callback function.
107 * @para void * - This parameter is supplied by the client when the
108 * timer is started and passed back to the client in the callback.
109 * @note in general timer callback functions should not block or
110 * take longer than 100ms. This constraint is required to ensure that
111 * higher priority callbacks are not held up.
112 * All callbacks are called from the same thread.
113 * This thread is a shared resource.
114 * The parameter passed is provided when the timer is scheduled.
115 */
116typedef void (*IxTimerCtrlTimerCallback)(void *userParam);
117
118
119/**
120 * @ingroup IxTimerCtrl
121 *
122 * @brief List used to identify the users of timers.
123 * @note The order in this list indicates priority. Components appearing
124 * higher in the list will be given priority over components lower in the
125 * list. When adding components, please insert at an appropriate position
126 * for priority ( i.e values should be less than IxTimerCtrlMaxPurpose ) .
127 */
128typedef enum
129{
130 IxTimerCtrlAdslPurpose,
131 /* Insert new purposes above this line only
132 */
133 IxTimerCtrlMaxPurpose
134}
135IxTimerCtrlPurpose;
136
137
138/*
139 * Function definition
140 */
141
142/**
143 * @ingroup IxTimerCtrl
144 *
145 * @fn ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
146 void *userParam,
147 IxTimerCtrlPurpose purpose,
148 UINT32 relativeTime,
149 unsigned *timerId )
150 *
151 * @brief Schedules a callback function to be called after a period of "time".
152 * The callback function should not block or run for more than 100ms.
153 * This function
154 *
155 * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
156 * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
157 * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
158 * decide the priority of callbacks with different purpose.
159 * @param relativeTime UINT32 [in] - time relative to now in milliseconds after which the callback
160 * will be called. The time must be greater than the duration of one OS tick.
161 * @param *timerId unsigned [out] - An id for the callback scheduled.
162 * This id can be used to cancel the callback.
163 * @return
164 * @li IX_SUCCESS - The timer was started successfully.
165 * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
166 * of running timers has been exceeded.
167 * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
168 * a NULL callback func, or the requested timeout is less than one OS tick.
169 * @note This function is re-entrant. The function accesses a list of running timers
170 * and may suspend the calling thread if this list is being accesed by another thread.
171 */
172PUBLIC IX_STATUS
173ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
174 void *userParam,
175 IxTimerCtrlPurpose purpose,
176 UINT32 relativeTime,
177 unsigned *timerId );
178
179
180/**
181 * @ingroup IxTimerCtrl
182 *
183 * @fn ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
184 void *param,
185 IxTimerCtrlPurpose purpose,
186 UINT32 interval,
187 unsigned *timerId )
188 *
189 * @brief Schedules a callback function to be called after a period of "time".
190 * The callback function should not block or run for more than 100ms.
191 *
192 * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
193 * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
194 * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
195 * decide the priority of callbacks with different purpose.
196 * @param interval UINT32 [in] - the interval in milliseconds between calls to func.
197 * @param timerId unsigned [out] - An id for the callback scheduled.
198 * This id can be used to cancel the callback.
199 * @return
200 * @li IX_SUCCESS - The timer was started successfully.
201 * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
202 * of running timers has been exceeded.
203 * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
204 * a NULL callback func, or the requested timeout is less than one OS tick.
205 * @note This function is re-entrant. The function accesses a list of running timers
206 * and may suspend the calling thread if this list is being accesed by another thread.
207 */
208PUBLIC IX_STATUS
209ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
210 void *param,
211 IxTimerCtrlPurpose purpose,
212 UINT32 interval,
213 unsigned *timerId );
214
215/**
216 * @ingroup IxTimerCtrl
217 *
218 * @fn ixTimerCtrlCancel (unsigned id)
219 *
220 * @brief Cancels a scheduled callback.
221 *
222 * @param id unsigned [in] - the id of the callback to be cancelled.
223 * @return
224 * @li IX_SUCCESS - The timer was successfully stopped.
225 * @li IX_FAIL - The id parameter did not corrrespond to any running timer..
226 * @note This function is re-entrant. The function accesses a list of running timers
227 * and may suspend the calling thread if this list is being accesed by another thread.
228 */
229PUBLIC IX_STATUS
230ixTimerCtrlCancel (unsigned id);
231
232/**
233 * @ingroup IxTimerCtrl
234 *
235 * @fn ixTimerCtrlInit(void)
236 *
237 * @brief Initialise the Timer Control Component.
238 * @return
239 * @li IX_SUCCESS - The timer control component initialized successfully.
240 * @li IX_FAIL - The timer control component initialization failed,
241 * or the component was already initialized.
242 * @note This must be done before any other API function is called.
243 * This function should be called once only and is not re-entrant.
244 */
245PUBLIC IX_STATUS
246ixTimerCtrlInit(void);
247
248
249/**
250 * @ingroup IxTimerCtrl
251 *
252 * @fn ixTimerCtrlShow( void )
253 *
254 * @brief Display the status of the Timer Control Component.
255 * @return void
256 * @note Displays a list of running timers.
257 * This function is not re-entrant. This function does not suspend the calling thread.
258 */
259PUBLIC void
260ixTimerCtrlShow( void );
261
262#endif /* IXTIMERCTRL_H */
263