contrib/ofed/management/opensm/include/complib/cl_timer.h

   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_ */