Makefile-> change name of netapi lib
authorDavid Lide <a0216552@gtudci01.(none)>
Thu, 26 Jan 2012 22:29:54 +0000 (17:29 -0500)
committerDavid Lide <a0216552@gtudci01.(none)>
Thu, 26 Jan 2012 22:29:54 +0000 (17:29 -0500)
netapi_timer.h -> added comments, minor changs to api
timlist.c -> bug in recovering cancelled timer, added unit test code
netapi_timer.c -> minor api changes\

ti/runtime/netapi/build/Makefile
ti/runtime/netapi/netapi_timer.h
ti/runtime/netapi/src/netapi_timer.c
ti/runtime/netapi/src/timlist.c
ti/runtime/netapi/test/build/Makefile
ti/runtime/netapi/test/net_test.c

index 63dd2ecb90437ddea7aa67781899fcc134ceeb69..ae05a1198ec5e82f407854d316a0b504ec610020 100644 (file)
@@ -33,10 +33,10 @@ clean:
 %.o: %.c
        $(CC)  -c  $(CFLAGS)  $<  -o $@
 
-api: $(NETAPI_LIB_DIR)/api_lib.a
+api: $(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a
 
-$(NETAPI_LIB_DIR)/api_lib.a:  $(API_OBJS) 
-       rm -f $(NETAPI_LIB_DIR)/api_lib.a
-       $(AR)  rcv $(NETAPI_LIB_DIR)/api_lib.a $(API_OBJS)
+$(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a:  $(API_OBJS) 
+       rm -f $(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a
+       $(AR)  rcv $(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a $(API_OBJS)
 
        
index a74294c20ecb9f440a725636ce13169e01f24fa5..213974c6deb2c8d0bad729b01b797e1715d8b0dd 100644 (file)
  *  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 clock ticks per second
+//return hw timer clock ticks per second
 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;
@@ -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;
+
+/* timer filter values */
 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
 
+/*
+ *  @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,
+       NETAPI_TIMER_GROUP_HANDLE_T th,  //timer group
        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
@@ -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
-       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);
 
-//open a [global] timer group
+//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_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)
-       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,
@@ -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);
 
+/*
+*  @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);
 
index 2565089e33fef05b19abdbe0e6d7fa956971d77d..21d5cdd946c114db584c3a7db7a2d6ca3a9f7798 100644 (file)
@@ -95,7 +95,8 @@ NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
         NETAPI_TIMER_CB_T cb,
         int local,    //1 if timers local to thread
         int exp2cancel,//1 if expect to cancel
-        int cell_width,
+        int cell_width, //in ticks
+       int tol,        //in ticks
         int maxTimers,
         int *pErr)
 {
@@ -106,6 +107,7 @@ NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
  temp_g.local = local;
  temp_g.exp2cancel= exp2cancel;
  temp_g.cell_width=cell_width;
+ temp_g.tol=tol;
  temp_g.h = netHandle;
  temp_g.last_polled=(netapi_getTimestamp()/cell_width) * cell_width + (cell_width-1);
  printf(">timer group %s created. width = %d (ticks)\n", name, cell_width);
@@ -115,6 +117,7 @@ NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
 //open a [global] timer group
 NETAPI_TIMER_GROUP_HANDLE_T  netapi_TimerGroupOpen(
         NETAPI_T netHandle,
+        char * name,
         NETAPI_TIMER_CB_T cb,
         int *pErr)
 {
@@ -208,7 +211,7 @@ int c_seen=0;
       tim_return_fired_list(&((TIMER_GROUP_T*) th)->cells[cell],
                            &res,
                             &((TIMER_GROUP_T*) th)->free,
-                            i,
+                            i,  
                             &n);
       if (n)
       {
@@ -231,7 +234,8 @@ int c_seen=0;
 int  netapi_TimerGroupPollAll(NETAPI_T nh, NETAPI_TIMER_FILTER_T f,  int maxTimers)
 {
  //todo: use filters and poll global, local lists in nh
- netapi_TimerGroupPoll(&temp_g, maxTimers);
+ if (temp_g.h)
+    netapi_TimerGroupPoll(&temp_g, maxTimers);
  return 0;
 }
 
index dcea6e9364737d0f7afdba458b15989ba6c06347..9b086de91b77813f176486a6eb5b3991122f99b1 100644 (file)
  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
  ***************************************/
-#include "netapi_timer.h"
+//#define TEST_DRIVER
+#ifdef TEST_DRIVER
+typedef void * NETAPI_T;
+typedef void * NETAPI_TIMER_CB_T;
+#else
+#include "../netapi_timer.h"
+#endif
 #include "timer_loc.h"
-#include "netapi_err.h"
+#include "../netapi_err.h"
 
 #ifndef NULL
 #define NULL 0
@@ -181,13 +187,14 @@ for(i=0;p;)
        }
        else //skip over cancelled timer..
        {
-         //skip & free
+         //skip & free. make sure we adjust head or tail if necessary
          if (p_last){
              p_last->next=p->next; 
          }
          else {
-            tl->head = p->next;
+            tl->head = p->next; /* we are freeing old head..*/
          }
+         if (tl->tail ==p)  tl->tail=p_last; /* we are freeing old tail */
          temp_p_next=p->next;
          tim_return_single_free(ftl,p);
          p=temp_p_next; 
@@ -206,6 +213,7 @@ for(i=0;p;)
          else {
             tl->head = p->next;
          }
+         if (tl->tail ==p)  tl->tail=p_last; /* we are freeing old tail */
          temp_p_next=p->next;
          tim_return_single_free(ftl,p);
          p=temp_p_next;      
@@ -305,7 +313,6 @@ tl->tail=p;
 return p;
 }
 
-//#define TEST_DRIVER
 #ifdef TEST_DRIVER
 TIM_LIST_T the_base={NULL,NULL};
 TIM_LIST_T cell_base={NULL,NULL};
@@ -340,7 +347,23 @@ tim_return_fired_list(&cell_base, &res, &the_base, (unsigned long long) i,  &n);
  printf("at %d got %d\n", i, n);
  if (n) tim_return_free(&the_base,&res,n);
  }
+
+//special cases..
+
+ timers[0]=tim_set(&cell_base, &the_base, 106LL, (void *)10, &err);
+ tim_cancel(timers[0],&err);
+ tim_return_fired_list(&cell_base, &res, &the_base, (unsigned long long) 106,  &n);
  
+ timers[0]=tim_set(&cell_base, &the_base, 106LL, (void *)10, &err);
+ timers[1]=tim_set(&cell_base, &the_base, 106LL, (void *)10, &err);
+ tim_cancel(timers[0],&err);
+ tim_return_fired_list(&cell_base, &res, &the_base, (unsigned long long) 106,  &n);
+
+ timers[0]=tim_set(&cell_base, &the_base, 106LL, (void *)10, &err);
+ timers[1]=tim_set(&cell_base, &the_base, 106LL, (void *)10, &err);
+ tim_cancel(timers[0],&err);
+ tim_cancel(timers[1],&err);
+ tim_return_fired_list(&cell_base, &res, &the_base, (unsigned long long) 106,  &n);
  
 }
 #endif
index b98c38a2a57aa967841dcf1b79ea29fd3b9324bd..21c2edefe257c062db8d16074d2ff1cb31479f4e 100644 (file)
@@ -40,11 +40,11 @@ clean:
 %.o: %.c
        $(CC)  -c  $(CFLAGS)  $<  -o $@
 
-$(NETAPI_LIB_DIR)/api_lib.a:
+$(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a:
        make -C $(NETAPI_BUILD_DIR) 
 
-net_test:  $(NT_OBJS) $(TRIE_OBJS) $(NETAPI_LIB_DIR)/api_lib.a
-       $(CC) $(LDFLAGS)  $(NT_OBJS) $(TRIE_OBJS) $(NETAPI_LIB_DIR)/api_lib.a $(PKTLIB_LIB) $(QMSS_LIB) $(CPPI_LIB) $(NWAL_LIB) $(PA_LIB)  -o net_test
+net_test:  $(NT_OBJS) $(TRIE_OBJS) $(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a
+       $(CC) $(LDFLAGS)  $(NT_OBJS) $(TRIE_OBJS) $(NETAPI_LIB_DIR)/ti.runtime.netapi.aearmv7.a $(PKTLIB_LIB) $(QMSS_LIB) $(CPPI_LIB) $(NWAL_LIB) $(PA_LIB)  -o net_test
 
         
 synchtest: ../synchtest.o
index 188890e6c45c0679f5419a783008bee2d19cb31d..8d147d0d24987f9f4645ce0551fa6cf5653f3f8a 100755 (executable)
@@ -554,11 +554,22 @@ for(i=0;i<n_fired;i++)
         200LL,  //every  second
         &err);
   else
+  {
     t3 = netapi_TimerGroupStartTimer(
         th,
         (void *) 3,
         300LL,  //every  second
         &err);
+    //cancel 1 and restart 1
+   netapi_TimerGroupCancel(th,t1,&err);
+   t1 = netapi_TimerGroupStartTimer(
+        th,
+        (void *) 1,
+        100LL,  //every  second
+        &err);
+
+
+ }
 
 
   tx = netapi_TimerGetNext(fired_list,tx); 
@@ -771,6 +782,7 @@ if (err) {printf("addmac1 failed %d\n",err); exit(1); }
         0,    //1 if timers local to thread
         0,    //1 if expect to cancel
         netapi_getTicksPerSec()/100,  /* 10 msc resolution for these timers */
+        netapi_getTicksPerSec()/1000, /* would like 1msc tolerence */
         100,
         &err);
 if (err) {printf("timergroupcreate failed %d\n",err); exit(1);}