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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
38 * Declaration of timer abstraction.
44 #include <complib/cl_types.h>
47 # define BEGIN_C_DECLS extern "C" {
48 # define END_C_DECLS }
49 #else /* !__cplusplus */
50 # define BEGIN_C_DECLS
52 #endif /* __cplusplus */
55 /****h* Component Library/Timer
60 * The Timer provides the ability to schedule a function to be invoked at
61 * a given time in the future.
63 * The timer callback function must not perform any blocking operations.
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
74 * cl_pfn_timer_callback_t
77 * cl_timer_construct, cl_timer_init, cl_timer_destroy
80 * cl_timer_start, cl_timer_stop
82 /****d* Component Library: Timer/cl_pfn_timer_callback_t
84 * cl_pfn_timer_callback_t
87 * The cl_pfn_timer_callback_t function type defines the prototype for
88 * functions used to notify users of a timer expiration.
92 typedef void (*cl_pfn_timer_callback_t) (IN void *context);
96 * [in] Value specified in a previous call to cl_timer_init.
99 * This function does not return a value.
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.
106 * Timer, cl_timer_init
110 * This include file defines the timer structure, and depends on the timer
111 * callback definition.
113 #include <complib/cl_timer_osd.h>
115 /****f* Component Library: Timer/cl_timer_construct
120 * The cl_timer_construct function initializes the state of a timer.
124 void cl_timer_construct(IN cl_timer_t * const p_timer);
128 * [in] Pointer to a cl_timer_t structure whose state to initialize.
131 * This function does not return a value.
134 * Allows calling cl_timer_destroy without first calling cl_timer_init.
136 * Calling cl_timer_construct is a prerequisite to calling any other
137 * timer function except cl_timer_init.
140 * Timer, cl_timer_init, cl_timer_destroy
143 /****f* Component Library: Timer/cl_timer_init
148 * The cl_timer_init function initializes a timer for use.
153 cl_timer_init(IN cl_timer_t * const p_timer,
154 IN cl_pfn_timer_callback_t pfn_callback,
155 IN const void *const context);
159 * [in] Pointer to a cl_timer_t structure to initialize.
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.
167 * [in] Value to pass to the callback function.
170 * CL_SUCCESS if the timer was successfully initialized.
172 * CL_ERROR otherwise.
175 * Allows calling cl_timer_start and cl_timer_stop.
178 * Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start,
179 * cl_timer_stop, cl_pfn_timer_callback_t
182 /****f* Component Library: Timer/cl_timer_destroy
187 * The cl_timer_destroy function performs any necessary cleanup of a timer.
191 void cl_timer_destroy(IN cl_timer_t * const p_timer);
195 * [in] Pointer to a cl_timer_t structure to destroy.
198 * This function does not return a value.
201 * cl_timer_destroy cancels any pending callbacks.
203 * This function should only be called after a call to cl_timer_construct
207 * Timer, cl_timer_construct, cl_timer_init
210 /****f* Component Library: Timer/cl_timer_start
215 * The cl_timer_start function sets a timer to expire after a given interval.
220 cl_timer_start(IN cl_timer_t * const p_timer, IN const uint32_t time_ms);
224 * [in] Pointer to a cl_timer_t structure to schedule.
227 * [in] Time, in milliseconds, before the timer should expire.
230 * CL_SUCCESS if the timer was successfully scheduled.
232 * CL_ERROR otherwise.
235 * cl_timer_start implicitly stops the timer before being scheduled.
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.
242 * Timer, cl_timer_stop, cl_timer_trim
245 /****f* Component Library: Timer/cl_timer_stop
250 * The cl_timer_stop function stops a pending timer from expiring.
254 void cl_timer_stop(IN cl_timer_t * const p_timer);
258 * [in] Pointer to a cl_timer_t structure.
261 * This function does not return a value.
264 * Timer, cl_timer_start, cl_timer_trim
267 /****f* Component Library: Timer/cl_timer_trim
272 * The cl_timer_trim function pulls in the absolute expiration
273 * time of a timer if the current expiration time exceeds the specified
276 * sets a timer to expire after a given
277 * interval if that interval is less than the current timer expiration.
282 cl_timer_trim(IN cl_timer_t * const p_timer, IN const uint32_t time_ms);
286 * [in] Pointer to a cl_timer_t structure to schedule.
289 * [in] Maximum time, in milliseconds, before the timer should expire.
292 * CL_SUCCESS if the timer was successfully scheduled.
294 * CL_ERROR otherwise.
297 * cl_timer_trim has no effect if the time interval is greater than the
298 * remaining time when the timer is set.
300 * If the new interval time is less than the remaining time, cl_timer_trim
301 * implicitly stops the timer before resetting it.
303 * If the timer is reset, it is guaranteed to expire no sooner than the
304 * new interval, but may take longer to expire.
307 * Timer, cl_timer_start, cl_timer_stop
310 /****f* Component Library: Time Stamp/cl_get_time_stamp
315 * The cl_get_time_stamp function returns the current time stamp in
316 * microseconds since the system was booted.
320 uint64_t cl_get_time_stamp(void);
323 * Time elapsed, in microseconds, since the system was booted.
326 * Timer, cl_get_time_stamp_sec
329 /****f* Component Library: Time Stamp/cl_get_time_stamp_sec
331 * cl_get_time_stamp_sec
334 * The cl_get_time_stamp_sec function returns the current time stamp in
335 * seconds since the system was booted.
339 uint32_t cl_get_time_stamp_sec(void);
342 * Time elapsed, in seconds, since the system was booted.
345 * Timer, cl_get_time_stamp
349 #endif /* _CL_TIMER_H_ */