cl_timer.h revision 329564 
1/*
2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
5 *
6 * This software is available to you under a choice of one of two
7 * licenses.  You may choose to be licensed under the terms of the GNU
8 * General Public License (GPL) Version 2, available from the file
9 * COPYING in the main directory of this source tree, or the
10 * OpenIB.org BSD license below:
11 *
12 *     Redistribution and use in source and binary forms, with or
13 *     without modification, are permitted provided that the following
14 *     conditions are met:
15 *
16 *      - Redistributions of source code must retain the above
17 *        copyright notice, this list of conditions and the following
18 *        disclaimer.
19 *
20 *      - Redistributions in binary form must reproduce the above
21 *        copyright notice, this list of conditions and the following
22 *        disclaimer in the documentation and/or other materials
23 *        provided with the distribution.
24 *
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32 * SOFTWARE.
33 *
34 */
35
36/*
37 * Abstract:
38 *	Declaration of timer abstraction.
39 */
40
41#ifndef _CL_TIMER_H_
42#define _CL_TIMER_H_
43
44#include <complib/cl_types.h>
45
46#ifdef __cplusplus
47#  define BEGIN_C_DECLS extern "C" {
48#  define END_C_DECLS   }
49#else				/* !__cplusplus */
50#  define BEGIN_C_DECLS
51#  define END_C_DECLS
52#endif				/* __cplusplus */
53
54BEGIN_C_DECLS
55/****h* Component Library/Timer
56* NAME
57*	Timer
58*
59* DESCRIPTION
60*	The Timer provides the ability to schedule a function to be invoked at
61*	a given time in the future.
62*
63*	The timer callback function must not perform any blocking operations.
64*
65*	The timer functions operate on a cl_timer_t structure which should be
66*	treated as opaque and should be manipulated only through the provided
67*	functions.
68*
69* SEE ALSO
70*	Structures:
71*		cl_timer_t
72*
73*	Callbacks:
74*		cl_pfn_timer_callback_t
75*
76*	Initialization:
77*		cl_timer_construct, cl_timer_init, cl_timer_destroy
78*
79*	Manipulation:
80*		cl_timer_start, cl_timer_stop
81*********/
82/****d* Component Library: Timer/cl_pfn_timer_callback_t
83* NAME
84*	cl_pfn_timer_callback_t
85*
86* DESCRIPTION
87*	The cl_pfn_timer_callback_t function type defines the prototype for
88*	functions used to notify users of a timer expiration.
89*
90* SYNOPSIS
91*/
92typedef void (*cl_pfn_timer_callback_t) (IN void *context);
93/*
94* PARAMETERS
95*	context
96*		[in] Value specified in a previous call to cl_timer_init.
97*
98* RETURN VALUE
99*	This function does not return a value.
100*
101* NOTES
102*	This function type is provided as function prototype reference for the
103*	function provided by users as a parameter to the cl_timer_init function.
104*
105* SEE ALSO
106*	Timer, cl_timer_init
107*********/
108
109/*
110 * This include file defines the timer structure, and depends on the timer
111 * callback definition.
112 */
113#include <complib/cl_timer_osd.h>
114
115/****f* Component Library: Timer/cl_timer_construct
116* NAME
117*	cl_timer_construct
118*
119* DESCRIPTION
120*	The cl_timer_construct function initializes the state of a timer.
121*
122* SYNOPSIS
123*/
124void cl_timer_construct(IN cl_timer_t * const p_timer);
125/*
126* PARAMETERS
127*	p_timer
128*		[in] Pointer to a cl_timer_t structure whose state to initialize.
129*
130* RETURN VALUE
131*	This function does not return a value.
132*
133* NOTES
134*	Allows calling cl_timer_destroy without first calling cl_timer_init.
135*
136*	Calling cl_timer_construct is a prerequisite to calling any other
137*	timer function except cl_timer_init.
138*
139* SEE ALSO
140*	Timer, cl_timer_init, cl_timer_destroy
141*********/
142
143/****f* Component Library: Timer/cl_timer_init
144* NAME
145*	cl_timer_init
146*
147* DESCRIPTION
148*	The cl_timer_init function initializes a timer for use.
149*
150* SYNOPSIS
151*/
152cl_status_t
153cl_timer_init(IN cl_timer_t * const p_timer,
154	      IN cl_pfn_timer_callback_t pfn_callback,
155	      IN const void *const context);
156/*
157* PARAMETERS
158*	p_timer
159*		[in] Pointer to a cl_timer_t structure to initialize.
160*
161*	pfn_callback
162*		[in] Address of a callback function to be invoked when a timer expires.
163*		See the cl_pfn_timer_callback_t function type definition for details
164*		about the callback function.
165*
166*	context
167*		[in] Value to pass to the callback function.
168*
169* RETURN VALUES
170*	CL_SUCCESS if the timer was successfully initialized.
171*
172*	CL_ERROR otherwise.
173*
174* NOTES
175*	Allows calling cl_timer_start and cl_timer_stop.
176*
177* SEE ALSO
178*	Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start,
179*	cl_timer_stop, cl_pfn_timer_callback_t
180*********/
181
182/****f* Component Library: Timer/cl_timer_destroy
183* NAME
184*	cl_timer_destroy
185*
186* DESCRIPTION
187*	The cl_timer_destroy function performs any necessary cleanup of a timer.
188*
189* SYNOPSIS
190*/
191void cl_timer_destroy(IN cl_timer_t * const p_timer);
192/*
193* PARAMETERS
194*	p_timer
195*		[in] Pointer to a cl_timer_t structure to destroy.
196*
197* RETURN VALUE
198*	This function does not return a value.
199*
200* NOTES
201*	cl_timer_destroy cancels any pending callbacks.
202*
203*	This function should only be called after a call to cl_timer_construct
204*	or cl_timer_init.
205*
206* SEE ALSO
207*	Timer, cl_timer_construct, cl_timer_init
208*********/
209
210/****f* Component Library: Timer/cl_timer_start
211* NAME
212*	cl_timer_start
213*
214* DESCRIPTION
215*	The cl_timer_start function sets a timer to expire after a given interval.
216*
217* SYNOPSIS
218*/
219cl_status_t
220cl_timer_start(IN cl_timer_t * const p_timer, IN const uint32_t time_ms);
221/*
222* PARAMETERS
223*	p_timer
224*		[in] Pointer to a cl_timer_t structure to schedule.
225*
226*	time_ms
227*		[in] Time, in milliseconds, before the timer should expire.
228*
229* RETURN VALUES
230*	CL_SUCCESS if the timer was successfully scheduled.
231*
232*	CL_ERROR otherwise.
233*
234* NOTES
235*	cl_timer_start implicitly stops the timer before being scheduled.
236*
237*	The interval specified by the time_ms parameter is a minimum interval.
238*	The timer is guaranteed to expire no sooner than the desired interval, but
239*	may take longer to expire.
240*
241* SEE ALSO
242*	Timer, cl_timer_stop, cl_timer_trim
243*********/
244
245/****f* Component Library: Timer/cl_timer_stop
246* NAME
247*	cl_timer_stop
248*
249* DESCRIPTION
250*	The cl_timer_stop function stops a pending timer from expiring.
251*
252* SYNOPSIS
253*/
254void cl_timer_stop(IN cl_timer_t * const p_timer);
255/*
256* PARAMETERS
257*	p_timer
258*		[in] Pointer to a cl_timer_t structure.
259*
260* RETURN VALUE
261*	This function does not return a value.
262*
263* SEE ALSO
264*	Timer, cl_timer_start, cl_timer_trim
265*********/
266
267/****f* Component Library: Timer/cl_timer_trim
268* NAME
269*	cl_timer_trim
270*
271* DESCRIPTION
272*	The cl_timer_trim function pulls in the absolute expiration
273*	time of a timer if the current expiration time exceeds the specified
274*	interval.
275*
276*	sets a timer to expire after a given
277*	interval if that interval is less than the current timer expiration.
278*
279* SYNOPSIS
280*/
281cl_status_t
282cl_timer_trim(IN cl_timer_t * const p_timer, IN const uint32_t time_ms);
283/*
284* PARAMETERS
285*	p_timer
286*		[in] Pointer to a cl_timer_t structure to schedule.
287*
288*	time_ms
289*		[in] Maximum time, in milliseconds, before the timer should expire.
290*
291* RETURN VALUES
292*	CL_SUCCESS if the timer was successfully scheduled.
293*
294*	CL_ERROR otherwise.
295*
296* NOTES
297*	cl_timer_trim has no effect if the time interval is greater than the
298*	remaining time when the timer is set.
299*
300*	If the new interval time is less than the remaining time, cl_timer_trim
301*	implicitly stops the timer before resetting it.
302*
303*	If the timer is reset, it is guaranteed to expire no sooner than the
304*	new interval, but may take longer to expire.
305*
306* SEE ALSO
307*	Timer, cl_timer_start, cl_timer_stop
308*********/
309
310/****f* Component Library: Time Stamp/cl_get_time_stamp
311* NAME
312*	cl_get_time_stamp
313*
314* DESCRIPTION
315*	The cl_get_time_stamp function returns the current time stamp in
316*	microseconds since the system was booted.
317*
318* SYNOPSIS
319*/
320uint64_t cl_get_time_stamp(void);
321/*
322* RETURN VALUE
323*	Time elapsed, in microseconds, since the system was booted.
324*
325* SEE ALSO
326*	Timer, cl_get_time_stamp_sec
327*********/
328
329/****f* Component Library: Time Stamp/cl_get_time_stamp_sec
330* NAME
331*	cl_get_time_stamp_sec
332*
333* DESCRIPTION
334*	The cl_get_time_stamp_sec function returns the current time stamp in
335*	seconds since the system was booted.
336*
337* SYNOPSIS
338*/
339uint32_t cl_get_time_stamp_sec(void);
340/*
341* RETURN VALUE
342*	Time elapsed, in seconds, since the system was booted.
343*
344* SEE ALSO
345*	Timer, cl_get_time_stamp
346*********/
347
348END_C_DECLS
349#endif				/* _CL_TIMER_H_ */
350