1321936Shselasky/* 2321936Shselasky * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3321936Shselasky * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4321936Shselasky * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5321936Shselasky * 6321936Shselasky * This software is available to you under a choice of one of two 7321936Shselasky * licenses. You may choose to be licensed under the terms of the GNU 8321936Shselasky * General Public License (GPL) Version 2, available from the file 9321936Shselasky * COPYING in the main directory of this source tree, or the 10321936Shselasky * OpenIB.org BSD license below: 11321936Shselasky * 12321936Shselasky * Redistribution and use in source and binary forms, with or 13321936Shselasky * without modification, are permitted provided that the following 14321936Shselasky * conditions are met: 15321936Shselasky * 16321936Shselasky * - Redistributions of source code must retain the above 17321936Shselasky * copyright notice, this list of conditions and the following 18321936Shselasky * disclaimer. 19321936Shselasky * 20321936Shselasky * - Redistributions in binary form must reproduce the above 21321936Shselasky * copyright notice, this list of conditions and the following 22321936Shselasky * disclaimer in the documentation and/or other materials 23321936Shselasky * provided with the distribution. 24321936Shselasky * 25321936Shselasky * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26321936Shselasky * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27321936Shselasky * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28321936Shselasky * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29321936Shselasky * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30321936Shselasky * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31321936Shselasky * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32321936Shselasky * SOFTWARE. 33321936Shselasky * 34321936Shselasky */ 35321936Shselasky 36321936Shselasky/* 37321936Shselasky * Abstract: 38321936Shselasky * Declaration of timer abstraction. 39321936Shselasky */ 40321936Shselasky 41321936Shselasky#ifndef _CL_TIMER_H_ 42321936Shselasky#define _CL_TIMER_H_ 43321936Shselasky 44321936Shselasky#include <complib/cl_types.h> 45321936Shselasky 46321936Shselasky#ifdef __cplusplus 47321936Shselasky# define BEGIN_C_DECLS extern "C" { 48321936Shselasky# define END_C_DECLS } 49321936Shselasky#else /* !__cplusplus */ 50321936Shselasky# define BEGIN_C_DECLS 51321936Shselasky# define END_C_DECLS 52321936Shselasky#endif /* __cplusplus */ 53321936Shselasky 54321936ShselaskyBEGIN_C_DECLS 55321936Shselasky/****h* Component Library/Timer 56321936Shselasky* NAME 57321936Shselasky* Timer 58321936Shselasky* 59321936Shselasky* DESCRIPTION 60321936Shselasky* The Timer provides the ability to schedule a function to be invoked at 61321936Shselasky* a given time in the future. 62321936Shselasky* 63321936Shselasky* The timer callback function must not perform any blocking operations. 64321936Shselasky* 65321936Shselasky* The timer functions operate on a cl_timer_t structure which should be 66321936Shselasky* treated as opaque and should be manipulated only through the provided 67321936Shselasky* functions. 68321936Shselasky* 69321936Shselasky* SEE ALSO 70321936Shselasky* Structures: 71321936Shselasky* cl_timer_t 72321936Shselasky* 73321936Shselasky* Callbacks: 74321936Shselasky* cl_pfn_timer_callback_t 75321936Shselasky* 76321936Shselasky* Initialization: 77321936Shselasky* cl_timer_construct, cl_timer_init, cl_timer_destroy 78321936Shselasky* 79321936Shselasky* Manipulation: 80321936Shselasky* cl_timer_start, cl_timer_stop 81321936Shselasky*********/ 82321936Shselasky/****d* Component Library: Timer/cl_pfn_timer_callback_t 83321936Shselasky* NAME 84321936Shselasky* cl_pfn_timer_callback_t 85321936Shselasky* 86321936Shselasky* DESCRIPTION 87321936Shselasky* The cl_pfn_timer_callback_t function type defines the prototype for 88321936Shselasky* functions used to notify users of a timer expiration. 89321936Shselasky* 90321936Shselasky* SYNOPSIS 91321936Shselasky*/ 92321936Shselaskytypedef void (*cl_pfn_timer_callback_t) (IN void *context); 93321936Shselasky/* 94321936Shselasky* PARAMETERS 95321936Shselasky* context 96321936Shselasky* [in] Value specified in a previous call to cl_timer_init. 97321936Shselasky* 98321936Shselasky* RETURN VALUE 99321936Shselasky* This function does not return a value. 100321936Shselasky* 101321936Shselasky* NOTES 102321936Shselasky* This function type is provided as function prototype reference for the 103321936Shselasky* function provided by users as a parameter to the cl_timer_init function. 104321936Shselasky* 105321936Shselasky* SEE ALSO 106321936Shselasky* Timer, cl_timer_init 107321936Shselasky*********/ 108321936Shselasky 109321936Shselasky/* 110321936Shselasky * This include file defines the timer structure, and depends on the timer 111321936Shselasky * callback definition. 112321936Shselasky */ 113321936Shselasky#include <complib/cl_timer_osd.h> 114321936Shselasky 115321936Shselasky/****f* Component Library: Timer/cl_timer_construct 116321936Shselasky* NAME 117321936Shselasky* cl_timer_construct 118321936Shselasky* 119321936Shselasky* DESCRIPTION 120321936Shselasky* The cl_timer_construct function initializes the state of a timer. 121321936Shselasky* 122321936Shselasky* SYNOPSIS 123321936Shselasky*/ 124321936Shselaskyvoid cl_timer_construct(IN cl_timer_t * const p_timer); 125321936Shselasky/* 126321936Shselasky* PARAMETERS 127321936Shselasky* p_timer 128321936Shselasky* [in] Pointer to a cl_timer_t structure whose state to initialize. 129321936Shselasky* 130321936Shselasky* RETURN VALUE 131321936Shselasky* This function does not return a value. 132321936Shselasky* 133321936Shselasky* NOTES 134321936Shselasky* Allows calling cl_timer_destroy without first calling cl_timer_init. 135321936Shselasky* 136321936Shselasky* Calling cl_timer_construct is a prerequisite to calling any other 137321936Shselasky* timer function except cl_timer_init. 138321936Shselasky* 139321936Shselasky* SEE ALSO 140321936Shselasky* Timer, cl_timer_init, cl_timer_destroy 141321936Shselasky*********/ 142321936Shselasky 143321936Shselasky/****f* Component Library: Timer/cl_timer_init 144321936Shselasky* NAME 145321936Shselasky* cl_timer_init 146321936Shselasky* 147321936Shselasky* DESCRIPTION 148321936Shselasky* The cl_timer_init function initializes a timer for use. 149321936Shselasky* 150321936Shselasky* SYNOPSIS 151321936Shselasky*/ 152321936Shselaskycl_status_t 153321936Shselaskycl_timer_init(IN cl_timer_t * const p_timer, 154321936Shselasky IN cl_pfn_timer_callback_t pfn_callback, 155321936Shselasky IN const void *const context); 156321936Shselasky/* 157321936Shselasky* PARAMETERS 158321936Shselasky* p_timer 159321936Shselasky* [in] Pointer to a cl_timer_t structure to initialize. 160321936Shselasky* 161321936Shselasky* pfn_callback 162321936Shselasky* [in] Address of a callback function to be invoked when a timer expires. 163321936Shselasky* See the cl_pfn_timer_callback_t function type definition for details 164321936Shselasky* about the callback function. 165321936Shselasky* 166321936Shselasky* context 167321936Shselasky* [in] Value to pass to the callback function. 168321936Shselasky* 169321936Shselasky* RETURN VALUES 170321936Shselasky* CL_SUCCESS if the timer was successfully initialized. 171321936Shselasky* 172321936Shselasky* CL_ERROR otherwise. 173321936Shselasky* 174321936Shselasky* NOTES 175321936Shselasky* Allows calling cl_timer_start and cl_timer_stop. 176321936Shselasky* 177321936Shselasky* SEE ALSO 178321936Shselasky* Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start, 179321936Shselasky* cl_timer_stop, cl_pfn_timer_callback_t 180321936Shselasky*********/ 181321936Shselasky 182321936Shselasky/****f* Component Library: Timer/cl_timer_destroy 183321936Shselasky* NAME 184321936Shselasky* cl_timer_destroy 185321936Shselasky* 186321936Shselasky* DESCRIPTION 187321936Shselasky* The cl_timer_destroy function performs any necessary cleanup of a timer. 188321936Shselasky* 189321936Shselasky* SYNOPSIS 190321936Shselasky*/ 191321936Shselaskyvoid cl_timer_destroy(IN cl_timer_t * const p_timer); 192321936Shselasky/* 193321936Shselasky* PARAMETERS 194321936Shselasky* p_timer 195321936Shselasky* [in] Pointer to a cl_timer_t structure to destroy. 196321936Shselasky* 197321936Shselasky* RETURN VALUE 198321936Shselasky* This function does not return a value. 199321936Shselasky* 200321936Shselasky* NOTES 201321936Shselasky* cl_timer_destroy cancels any pending callbacks. 202321936Shselasky* 203321936Shselasky* This function should only be called after a call to cl_timer_construct 204321936Shselasky* or cl_timer_init. 205321936Shselasky* 206321936Shselasky* SEE ALSO 207321936Shselasky* Timer, cl_timer_construct, cl_timer_init 208321936Shselasky*********/ 209321936Shselasky 210321936Shselasky/****f* Component Library: Timer/cl_timer_start 211321936Shselasky* NAME 212321936Shselasky* cl_timer_start 213321936Shselasky* 214321936Shselasky* DESCRIPTION 215321936Shselasky* The cl_timer_start function sets a timer to expire after a given interval. 216321936Shselasky* 217321936Shselasky* SYNOPSIS 218321936Shselasky*/ 219321936Shselaskycl_status_t 220321936Shselaskycl_timer_start(IN cl_timer_t * const p_timer, IN const uint32_t time_ms); 221321936Shselasky/* 222321936Shselasky* PARAMETERS 223321936Shselasky* p_timer 224321936Shselasky* [in] Pointer to a cl_timer_t structure to schedule. 225321936Shselasky* 226321936Shselasky* time_ms 227321936Shselasky* [in] Time, in milliseconds, before the timer should expire. 228321936Shselasky* 229321936Shselasky* RETURN VALUES 230321936Shselasky* CL_SUCCESS if the timer was successfully scheduled. 231321936Shselasky* 232321936Shselasky* CL_ERROR otherwise. 233321936Shselasky* 234321936Shselasky* NOTES 235321936Shselasky* cl_timer_start implicitly stops the timer before being scheduled. 236321936Shselasky* 237321936Shselasky* The interval specified by the time_ms parameter is a minimum interval. 238321936Shselasky* The timer is guaranteed to expire no sooner than the desired interval, but 239321936Shselasky* may take longer to expire. 240321936Shselasky* 241321936Shselasky* SEE ALSO 242321936Shselasky* Timer, cl_timer_stop, cl_timer_trim 243321936Shselasky*********/ 244321936Shselasky 245321936Shselasky/****f* Component Library: Timer/cl_timer_stop 246321936Shselasky* NAME 247321936Shselasky* cl_timer_stop 248321936Shselasky* 249321936Shselasky* DESCRIPTION 250321936Shselasky* The cl_timer_stop function stops a pending timer from expiring. 251321936Shselasky* 252321936Shselasky* SYNOPSIS 253321936Shselasky*/ 254321936Shselaskyvoid cl_timer_stop(IN cl_timer_t * const p_timer); 255321936Shselasky/* 256321936Shselasky* PARAMETERS 257321936Shselasky* p_timer 258321936Shselasky* [in] Pointer to a cl_timer_t structure. 259321936Shselasky* 260321936Shselasky* RETURN VALUE 261321936Shselasky* This function does not return a value. 262321936Shselasky* 263321936Shselasky* SEE ALSO 264321936Shselasky* Timer, cl_timer_start, cl_timer_trim 265321936Shselasky*********/ 266321936Shselasky 267321936Shselasky/****f* Component Library: Timer/cl_timer_trim 268321936Shselasky* NAME 269321936Shselasky* cl_timer_trim 270321936Shselasky* 271321936Shselasky* DESCRIPTION 272321936Shselasky* The cl_timer_trim function pulls in the absolute expiration 273321936Shselasky* time of a timer if the current expiration time exceeds the specified 274321936Shselasky* interval. 275321936Shselasky* 276321936Shselasky* sets a timer to expire after a given 277321936Shselasky* interval if that interval is less than the current timer expiration. 278321936Shselasky* 279321936Shselasky* SYNOPSIS 280321936Shselasky*/ 281321936Shselaskycl_status_t 282321936Shselaskycl_timer_trim(IN cl_timer_t * const p_timer, IN const uint32_t time_ms); 283321936Shselasky/* 284321936Shselasky* PARAMETERS 285321936Shselasky* p_timer 286321936Shselasky* [in] Pointer to a cl_timer_t structure to schedule. 287321936Shselasky* 288321936Shselasky* time_ms 289321936Shselasky* [in] Maximum time, in milliseconds, before the timer should expire. 290321936Shselasky* 291321936Shselasky* RETURN VALUES 292321936Shselasky* CL_SUCCESS if the timer was successfully scheduled. 293321936Shselasky* 294321936Shselasky* CL_ERROR otherwise. 295321936Shselasky* 296321936Shselasky* NOTES 297321936Shselasky* cl_timer_trim has no effect if the time interval is greater than the 298321936Shselasky* remaining time when the timer is set. 299321936Shselasky* 300321936Shselasky* If the new interval time is less than the remaining time, cl_timer_trim 301321936Shselasky* implicitly stops the timer before resetting it. 302321936Shselasky* 303321936Shselasky* If the timer is reset, it is guaranteed to expire no sooner than the 304321936Shselasky* new interval, but may take longer to expire. 305321936Shselasky* 306321936Shselasky* SEE ALSO 307321936Shselasky* Timer, cl_timer_start, cl_timer_stop 308321936Shselasky*********/ 309321936Shselasky 310321936Shselasky/****f* Component Library: Time Stamp/cl_get_time_stamp 311321936Shselasky* NAME 312321936Shselasky* cl_get_time_stamp 313321936Shselasky* 314321936Shselasky* DESCRIPTION 315321936Shselasky* The cl_get_time_stamp function returns the current time stamp in 316321936Shselasky* microseconds since the system was booted. 317321936Shselasky* 318321936Shselasky* SYNOPSIS 319321936Shselasky*/ 320321936Shselaskyuint64_t cl_get_time_stamp(void); 321321936Shselasky/* 322321936Shselasky* RETURN VALUE 323321936Shselasky* Time elapsed, in microseconds, since the system was booted. 324321936Shselasky* 325321936Shselasky* SEE ALSO 326321936Shselasky* Timer, cl_get_time_stamp_sec 327321936Shselasky*********/ 328321936Shselasky 329321936Shselasky/****f* Component Library: Time Stamp/cl_get_time_stamp_sec 330321936Shselasky* NAME 331321936Shselasky* cl_get_time_stamp_sec 332321936Shselasky* 333321936Shselasky* DESCRIPTION 334321936Shselasky* The cl_get_time_stamp_sec function returns the current time stamp in 335321936Shselasky* seconds since the system was booted. 336321936Shselasky* 337321936Shselasky* SYNOPSIS 338321936Shselasky*/ 339321936Shselaskyuint32_t cl_get_time_stamp_sec(void); 340321936Shselasky/* 341321936Shselasky* RETURN VALUE 342321936Shselasky* Time elapsed, in seconds, since the system was booted. 343321936Shselasky* 344321936Shselasky* SEE ALSO 345321936Shselasky* Timer, cl_get_time_stamp 346321936Shselasky*********/ 347321936Shselasky 348321936ShselaskyEND_C_DECLS 349321936Shselasky#endif /* _CL_TIMER_H_ */ 350