/************************************************
 *FILE: netapi_timer.h
 *Purpose:  netapi timer related functions
 **************************************************************
 * FILE: netapi_timer.h
 * 
 * DESCRIPTION:  netapi timer library header file for user space transport
 *               library
 * 
 * REVISION HISTORY:  rev 0.0.1 
 *
 *  Copyright (c) Texas Instruments Incorporated 2010-2011
 * 
 *  Redistribution and use in source and binary forms, with or without 
 *  modification, are permitted provided that the following conditions 
 *  are met:
 *
 *    Redistributions of source code must retain the above copyright 
 *    notice, this list of conditions and the following disclaimer.
 *
 *    Redistributions in binary form must 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 Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 *  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 THE COPYRIGHT 
 *  OWNER OR 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.

 ***********************************************/

/**  @mainpage Netapi Timer Lib 
 *
 *   @section intro  Introduction
 *
 *   The network API provides a user space interface to timers
 *      - a function to read a hw provided 64bit time stamp, @ref netapi_getTimestamp
 *        This returns a tick running at 1/6 cpu frequency
 *      - functions to create or open timer groups: @ref netapi_TimerGroupCreateTimer
 *        and @ref  netapi_TimerGroupOpenTimer.  A timer group
 *        is a group of timers with the same characteristics:
 *        -> local or global
 *        -> timer resolution (msc, 10 msc, etc)
 *        -> expect to fire or expect to cancel
 *        -> the same call back function for fired timers
 *      - functions to close or delete timer groups
 *      - function to start a timer,  @ref netapi_TimerGroupStartTimer
 *      - function to cancel a timer,  @ref netapi_TimerGroupCancelTimer
 *      - function to poll a timer group, or all timer groups registered to a NETAPI 
 *        instance
 *  \par
 *  NOTE:
 *      (C) Copyright 2010-2011 Texas Instruments, Inc.
 *  \par
 */


#ifndef __NETAPI_TIMER__H
#define __NETAPI_TIMER__H
#include "netapi.h"

extern volatile unsigned long * t64_virt_addr;
extern unsigned int cpu_cycles_sec;

//return hw timer clock ticks per second
unsigned long t64_ticks_sec(void);
#define netapi_getTicksPerSec t64_ticks_sec


/**  @ingroup netapi_api_functions */

/*
 *  @brief  API returns a 64bit h/w timestamp 
 *
 *  @details reads a h/w timer (TIMER64 on Appleton SOC) and returns a 64 bit time stamp    
 *           timer runs at @ref t64_ticks_sec.  Nominally this should be 1/6 CPU clk (@ref cpu_cycles_sec)
 *           
 *  @param[in]  none 
 *  @retval     unsigned long long timestamp (64 buts) 
 *  @pre        @ref netapi_init 
 */
//return 64 bit timestamp from hw timer
static inline unsigned long long netapi_getTimestamp(void) 
{
 volatile unsigned long long t1;
 volatile unsigned long long t2;
 unsigned long long val;
 t1 = t64_virt_addr[0x10/4]; //lo
 t2 = t64_virt_addr[0x14/4]; //hi
 val = ((unsigned long long) t2) <<32 | t1;
 return val;
}

/******************************************************/
/*******************TIMER API***************************/
/******************************************************/
typedef void * NETAPI_TIMER_GROUP_HANDLE_T;     
typedef void * NETAPI_TIMER_T;
typedef void * NETAPI_TIMER_LIST_T;

/* timer filter values */
typedef int NETAPI_TIMER_FILTER_T;
#define NETAPI_TIMER_NA   (void*) NULL
#define NETAPI_TIMER_FILTER_GLOBAL 0x1
#define NETAPI_TIMER_FILTER_LOCAL 0x2
#define NETAPI_TIMER_FILTER_E2F 0x4
#define NETAPI_TIMER_FILTER_E2C 0x8
#define NETAPI_TIMER_FITLER_ALL 0xf

//iterator on TIMER_LIST_T
NETAPI_TIMER_T netapi_TimerGetFirst( NETAPI_TIMER_LIST_T list);
NETAPI_TIMER_T netapi_TimerGetNext( NETAPI_TIMER_LIST_T list,NETAPI_TIMER_T prev);
void * netapi_TimerGetCookie(NETAPI_TIMER_T timer);
unsigned long long netapi_TimerGetTs(NETAPI_TIMER_T timer); //debug

/*
 *  @brief  API callback for timer expiration 
 *
 *  @details this function, provided by application,  is registered by application 
 *  when timer group is created.  It is called by timer library when a timer or set of timers
 *  expire. The timer list can be walled with iterators: @ref netapi_TimerGetFirst, 
 *  @ref netapi_TimerGetNext.  The timer id or "cookie" can be accessed via @ref netapi_TimerGetCookie
 *  NOTE: callback should check for cookie==NULL since timer could be cancelled as it is being fired
 *  @param[in]   @ref NETAPI_TIMER_GROUP_HANDLE_T : the handle to the timer group
 *  @param[in]   int  : the number of timers that have fired 
 *  @param[in]   @ref NETAPI_TIMER_LIST_T : the list of timers that hace expired 
 *  @param[in]   uint64_t : the current time
 *  @retval     none 
 *  @pre        @ref netapi_init , @ref netapi_TimerGroupCreate, @ref netapi_TimerGroupStartTimer
 */
//timer callback
typedef void (*NETAPI_TIMER_CB_T) (
	NETAPI_TIMER_GROUP_HANDLE_T th,  //timer group
	int n_fired,     //# timers fired
	NETAPI_TIMER_LIST_T fired_list,  //the list of fired timers. Access via iterators above
	uint64_t currentTime); 	//current timestamp

/*
*  @brief  API  for Timer Group Creation 
 *
 *  @details this function is used to create a timer group. A timer group is a block of timers
 *  that share the same characteristics.
 *  @param[in]   @ref NETAPI_T : the handle to the NETAPI Instance 
 *  @param[in]   char * : the name of the timer
 *  @param[in]   @ref NETAPI_TIMER_CB_T :  the callback function
 *  @param[in]   int  : local   (=1 if this timer group is local to this netapi instance, =0 if global)
 *  @param[in]   int  : exp2cancel. (=1 if this timer group is expected to be cancelled, =0 otherwise))
 *  @param[in]   int  : the timer group 'tick'. This is the group timer resolution in hw timestamp units. 
 *                Eg for 10 msc , enter @ref netapi_getTicksPerSec()/100
 *  @param[in]   int  : timerTolerence in hw timestamp ticks.  This is FUTURE.
 *  @param[in]   int  : maxTimers - the max number of timers that can be handled by the group.
 *  @param[in]   int* : pointer to error return
 *  @retval     @ref NETAPI_TIMER_GROUP_HANDLE_T : handle for this timer group 
 *  @pre        @ref netapi_init 
 */
//create a timer group
NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
	NETAPI_T  netHandle,  //netapi instance
	char * name, //name of the timer block
	NETAPI_TIMER_CB_T cb, //the callback function
	int local,    //1 if timers local to thread
	int exp2cancel,//1 if expect to cancel
	int timerTicksPerGroupTick,  //resolution for this timer block, in hw timer ticks
        int timerTolerence,          //tolerence for this timer block, in hw timer ticksi [FUTURE]
	int maxTimers, //max # of timer objects for this group
	int *pErr);

//open a [global] timer group [FUTURE]
NETAPI_TIMER_GROUP_HANDLE_T  netapi_TimerGroupOpen(
	NETAPI_T netHandle,
        char * name,
	NETAPI_TIMER_CB_T cb,
	int *pErr);

/*
*  @brief  API  for Start a Timer 
 *
 *  @details this function is used to start a timer. When it expires, the @ref NETAPI_TIMER_CB_T
 *           will be called.
 *  @param[in]   @ref NATAPI_TIMER_GROUP_HANDLE_T : the handle to the timer group 
 *  @param[in]   void * :  application provided timer id or cookie. MUST NOT BE NULL!!!
 *  @param[in]   uint64_t  : offset from current time when to fire this timer.  This offset MUST be in
 *                           units of timer group ticks (set at create time).  Eg. For 10 msc timer group,
 *                           offset2fire =1 =>  timer is to fire in 10 msc.
 *  @param[in]   int* : pointer to error return
 *  @retval     @ref NETAPI_TIMER_T : handle for this timer. Used to reference the timer for cancel
 *  @pre        @ref netapi_init , @ref netapi_TimerGroupCreate
 */
//start an individual timer
NETAPI_TIMER_T netapi_TimerGroupStartTimer(
	NETAPI_TIMER_GROUP_HANDLE_T th,  //the group handle
	void * cookie,       //user id ->  CANNONT BE NULL 
	uint64_t offs2fire,  //offset in timerGroup ticks (eg msc)
	int * pErr);         //error return

/*
*  @brief  API  for Cancel a Timer 
 *
 *  @details this function is used to cancel a timer. When it expires, the @ref NETAPI_TIMER_CB_T
 *           will be called.
 *  @param[in]   @ref NATAPI_TIMER_GROUP_HANDLE_T : the handle to the timer group 
 *  @param[in]   @ref NATAPI_TIMER_T : the handle to the  individual timer to cancel
 *  @param[in]   int* : pointer to error return
 *  @retval    none 
 *  @pre        @ref netapi_TimerGroupStartTimer
 */
//Cancel a timer
void  netapi_TimerGroupCancel(
        NETAPI_TIMER_GROUP_HANDLE_T th,
	NETAPI_TIMER_T timerId,
        int *pErr);

//close an opened timer group
void netapi_TimerGroupClose(
	NETAPI_TIMER_GROUP_HANDLE_T th,
        int *pErr);

//close an opened timer group
void netapi_TimerGroupDelete(
        NETAPI_TIMER_GROUP_HANDLE_T th,
        int *pErr);

//extract netapi handle from timer group handle
NETAPI_T netap_TimerGroupGetNH( NETAPI_TIMER_GROUP_HANDLE_T th);

//poll a specific timer group
int  netapi_TimerGroupPoll(NETAPI_TIMER_GROUP_HANDLE_T th, int maxTimers);

/*
*  @brief  API  for Polling all timer groups attached to an instance 
 *
 *  @details this function is used to poll all or a specified subset of the timer groups of an 
 *  instance. A mask can be set to filter which categories of timer groups (local vs global etc)
 *  to poll. The approximate max # of timers to process can also be set.
 *  @param[in]   @ref NATAPI_T : the handle of the netapi instance. 
 *  @param[in]   @ref NATAPI_TIMER_FILTER_T : the bit mask of timer group types to poll 
 *  @param[in]   int : approximate max number of timers to process.  NOTE: this can be used to
 *               coarsely control how many timers to process. In general, all timers that have been 
 *               hashed into the same cell and have expired will be processed regardless of the
 *               maxTmers setting.. [FUTURE]
 *  @retval    none 
 *  @pre        @ref netapi_init, @ref netapi_TimerGroupCreate
 */

//poll all timers
int  netapi_TimerGroupPollAll(NETAPI_T nh, NETAPI_TIMER_FILTER_T f,  int maxTimers);

/*****************END API*********************************/


#endif