/*++
"This software program is available to you under a choice of one of two
licenses.  You may choose to be licensed under either the GNU General Public
License (GPL) Version 2, June 1991, available at
http://www.fsf.org/copyleft/gpl.html, or the Intel BSD + Patent License,
the text of which follows:

"Recipient" has requested a license and Intel Corporation ("Intel") is willing
to grant a license for the software entitled InfiniBand(tm) System Software
(the "Software") being provided by Intel Corporation.

The following definitions apply to this License:

"Licensed Patents" means patent claims licensable by Intel Corporation which
are necessarily infringed by the use or sale of the Software alone or when
combined with the operating system referred to below.

"Recipient" means the party to whom Intel delivers this Software.
"Licensee" means Recipient and those third parties that receive a license to
any operating system available under the GNU Public License version 2.0 or
later.

Copyright (c) 1996-2003 Intel Corporation. All rights reserved.

The license is provided to Recipient and Recipient's Licensees under the
following terms.

Redistribution and use in source and binary forms of the Software, with or
without modification, are permitted provided that the following conditions are
met:
Redistributions of source code of the Software may retain the above copyright
notice, this list of conditions and the following disclaimer.

Redistributions in binary form of the Software may reproduce the above
copyright notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

Neither the name of Intel Corporation nor the names of its contributors shall
be used to endorse or promote products derived from this Software without
specific prior written permission.

Intel hereby grants Recipient and Licensees a non-exclusive, worldwide,
royalty-free patent license under Licensed Patents to make, use, sell, offer
to sell, import and otherwise transfer the Software, if any, in source code
and object code form. This license shall include changes to the Software that
are error corrections or other minor changes to the Software that do not add
functionality or features when the Software is incorporated in any version of
a operating system that has been distributed under the GNU General Public
License 2.0 or later.  This patent license shall apply to the combination of
the Software and any operating system licensed under the GNU Public License
version 2.0 or later if, at the time Intel provides the Software to Recipient,
such addition of the Software to the then publicly available versions of such
operating system available under the GNU Public License version 2.0 or later
(whether in gold, beta or alpha form) causes such combination to be covered by
the Licensed Patents. The patent license shall not apply to any other
combinations which include the Software. No hardware per se is licensed
hereunder.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL INTEL OR ITS CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
--*/

/*
 * Abstract:
 *	Declaration of timer abstraction.
 *
 * Environment:
 *	All
 *
 * $Revision: 1.1 $
 */

#ifndef _CL_TIMER_H_
#define _CL_TIMER_H_

#include <complib/cl_types.h>

/****h* Component Library/Timer
* NAME
*	Timer
*
* DESCRIPTION
*	The Timer provides the ability to schedule a function to be invoked at
*	a given time in the future.
*
*	The timer callback function must not perform any blocking operations.
*
*	The timer functions operate on a cl_timer_t structure which should be
*	treated as opaque and should be manipulated only through the provided
*	functions.
*
* SEE ALSO
*	Structures:
*		cl_timer_t
*
*	Callbacks:
*		cl_pfn_timer_callback_t
*
*	Initialization:
*		cl_timer_construct, cl_timer_init, cl_timer_destroy
*
*	Manipulation:
*		cl_timer_start, cl_timer_stop
*********/

/****d* Component Library: Timer/cl_pfn_timer_callback_t
* NAME
*	cl_pfn_timer_callback_t
*
* DESCRIPTION
*	The cl_pfn_timer_callback_t function type defines the prototype for
*	functions used to notify users of a timer expiration.
*
* SYNOPSIS
*/
typedef void
 (*cl_pfn_timer_callback_t) (IN void *context);
/*
* PARAMETERS
*	context
*		[in] Value specified in a previous call to cl_timer_init.
*
* RETURN VALUE
*	This function does not return a value.
*
* NOTES
*	This function type is provided as function prototype reference for the
*	function provided by users as a parameter to the cl_timer_init function.
*
* SEE ALSO
*	Timer, cl_timer_init
*********/

/*
 * This include file defines the timer structure, and depends on the timer
 * callback definition.
 */
#include <complib/cl_timer_osd.h>

#ifdef __cplusplus
extern "C" {
#endif

/****f* Component Library: Timer/cl_timer_construct
* NAME
*	cl_timer_construct
*
* DESCRIPTION
*	The cl_timer_construct function initializes the state of a timer.
*
* SYNOPSIS
*/
	void
	 cl_timer_construct(IN cl_timer_t * const p_timer);
/*
* PARAMETERS
*	p_timer
*		[in] Pointer to a cl_timer_t structure whose state to initialize.
*
* RETURN VALUE
*	This function does not return a value.
*
* NOTES
*	Allows calling cl_timer_destroy without first calling cl_timer_init.
*
*	Calling cl_timer_construct is a prerequisite to calling any other
*	timer function except cl_timer_init.
*
* SEE ALSO
*	Timer, cl_timer_init, cl_timer_destroy
*********/

/****f* Component Library: Timer/cl_timer_init
* NAME
*	cl_timer_init
*
* DESCRIPTION
*	The cl_timer_init function initializes a timer for use.
*
* SYNOPSIS
*/
	 cl_status_t
	    cl_timer_init(IN cl_timer_t * const p_timer,
			  IN cl_pfn_timer_callback_t pfn_callback,
			  IN const void *const context);
/*
* PARAMETERS
*	p_timer
*		[in] Pointer to a cl_timer_t structure to initialize.
*
*	pfn_callback
*		[in] Address of a callback function to be invoked when a timer expires.
*		See the cl_pfn_timer_callback_t function type definition for details
*		about the callback function.
*
*	context
*		[in] Value to pass to the callback function.
*
* RETURN VALUES
*	CL_SUCCESS if the timer was successfully initialized.
*
*	CL_ERROR otherwise.
*
* NOTES
*	Allows calling cl_timer_start and cl_timer_stop.
*
* SEE ALSO
*	Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start,
*	cl_timer_stop, cl_pfn_timer_callback_t
*********/

/****f* Component Library: Timer/cl_timer_destroy
* NAME
*	cl_timer_destroy
*
* DESCRIPTION
*	The cl_timer_destroy function performs any necessary cleanup of a timer.
*
* SYNOPSIS
*/
	void
	 cl_timer_destroy(IN cl_timer_t * const p_timer);
/*
* PARAMETERS
*	p_timer
*		[in] Pointer to a cl_timer_t structure to destroy.
*
* RETURN VALUE
*	This function does not return a value.
*
* NOTES
*	cl_timer_destroy cancels any pending callbacks.
*
*	This function should only be called after a call to cl_timer_construct
*	or cl_timer_init.
*
* SEE ALSO
*	Timer, cl_timer_construct, cl_timer_init
*********/

/****f* Component Library: Timer/cl_timer_start
* NAME
*	cl_timer_start
*
* DESCRIPTION
*	The cl_timer_start function sets a timer to expire after a given interval.
*
* SYNOPSIS
*/
	 cl_status_t
	    cl_timer_start(IN cl_timer_t * const p_timer,
			   IN const uint32_t time_ms);
/*
* PARAMETERS
*	p_timer
*		[in] Pointer to a cl_timer_t structure to schedule.
*
*	time_ms
*		[in] Time, in milliseconds, before the timer should expire.
*
* RETURN VALUES
*	CL_SUCCESS if the timer was successfully scheduled.
*
*	CL_ERROR otherwise.
*
* NOTES
*	cl_timer_start implicitly stops the timer before being scheduled.
*
*	The interval specified by the time_ms parameter is a minimum interval.
*	The timer is guaranteed to expire no sooner than the desired interval, but
*	may take longer to expire.
*
* SEE ALSO
*	Timer, cl_timer_stop, cl_timer_trim
*********/

/****f* Component Library: Timer/cl_timer_stop
* NAME
*	cl_timer_stop
*
* DESCRIPTION
*	The cl_timer_stop function stops a pending timer from expiring.
*
* SYNOPSIS
*/
	void
	 cl_timer_stop(IN cl_timer_t * const p_timer);
/*
* PARAMETERS
*	p_timer
*		[in] Pointer to a cl_timer_t structure.
*
* RETURN VALUE
*	This function does not return a value.
*
* SEE ALSO
*	Timer, cl_timer_start, cl_timer_trim
*********/

/****f* Component Library: Timer/cl_timer_trim
* NAME
*	cl_timer_trim
*
* DESCRIPTION
*	The cl_timer_trim function pulls in the absolute expiration
*	time of a timer if the current expiration time exceeds the specified
*	interval.
*
*	sets a timer to expire after a given
*	interval if that interval is less than the current timer expiration.
*
* SYNOPSIS
*/
	 cl_status_t
	    cl_timer_trim(IN cl_timer_t * const p_timer,
			  IN const uint32_t time_ms);
/*
* PARAMETERS
*	p_timer
*		[in] Pointer to a cl_timer_t structure to schedule.
*
*	time_ms
*		[in] Maximum time, in milliseconds, before the timer should expire.
*
* RETURN VALUES
*	CL_SUCCESS if the timer was successfully scheduled.
*
*	CL_ERROR otherwise.
*
* NOTES
*	cl_timer_trim has no effect if the time interval is greater than the
*	remaining time when the timer is set.
*
*	If the new interval time is less than the remaining time, cl_timer_trim
*	implicitly stops the timer before reseting it.
*
*	If the timer is reset, it is guaranteed to expire no sooner than the
*	new interval, but may take longer to expire.
*
* SEE ALSO
*	Timer, cl_timer_start, cl_timer_stop
*********/

/****f* Component Library: Time Stamp/cl_get_time_stamp
* NAME
*	cl_get_time_stamp
*
* DESCRIPTION
*	The cl_get_time_stamp function returns the current time stamp in
*	microseconds since the system was booted.
*
* SYNOPSIS
*/
	 uint64_t cl_get_time_stamp(void);
/*
* RETURN VALUE
*	Time elapsed, in microseconds, since the system was booted.
*
* SEE ALSO
*	Timer, cl_get_time_stamp_sec
*********/

/****f* Component Library: Time Stamp/cl_get_time_stamp_sec
* NAME
*	cl_get_time_stamp_sec
*
* DESCRIPTION
*	The cl_get_time_stamp_sec function returns the current time stamp in
*	seconds since the system was booted.
*
* SYNOPSIS
*/
	 uint32_t cl_get_time_stamp_sec(void);
/*
* RETURN VALUE
*	Time elapsed, in seconds, since the system was booted.
*
* SEE ALSO
*	Timer, cl_get_time_stamp
*********/

#ifdef __cplusplus
}				/* extern "C" */
#endif
#endif				/* _CL_TIMER_H_ */
