cl_timer.h revision 219820
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