]>
Commit | Line | Data |
---|---|---|
ba94a1bb WD |
1 | /** |
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 | */ | |
116 | typedef 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 | */ | |
128 | typedef enum | |
129 | { | |
130 | IxTimerCtrlAdslPurpose, | |
131 | /* Insert new purposes above this line only | |
132 | */ | |
133 | IxTimerCtrlMaxPurpose | |
134 | } | |
135 | IxTimerCtrlPurpose; | |
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 | */ | |
172 | PUBLIC IX_STATUS | |
173 | ixTimerCtrlSchedule(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 | */ | |
208 | PUBLIC IX_STATUS | |
209 | ixTimerCtrlScheduleRepeating(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 | */ | |
229 | PUBLIC IX_STATUS | |
230 | ixTimerCtrlCancel (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 | */ | |
245 | PUBLIC IX_STATUS | |
246 | ixTimerCtrlInit(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 | */ | |
259 | PUBLIC void | |
260 | ixTimerCtrlShow( void ); | |
261 | ||
262 | #endif /* IXTIMERCTRL_H */ | |
263 |