4 * This is the header file for the Timer Control component.
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.
16 * IXP400 SW Release version 2.0
18 * -- Copyright Notice --
21 * Copyright 2001-2005, Intel Corporation.
22 * All rights reserved.
25 * SPDX-License-Identifier: BSD-3-Clause
27 * -- End of Copyright Notice --
31 * @defgroup IxTimerCtrl IXP400 Timer Control (IxTimerCtrl) API
33 * @brief The public API for the IXP400 Timer Control Component.
43 /* #include "Ossl.h" */
46 * #defines and macros used in this file.
50 * @ingroup IxTimerCtrl
52 * @def IX_TIMERCTRL_NO_FREE_TIMERS
54 * @brief Timer schedule return code.
56 * Indicates that the request to start a timer failed because
57 * all available timer resources are used.
59 #define IX_TIMERCTRL_NO_FREE_TIMERS 2
63 * @ingroup IxTimerCtrl
65 * @def IX_TIMERCTRL_PARAM_ERROR
67 * @brief Timer schedule return code.
69 * Indicates that the request to start a timer failed because
70 * the client has supplied invalid parameters.
72 #define IX_TIMERCTRL_PARAM_ERROR 3
76 * Typedefs whose scope is limited to this file.
80 * @ingroup IxTimerCtrl
82 * @brief A typedef for a pointer to a timer callback function.
83 * @para void * - This parameter is supplied by the client when the
84 * timer is started and passed back to the client in the callback.
85 * @note in general timer callback functions should not block or
86 * take longer than 100ms. This constraint is required to ensure that
87 * higher priority callbacks are not held up.
88 * All callbacks are called from the same thread.
89 * This thread is a shared resource.
90 * The parameter passed is provided when the timer is scheduled.
92 typedef void (*IxTimerCtrlTimerCallback)(void *userParam);
96 * @ingroup IxTimerCtrl
98 * @brief List used to identify the users of timers.
99 * @note The order in this list indicates priority. Components appearing
100 * higher in the list will be given priority over components lower in the
101 * list. When adding components, please insert at an appropriate position
102 * for priority ( i.e values should be less than IxTimerCtrlMaxPurpose ) .
106 IxTimerCtrlAdslPurpose,
107 /* Insert new purposes above this line only
109 IxTimerCtrlMaxPurpose
115 * Function definition
119 * @ingroup IxTimerCtrl
121 * @fn ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
123 IxTimerCtrlPurpose purpose,
127 * @brief Schedules a callback function to be called after a period of "time".
128 * The callback function should not block or run for more than 100ms.
131 * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
132 * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
133 * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
134 * decide the priority of callbacks with different purpose.
135 * @param relativeTime UINT32 [in] - time relative to now in milliseconds after which the callback
136 * will be called. The time must be greater than the duration of one OS tick.
137 * @param *timerId unsigned [out] - An id for the callback scheduled.
138 * This id can be used to cancel the callback.
140 * @li IX_SUCCESS - The timer was started successfully.
141 * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
142 * of running timers has been exceeded.
143 * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
144 * a NULL callback func, or the requested timeout is less than one OS tick.
145 * @note This function is re-entrant. The function accesses a list of running timers
146 * and may suspend the calling thread if this list is being accesed by another thread.
149 ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
151 IxTimerCtrlPurpose purpose,
157 * @ingroup IxTimerCtrl
159 * @fn ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
161 IxTimerCtrlPurpose purpose,
165 * @brief Schedules a callback function to be called after a period of "time".
166 * The callback function should not block or run for more than 100ms.
168 * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
169 * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
170 * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
171 * decide the priority of callbacks with different purpose.
172 * @param interval UINT32 [in] - the interval in milliseconds between calls to func.
173 * @param timerId unsigned [out] - An id for the callback scheduled.
174 * This id can be used to cancel the callback.
176 * @li IX_SUCCESS - The timer was started successfully.
177 * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
178 * of running timers has been exceeded.
179 * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
180 * a NULL callback func, or the requested timeout is less than one OS tick.
181 * @note This function is re-entrant. The function accesses a list of running timers
182 * and may suspend the calling thread if this list is being accesed by another thread.
185 ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
187 IxTimerCtrlPurpose purpose,
192 * @ingroup IxTimerCtrl
194 * @fn ixTimerCtrlCancel (unsigned id)
196 * @brief Cancels a scheduled callback.
198 * @param id unsigned [in] - the id of the callback to be cancelled.
200 * @li IX_SUCCESS - The timer was successfully stopped.
201 * @li IX_FAIL - The id parameter did not corrrespond to any running timer..
202 * @note This function is re-entrant. The function accesses a list of running timers
203 * and may suspend the calling thread if this list is being accesed by another thread.
206 ixTimerCtrlCancel (unsigned id);
209 * @ingroup IxTimerCtrl
211 * @fn ixTimerCtrlInit(void)
213 * @brief Initialise the Timer Control Component.
215 * @li IX_SUCCESS - The timer control component initialized successfully.
216 * @li IX_FAIL - The timer control component initialization failed,
217 * or the component was already initialized.
218 * @note This must be done before any other API function is called.
219 * This function should be called once only and is not re-entrant.
222 ixTimerCtrlInit(void);
226 * @ingroup IxTimerCtrl
228 * @fn ixTimerCtrlShow( void )
230 * @brief Display the status of the Timer Control Component.
232 * @note Displays a list of running timers.
233 * This function is not re-entrant. This function does not suspend the calling thread.
236 ixTimerCtrlShow( void );
238 #endif /* IXTIMERCTRL_H */