cl_timer.h revision 219820
1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of timer abstraction. 39219820Sjeff */ 40219820Sjeff 41219820Sjeff#ifndef _CL_TIMER_H_ 42219820Sjeff#define _CL_TIMER_H_ 43219820Sjeff 44219820Sjeff#include <complib/cl_types.h> 45219820Sjeff 46219820Sjeff#ifdef __cplusplus 47219820Sjeff# define BEGIN_C_DECLS extern "C" { 48219820Sjeff# define END_C_DECLS } 49219820Sjeff#else /* !__cplusplus */ 50219820Sjeff# define BEGIN_C_DECLS 51219820Sjeff# define END_C_DECLS 52219820Sjeff#endif /* __cplusplus */ 53219820Sjeff 54219820SjeffBEGIN_C_DECLS 55219820Sjeff/****h* Component Library/Timer 56219820Sjeff* NAME 57219820Sjeff* Timer 58219820Sjeff* 59219820Sjeff* DESCRIPTION 60219820Sjeff* The Timer provides the ability to schedule a function to be invoked at 61219820Sjeff* a given time in the future. 62219820Sjeff* 63219820Sjeff* The timer callback function must not perform any blocking operations. 64219820Sjeff* 65219820Sjeff* The timer functions operate on a cl_timer_t structure which should be 66219820Sjeff* treated as opaque and should be manipulated only through the provided 67219820Sjeff* functions. 68219820Sjeff* 69219820Sjeff* SEE ALSO 70219820Sjeff* Structures: 71219820Sjeff* cl_timer_t 72219820Sjeff* 73219820Sjeff* Callbacks: 74219820Sjeff* cl_pfn_timer_callback_t 75219820Sjeff* 76219820Sjeff* Initialization: 77219820Sjeff* cl_timer_construct, cl_timer_init, cl_timer_destroy 78219820Sjeff* 79219820Sjeff* Manipulation: 80219820Sjeff* cl_timer_start, cl_timer_stop 81219820Sjeff*********/ 82219820Sjeff/****d* Component Library: Timer/cl_pfn_timer_callback_t 83219820Sjeff* NAME 84219820Sjeff* cl_pfn_timer_callback_t 85219820Sjeff* 86219820Sjeff* DESCRIPTION 87219820Sjeff* The cl_pfn_timer_callback_t function type defines the prototype for 88219820Sjeff* functions used to notify users of a timer expiration. 89219820Sjeff* 90219820Sjeff* SYNOPSIS 91219820Sjeff*/ 92219820Sjefftypedef void (*cl_pfn_timer_callback_t) (IN void *context); 93219820Sjeff/* 94219820Sjeff* PARAMETERS 95219820Sjeff* context 96219820Sjeff* [in] Value specified in a previous call to cl_timer_init. 97219820Sjeff* 98219820Sjeff* RETURN VALUE 99219820Sjeff* This function does not return a value. 100219820Sjeff* 101219820Sjeff* NOTES 102219820Sjeff* This function type is provided as function prototype reference for the 103219820Sjeff* function provided by users as a parameter to the cl_timer_init function. 104219820Sjeff* 105219820Sjeff* SEE ALSO 106219820Sjeff* Timer, cl_timer_init 107219820Sjeff*********/ 108219820Sjeff 109219820Sjeff/* 110219820Sjeff * This include file defines the timer structure, and depends on the timer 111219820Sjeff * callback definition. 112219820Sjeff */ 113219820Sjeff#include <complib/cl_timer_osd.h> 114219820Sjeff 115219820Sjeff/****f* Component Library: Timer/cl_timer_construct 116219820Sjeff* NAME 117219820Sjeff* cl_timer_construct 118219820Sjeff* 119219820Sjeff* DESCRIPTION 120219820Sjeff* The cl_timer_construct function initializes the state of a timer. 121219820Sjeff* 122219820Sjeff* SYNOPSIS 123219820Sjeff*/ 124219820Sjeffvoid cl_timer_construct(IN cl_timer_t * const p_timer); 125219820Sjeff/* 126219820Sjeff* PARAMETERS 127219820Sjeff* p_timer 128219820Sjeff* [in] Pointer to a cl_timer_t structure whose state to initialize. 129219820Sjeff* 130219820Sjeff* RETURN VALUE 131219820Sjeff* This function does not return a value. 132219820Sjeff* 133219820Sjeff* NOTES 134219820Sjeff* Allows calling cl_timer_destroy without first calling cl_timer_init. 135219820Sjeff* 136219820Sjeff* Calling cl_timer_construct is a prerequisite to calling any other 137219820Sjeff* timer function except cl_timer_init. 138219820Sjeff* 139219820Sjeff* SEE ALSO 140219820Sjeff* Timer, cl_timer_init, cl_timer_destroy 141219820Sjeff*********/ 142219820Sjeff 143219820Sjeff/****f* Component Library: Timer/cl_timer_init 144219820Sjeff* NAME 145219820Sjeff* cl_timer_init 146219820Sjeff* 147219820Sjeff* DESCRIPTION 148219820Sjeff* The cl_timer_init function initializes a timer for use. 149219820Sjeff* 150219820Sjeff* SYNOPSIS 151219820Sjeff*/ 152219820Sjeffcl_status_t 153219820Sjeffcl_timer_init(IN cl_timer_t * const p_timer, 154219820Sjeff IN cl_pfn_timer_callback_t pfn_callback, 155219820Sjeff IN const void *const context); 156219820Sjeff/* 157219820Sjeff* PARAMETERS 158219820Sjeff* p_timer 159219820Sjeff* [in] Pointer to a cl_timer_t structure to initialize. 160219820Sjeff* 161219820Sjeff* pfn_callback 162219820Sjeff* [in] Address of a callback function to be invoked when a timer expires. 163219820Sjeff* See the cl_pfn_timer_callback_t function type definition for details 164219820Sjeff* about the callback function. 165219820Sjeff* 166219820Sjeff* context 167219820Sjeff* [in] Value to pass to the callback function. 168219820Sjeff* 169219820Sjeff* RETURN VALUES 170219820Sjeff* CL_SUCCESS if the timer was successfully initialized. 171219820Sjeff* 172219820Sjeff* CL_ERROR otherwise. 173219820Sjeff* 174219820Sjeff* NOTES 175219820Sjeff* Allows calling cl_timer_start and cl_timer_stop. 176219820Sjeff* 177219820Sjeff* SEE ALSO 178219820Sjeff* Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start, 179219820Sjeff* cl_timer_stop, cl_pfn_timer_callback_t 180219820Sjeff*********/ 181219820Sjeff 182219820Sjeff/****f* Component Library: Timer/cl_timer_destroy 183219820Sjeff* NAME 184219820Sjeff* cl_timer_destroy 185219820Sjeff* 186219820Sjeff* DESCRIPTION 187219820Sjeff* The cl_timer_destroy function performs any necessary cleanup of a timer. 188219820Sjeff* 189219820Sjeff* SYNOPSIS 190219820Sjeff*/ 191219820Sjeffvoid cl_timer_destroy(IN cl_timer_t * const p_timer); 192219820Sjeff/* 193219820Sjeff* PARAMETERS 194219820Sjeff* p_timer 195219820Sjeff* [in] Pointer to a cl_timer_t structure to destroy. 196219820Sjeff* 197219820Sjeff* RETURN VALUE 198219820Sjeff* This function does not return a value. 199219820Sjeff* 200219820Sjeff* NOTES 201219820Sjeff* cl_timer_destroy cancels any pending callbacks. 202219820Sjeff* 203219820Sjeff* This function should only be called after a call to cl_timer_construct 204219820Sjeff* or cl_timer_init. 205219820Sjeff* 206219820Sjeff* SEE ALSO 207219820Sjeff* Timer, cl_timer_construct, cl_timer_init 208219820Sjeff*********/ 209219820Sjeff 210219820Sjeff/****f* Component Library: Timer/cl_timer_start 211219820Sjeff* NAME 212219820Sjeff* cl_timer_start 213219820Sjeff* 214219820Sjeff* DESCRIPTION 215219820Sjeff* The cl_timer_start function sets a timer to expire after a given interval. 216219820Sjeff* 217219820Sjeff* SYNOPSIS 218219820Sjeff*/ 219219820Sjeffcl_status_t 220219820Sjeffcl_timer_start(IN cl_timer_t * const p_timer, IN const uint32_t time_ms); 221219820Sjeff/* 222219820Sjeff* PARAMETERS 223219820Sjeff* p_timer 224219820Sjeff* [in] Pointer to a cl_timer_t structure to schedule. 225219820Sjeff* 226219820Sjeff* time_ms 227219820Sjeff* [in] Time, in milliseconds, before the timer should expire. 228219820Sjeff* 229219820Sjeff* RETURN VALUES 230219820Sjeff* CL_SUCCESS if the timer was successfully scheduled. 231219820Sjeff* 232219820Sjeff* CL_ERROR otherwise. 233219820Sjeff* 234219820Sjeff* NOTES 235219820Sjeff* cl_timer_start implicitly stops the timer before being scheduled. 236219820Sjeff* 237219820Sjeff* The interval specified by the time_ms parameter is a minimum interval. 238219820Sjeff* The timer is guaranteed to expire no sooner than the desired interval, but 239219820Sjeff* may take longer to expire. 240219820Sjeff* 241219820Sjeff* SEE ALSO 242219820Sjeff* Timer, cl_timer_stop, cl_timer_trim 243219820Sjeff*********/ 244219820Sjeff 245219820Sjeff/****f* Component Library: Timer/cl_timer_stop 246219820Sjeff* NAME 247219820Sjeff* cl_timer_stop 248219820Sjeff* 249219820Sjeff* DESCRIPTION 250219820Sjeff* The cl_timer_stop function stops a pending timer from expiring. 251219820Sjeff* 252219820Sjeff* SYNOPSIS 253219820Sjeff*/ 254219820Sjeffvoid cl_timer_stop(IN cl_timer_t * const p_timer); 255219820Sjeff/* 256219820Sjeff* PARAMETERS 257219820Sjeff* p_timer 258219820Sjeff* [in] Pointer to a cl_timer_t structure. 259219820Sjeff* 260219820Sjeff* RETURN VALUE 261219820Sjeff* This function does not return a value. 262219820Sjeff* 263219820Sjeff* SEE ALSO 264219820Sjeff* Timer, cl_timer_start, cl_timer_trim 265219820Sjeff*********/ 266219820Sjeff 267219820Sjeff/****f* Component Library: Timer/cl_timer_trim 268219820Sjeff* NAME 269219820Sjeff* cl_timer_trim 270219820Sjeff* 271219820Sjeff* DESCRIPTION 272219820Sjeff* The cl_timer_trim function pulls in the absolute expiration 273219820Sjeff* time of a timer if the current expiration time exceeds the specified 274219820Sjeff* interval. 275219820Sjeff* 276219820Sjeff* sets a timer to expire after a given 277219820Sjeff* interval if that interval is less than the current timer expiration. 278219820Sjeff* 279219820Sjeff* SYNOPSIS 280219820Sjeff*/ 281219820Sjeffcl_status_t 282219820Sjeffcl_timer_trim(IN cl_timer_t * const p_timer, IN const uint32_t time_ms); 283219820Sjeff/* 284219820Sjeff* PARAMETERS 285219820Sjeff* p_timer 286219820Sjeff* [in] Pointer to a cl_timer_t structure to schedule. 287219820Sjeff* 288219820Sjeff* time_ms 289219820Sjeff* [in] Maximum time, in milliseconds, before the timer should expire. 290219820Sjeff* 291219820Sjeff* RETURN VALUES 292219820Sjeff* CL_SUCCESS if the timer was successfully scheduled. 293219820Sjeff* 294219820Sjeff* CL_ERROR otherwise. 295219820Sjeff* 296219820Sjeff* NOTES 297219820Sjeff* cl_timer_trim has no effect if the time interval is greater than the 298219820Sjeff* remaining time when the timer is set. 299219820Sjeff* 300219820Sjeff* If the new interval time is less than the remaining time, cl_timer_trim 301219820Sjeff* implicitly stops the timer before resetting it. 302219820Sjeff* 303219820Sjeff* If the timer is reset, it is guaranteed to expire no sooner than the 304219820Sjeff* new interval, but may take longer to expire. 305219820Sjeff* 306219820Sjeff* SEE ALSO 307219820Sjeff* Timer, cl_timer_start, cl_timer_stop 308219820Sjeff*********/ 309219820Sjeff 310219820Sjeff/****f* Component Library: Time Stamp/cl_get_time_stamp 311219820Sjeff* NAME 312219820Sjeff* cl_get_time_stamp 313219820Sjeff* 314219820Sjeff* DESCRIPTION 315219820Sjeff* The cl_get_time_stamp function returns the current time stamp in 316219820Sjeff* microseconds since the system was booted. 317219820Sjeff* 318219820Sjeff* SYNOPSIS 319219820Sjeff*/ 320219820Sjeffuint64_t cl_get_time_stamp(void); 321219820Sjeff/* 322219820Sjeff* RETURN VALUE 323219820Sjeff* Time elapsed, in microseconds, since the system was booted. 324219820Sjeff* 325219820Sjeff* SEE ALSO 326219820Sjeff* Timer, cl_get_time_stamp_sec 327219820Sjeff*********/ 328219820Sjeff 329219820Sjeff/****f* Component Library: Time Stamp/cl_get_time_stamp_sec 330219820Sjeff* NAME 331219820Sjeff* cl_get_time_stamp_sec 332219820Sjeff* 333219820Sjeff* DESCRIPTION 334219820Sjeff* The cl_get_time_stamp_sec function returns the current time stamp in 335219820Sjeff* seconds since the system was booted. 336219820Sjeff* 337219820Sjeff* SYNOPSIS 338219820Sjeff*/ 339219820Sjeffuint32_t cl_get_time_stamp_sec(void); 340219820Sjeff/* 341219820Sjeff* RETURN VALUE 342219820Sjeff* Time elapsed, in seconds, since the system was booted. 343219820Sjeff* 344219820Sjeff* SEE ALSO 345219820Sjeff* Timer, cl_get_time_stamp 346219820Sjeff*********/ 347219820Sjeff 348219820SjeffEND_C_DECLS 349219820Sjeff#endif /* _CL_TIMER_H_ */ 350