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 54 BEGIN_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 */ 92 typedef 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 */ 124 void 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 */ 152 cl_status_t 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); 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 */ 191 void 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 */ 219 cl_status_t 220 cl_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 */ 254 void 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 */ 281 cl_status_t 282 cl_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 */ 320 uint64_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 */ 339 uint32_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 348 END_C_DECLS 349 #endif /* _CL_TIMER_H_ */ 350