inc/complib/cl_timer.h

   1 /*\r
   2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
   3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
   4  *\r
   5  * This software is available to you under the OpenIB.org BSD license\r
   6  * below:\r
   7  *\r
   8  *     Redistribution and use in source and binary forms, with or\r
   9  *     without modification, are permitted provided that the following\r
  10  *     conditions are met:\r
  11  *\r
  12  *      - Redistributions of source code must retain the above\r
  13  *        copyright notice, this list of conditions and the following\r
  14  *        disclaimer.\r
  15  *\r
  16  *      - Redistributions in binary form must reproduce the above\r
  17  *        copyright notice, this list of conditions and the following\r
  18  *        disclaimer in the documentation and/or other materials\r
  19  *        provided with the distribution.\r
  20  *\r
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
  22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
  23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
  24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
  25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
  26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
  28  * SOFTWARE.\r
  29  *\r
  30  * $Id$\r
  31  */\r
  32 \r
  33 \r
  34 /*\r
  35  * Abstract:\r
  36  *      Declaration of timer abstraction.\r
  37  *\r
  38  * Environment:\r
  39  *      All\r
  40  */\r
  41 \r
  42 \r
  43 #ifndef _CL_TIMER_H_\r
  44 #define _CL_TIMER_H_\r
  45 \r
  46 \r
  47 #include <complib/cl_types.h>\r
  48 \r
  49 \r
  50 /****h* Component Library/Timer\r
  51 * NAME\r
  52 *       Timer\r
  53 *\r
  54 * DESCRIPTION\r
  55 *       The Timer provides the ability to schedule a function to be invoked at\r
  56 *       a given time in the future.\r
  57 *\r
  58 *       The timer callback function must not perform any blocking operations.\r
  59 *\r
  60 *       The timer functions operate on a cl_timer_t structure which should be\r
  61 *       treated as opaque and should be manipulated only through the provided\r
  62 *       functions.\r
  63 *\r
  64 * SEE ALSO\r
  65 *       Structures:\r
  66 *               cl_timer_t\r
  67 *\r
  68 *       Callbacks:\r
  69 *               cl_pfn_timer_callback_t\r
  70 *\r
  71 *       Initialization:\r
  72 *               cl_timer_construct, cl_timer_init, cl_timer_destroy\r
  73 *\r
  74 *       Manipulation:\r
  75 *               cl_timer_start, cl_timer_stop\r
  76 *********/\r
  77 \r
  78 \r
  79 /****d* Component Library: Timer/cl_pfn_timer_callback_t\r
  80 * NAME\r
  81 *       cl_pfn_timer_callback_t\r
  82 *\r
  83 * DESCRIPTION\r
  84 *       The cl_pfn_timer_callback_t function type defines the prototype for\r
  85 *       functions used to notify users of a timer expiration.\r
  86 *\r
  87 * SYNOPSIS\r
  88 */\r
  89 typedef void\r
  90 (CL_API *cl_pfn_timer_callback_t)(\r
  91         IN void*        context );\r
  92 /*\r
  93 * PARAMETERS\r
  94 *       context\r
  95 *               [in] Value specified in a previous call to cl_timer_init.\r
  96 *\r
  97 * RETURN VALUE\r
  98 *       This function does not return a value.\r
  99 *\r
 100 * NOTES\r
 101 *       This function type is provided as function prototype reference for the\r
 102 *       function provided by users as a parameter to the cl_timer_init function.\r
 103 *\r
 104 * SEE ALSO\r
 105 *       Timer, cl_timer_init\r
 106 *********/\r
 107 \r
 108 \r
 109 /*\r
 110  * This include file defines the timer structure, and depends on the timer\r
 111  * callback definition.\r
 112  */\r
 113 #include <complib/cl_timer_osd.h>\r
 114 \r
 115 \r
 116 #ifdef __cplusplus\r
 117 extern "C"\r
 118 {\r
 119 #endif\r
 120 \r
 121 \r
 122 /****f* Component Library: Timer/cl_timer_construct\r
 123 * NAME\r
 124 *       cl_timer_construct\r
 125 *\r
 126 * DESCRIPTION\r
 127 *       The cl_timer_construct function initializes the state of a timer.\r
 128 *\r
 129 * SYNOPSIS\r
 130 */\r
 131 CL_EXPORT void CL_API\r
 132 cl_timer_construct(\r
 133         IN      cl_timer_t* const       p_timer );\r
 134 /*\r
 135 * PARAMETERS\r
 136 *       p_timer\r
 137 *               [in] Pointer to a cl_timer_t structure whose state to initialize.\r
 138 *\r
 139 * RETURN VALUE\r
 140 *       This function does not return a value.\r
 141 *\r
 142 * NOTES\r
 143 *       Allows calling cl_timer_destroy without first calling cl_timer_init.\r
 144 *\r
 145 *       Calling cl_timer_construct is a prerequisite to calling any other\r
 146 *       timer function except cl_timer_init.\r
 147 *\r
 148 * SEE ALSO\r
 149 *       Timer, cl_timer_init, cl_timer_destroy\r
 150 *********/\r
 151 \r
 152 \r
 153 /****f* Component Library: Timer/cl_timer_init\r
 154 * NAME\r
 155 *       cl_timer_init\r
 156 *\r
 157 * DESCRIPTION\r
 158 *       The cl_timer_init function initializes a timer for use.\r
 159 *\r
 160 * SYNOPSIS\r
 161 */\r
 162 CL_EXPORT cl_status_t CL_API\r
 163 cl_timer_init(\r
 164         IN      cl_timer_t* const               p_timer,\r
 165         IN      cl_pfn_timer_callback_t pfn_callback,\r
 166         IN      const void* const               context );\r
 167 /*\r
 168 * PARAMETERS\r
 169 *       p_timer\r
 170 *               [in] Pointer to a cl_timer_t structure to initialize.\r
 171 *\r
 172 *       pfn_callback\r
 173 *               [in] Address of a callback function to be invoked when a timer expires.\r
 174 *               See the cl_pfn_timer_callback_t function type definition for details\r
 175 *               about the callback function.\r
 176 *\r
 177 *       context\r
 178 *               [in] Value to pass to the callback function.\r
 179 *\r
 180 * RETURN VALUES\r
 181 *       CL_SUCCESS if the timer was successfully initialized.\r
 182 *\r
 183 *       CL_ERROR otherwise.\r
 184 *\r
 185 * NOTES\r
 186 *       Allows calling cl_timer_start and cl_timer_stop.\r
 187 *\r
 188 * SEE ALSO\r
 189 *       Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start,\r
 190 *       cl_timer_stop, cl_pfn_timer_callback_t\r
 191 *********/\r
 192 \r
 193 \r
 194 /****f* Component Library: Timer/cl_timer_destroy\r
 195 * NAME\r
 196 *       cl_timer_destroy\r
 197 *\r
 198 * DESCRIPTION\r
 199 *       The cl_timer_destroy function performs any necessary cleanup of a timer.\r
 200 *\r
 201 * SYNOPSIS\r
 202 */\r
 203 CL_EXPORT void CL_API\r
 204 cl_timer_destroy(\r
 205         IN      cl_timer_t* const       p_timer );\r
 206 /*\r
 207 * PARAMETERS\r
 208 *       p_timer\r
 209 *               [in] Pointer to a cl_timer_t structure to destroy.\r
 210 *\r
 211 * RETURN VALUE\r
 212 *       This function does not return a value.\r
 213 *\r
 214 * NOTES\r
 215 *       cl_timer_destroy cancels any pending callbacks.\r
 216 *\r
 217 *       This function should only be called after a call to cl_timer_construct\r
 218 *       or cl_timer_init.\r
 219 *\r
 220 * SEE ALSO\r
 221 *       Timer, cl_timer_construct, cl_timer_init\r
 222 *********/\r
 223 \r
 224 \r
 225 /****f* Component Library: Timer/cl_timer_start\r
 226 * NAME\r
 227 *       cl_timer_start\r
 228 *\r
 229 * DESCRIPTION\r
 230 *       The cl_timer_start function sets a timer to expire after a given interval.\r
 231 *\r
 232 * SYNOPSIS\r
 233 */\r
 234 CL_EXPORT cl_status_t CL_API\r
 235 cl_timer_start(\r
 236         IN      cl_timer_t* const       p_timer,\r
 237         IN      const uint32_t          time_ms );\r
 238 /*\r
 239 * PARAMETERS\r
 240 *       p_timer\r
 241 *               [in] Pointer to a cl_timer_t structure to schedule.\r
 242 *\r
 243 *       time_ms\r
 244 *               [in] Time, in milliseconds, before the timer should expire.\r
 245 *\r
 246 * RETURN VALUES\r
 247 *       CL_SUCCESS if the timer was successfully scheduled.\r
 248 *\r
 249 *       CL_ERROR otherwise.\r
 250 *\r
 251 * NOTES\r
 252 *       cl_timer_start implicitly stops the timer before being scheduled.\r
 253 *\r
 254 *       The interval specified by the time_ms parameter is a minimum interval.\r
 255 *       The timer is guaranteed to expire no sooner than the desired interval, but\r
 256 *       may take longer to expire.\r
 257 *\r
 258 * SEE ALSO\r
 259 *       Timer, cl_timer_stop, cl_timer_trim\r
 260 *********/\r
 261 \r
 262 \r
 263 /****f* Component Library: Timer/cl_timer_stop\r
 264 * NAME\r
 265 *       cl_timer_stop\r
 266 *\r
 267 * DESCRIPTION\r
 268 *       The cl_timer_stop function stops a pending timer from expiring.\r
 269 *\r
 270 * SYNOPSIS\r
 271 */\r
 272 CL_EXPORT void CL_API\r
 273 cl_timer_stop(\r
 274         IN      cl_timer_t* const       p_timer );\r
 275 /*\r
 276 * PARAMETERS\r
 277 *       p_timer\r
 278 *               [in] Pointer to a cl_timer_t structure.\r
 279 *\r
 280 * RETURN VALUE\r
 281 *       This function does not return a value.\r
 282 *\r
 283 * SEE ALSO\r
 284 *       Timer, cl_timer_start, cl_timer_trim\r
 285 *********/\r
 286 \r
 287 \r
 288 /****f* Component Library: Timer/cl_timer_trim\r
 289 * NAME\r
 290 *       cl_timer_trim\r
 291 *\r
 292 * DESCRIPTION\r
 293 *       The cl_timer_trim function pulls in the absolute expiration\r
 294 *       time of a timer if the current expiration time exceeds the specified\r
 295 *       interval.\r
 296 *\r
 297 *       sets a timer to expire after a given\r
 298 *       interval if that interval is less than the current timer expiration.\r
 299 *\r
 300 * SYNOPSIS\r
 301 */\r
 302 CL_EXPORT cl_status_t CL_API\r
 303 cl_timer_trim(\r
 304         IN      cl_timer_t* const       p_timer,\r
 305         IN      const uint32_t          time_ms );\r
 306 /*\r
 307 * PARAMETERS\r
 308 *       p_timer\r
 309 *               [in] Pointer to a cl_timer_t structure to schedule.\r
 310 *\r
 311 *       time_ms\r
 312 *               [in] Maximum time, in milliseconds, before the timer should expire.\r
 313 *\r
 314 * RETURN VALUES\r
 315 *       CL_SUCCESS if the timer was successfully scheduled.\r
 316 *\r
 317 *       CL_ERROR otherwise.\r
 318 *\r
 319 * NOTES\r
 320 *       cl_timer_trim has no effect if the time interval is greater than the\r
 321 *       remaining time when the timer is set.\r
 322 *\r
 323 *       If the new interval time is less than the remaining time, cl_timer_trim\r
 324 *       implicitly stops the timer before reseting it.\r
 325 *\r
 326 *       If the timer is reset, it is guaranteed to expire no sooner than the\r
 327 *       new interval, but may take longer to expire.\r
 328 *\r
 329 * SEE ALSO\r
 330 *       Timer, cl_timer_start, cl_timer_stop\r
 331 *********/\r
 332 \r
 333 \r
 334 /****f* Component Library: Time Stamp/cl_get_time_stamp\r
 335 * NAME\r
 336 *       cl_get_time_stamp\r
 337 *\r
 338 * DESCRIPTION\r
 339 *       The cl_get_time_stamp function returns the current time stamp in\r
 340 *       microseconds since the system was booted.\r
 341 *\r
 342 * SYNOPSIS\r
 343 */\r
 344 CL_EXPORT uint64_t CL_API\r
 345 cl_get_time_stamp( void );\r
 346 /*\r
 347 * RETURN VALUE\r
 348 *       Time elapsed, in microseconds, since the system was booted.\r
 349 *\r
 350 * SEE ALSO\r
 351 *       Timer, cl_get_time_stamp_usec, cl_get_time_stamp_sec\r
 352 *********/\r
 353 \r
 354 \r
 355 /****f* Component Library: Time Stamp/cl_get_time_stamp_usec\r
 356 * NAME\r
 357 *       cl_get_time_stamp_usec\r
 358 *\r
 359 * DESCRIPTION\r
 360 *       The cl_get_time_stamp_usec function returns the current time stamp in\r
 361 *       microseconds since the system was booted.\r
 362 *\r
 363 * SYNOPSIS\r
 364 */\r
 365 CL_INLINE uint64_t CL_API\r
 366 cl_get_time_stamp_usec( void )\r
 367 {\r
 368         return cl_get_time_stamp();\r
 369 }\r
 370 /*\r
 371 * RETURN VALUE\r
 372 *       Time elapsed, in microseconds, since the system was booted.\r
 373 *\r
 374 * SEE ALSO\r
 375 *       Timer, cl_get_time_stamp, cl_get_time_stamp_sec\r
 376 *********/\r
 377 \r
 378 \r
 379 /****f* Component Library: Time Stamp/cl_get_time_stamp_sec\r
 380 * NAME\r
 381 *       cl_get_time_stamp_sec\r
 382 *\r
 383 * DESCRIPTION\r
 384 *       The cl_get_time_stamp_sec function returns the current time stamp in\r
 385 *       seconds since the system was booted.\r
 386 *\r
 387 * SYNOPSIS\r
 388 */\r
 389 CL_EXPORT uint32_t CL_API\r
 390 cl_get_time_stamp_sec( void );\r
 391 /*\r
 392 * RETURN VALUE\r
 393 *       Time elapsed, in seconds, since the system was booted.\r
 394 *\r
 395 * SEE ALSO\r
 396 *       Timer, cl_get_time_stamp\r
 397 *********/\r
 398 \r
 399 \r
 400 /****f* Component Library: Time Stamp/cl_get_tick_count\r
 401 * NAME\r
 402 *       cl_get_tick_count\r
 403 *\r
 404 * DESCRIPTION\r
 405 *       The cl_get_tick_count function returns the raw high-resolution\r
 406 *       performance counter value.\r
 407 *\r
 408 * SYNOPSIS\r
 409 */\r
 410 CL_EXPORT uint64_t CL_API\r
 411 cl_get_tick_count( void );\r
 412 /*\r
 413 * RETURN VALUE\r
 414 *       Value of the high-resolution performance counter.\r
 415 *\r
 416 * SEE ALSO\r
 417 *       Timer, cl_get_time_stamp, cl_get_frequency\r
 418 *********/\r
 419 \r
 420 \r
 421 /****f* Component Library: Time Stamp/cl_get_frequency\r
 422 * NAME\r
 423 *       cl_get_frequency\r
 424 *\r
 425 * DESCRIPTION\r
 426 *       The cl_get_frequency function returns the frequency of the\r
 427 *       high-resolution performance counter.\r
 428 *\r
 429 * SYNOPSIS\r
 430 */\r
 431 CL_EXPORT uint64_t CL_API\r
 432 cl_get_frequency( void );\r
 433 /*\r
 434 * RETURN VALUE\r
 435 *       The frequency of the high-resolution performance counter.\r
 436 *\r
 437 * SEE ALSO\r
 438 *       Timer, cl_get_time_stamp, cl_get_tick_count\r
 439 *********/\r
 440 \r
 441 \r
 442 #ifdef __cplusplus\r
 443 }       /* extern "C" */\r
 444 #endif\r
 445 \r
 446 #endif /* _CL_TIMER_H_ */\r