← Back to branch summary

~ubuntu-branches/ubuntu/maverick/u-boot-omap3/maverick

« back to all changes in this revision

Viewing changes to cpu/ixp/npe/include/IxTimerCtrl.h

  • Committer: Bazaar Package Importer
  • Author(s): Oliver Grawert
  • Date: 2010-03-22 15:06:23 UTC
  • Revision ID: james.westby@ubuntu.com-20100322150623-i21g8rgiyl5dohag
Tags: upstream-2010.3git20100315
Import upstream version 2010.3git20100315

Show diffs side-by-side

added added

removed removed

Lines of Context:
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