Merge branch 'mpc86xx'
[platform/kernel/u-boot.git] / cpu / ixp / npe / include / IxTimerCtrl.h
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