Makefile-> change name of netapi lib
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi_timer.h
index a74294c20ecb9f440a725636ce13169e01f24fa5..213974c6deb2c8d0bad729b01b797e1715d8b0dd 100644 (file)
  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
  ***********************************************/
  *  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"
 #ifndef __NETAPI_TIMER__H
 #define __NETAPI_TIMER__H
 #include "netapi.h"
 extern volatile unsigned long * t64_virt_addr;
 extern unsigned int cpu_cycles_sec;
 
 extern volatile unsigned long * t64_virt_addr;
 extern unsigned int cpu_cycles_sec;
 
-//return clock ticks per second
+//return hw timer clock ticks per second
 unsigned long t64_ticks_sec(void);
 #define netapi_getTicksPerSec t64_ticks_sec
 
 unsigned long t64_ticks_sec(void);
 #define netapi_getTicksPerSec t64_ticks_sec
 
-//return 64 bit timestamp
+
+/**  @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;
 static inline unsigned long long netapi_getTimestamp(void) 
 {
  volatile unsigned long long t1;
@@ -69,6 +109,8 @@ static inline unsigned long long netapi_getTimestamp(void)
 typedef void * NETAPI_TIMER_GROUP_HANDLE_T;     
 typedef void * NETAPI_TIMER_T;
 typedef void * NETAPI_TIMER_LIST_T;
 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
 typedef int NETAPI_TIMER_FILTER_T;
 #define NETAPI_TIMER_NA   (void*) NULL
 #define NETAPI_TIMER_FILTER_GLOBAL 0x1
@@ -83,13 +125,46 @@ 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
 
 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) (
 //timer callback
 typedef void (*NETAPI_TIMER_CB_T) (
-       NETAPI_TIMER_GROUP_HANDLE_T th,
+       NETAPI_TIMER_GROUP_HANDLE_T th,  //timer group
        int n_fired,     //# timers fired
        int n_fired,     //# timers fired
-       NETAPI_TIMER_LIST_T fired_list,
-       uint64_t currentTime);  
+       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
 //create a timer group
 NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
        NETAPI_T  netHandle,  //netapi instance
@@ -97,23 +172,50 @@ NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
        NETAPI_TIMER_CB_T cb, //the callback function
        int local,    //1 if timers local to thread
        int exp2cancel,//1 if expect to cancel
        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 timer ticks
+       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);
 
        int maxTimers, //max # of timer objects for this group
        int *pErr);
 
-//open a [global] timer group
+//open a [global] timer group [FUTURE]
 NETAPI_TIMER_GROUP_HANDLE_T  netapi_TimerGroupOpen(
        NETAPI_T netHandle,
 NETAPI_TIMER_GROUP_HANDLE_T  netapi_TimerGroupOpen(
        NETAPI_T netHandle,
+        char * name,
        NETAPI_TIMER_CB_T cb,
        int *pErr);
 
        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
 //start an individual timer
-NETAPI_TIMER_T netapi_TimerGroupStartiTimer(
-       NETAPI_TIMER_GROUP_HANDLE_T th,
-       void * cookie,
+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)
        uint64_t offs2fire,  //offset in timerGroup ticks (eg msc)
-       int * pErr);
+       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,
 //Cancel a timer
 void  netapi_TimerGroupCancel(
         NETAPI_TIMER_GROUP_HANDLE_T th,
@@ -136,6 +238,22 @@ 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);
 
 //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);
 
 //poll all timers
 int  netapi_TimerGroupPollAll(NETAPI_T nh, NETAPI_TIMER_FILTER_T f,  int maxTimers);