Makefile-> change name of netapi lib
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi_timer.h
1 /************************************************
2  *FILE: netapi_timer.h
3  *Purpose:  netapi timer related functions
4  **************************************************************
5  * FILE: netapi_timer.h
6  * 
7  * DESCRIPTION:  netapi timer library header file for user space transport
8  *               library
9  * 
10  * REVISION HISTORY:  rev 0.0.1 
11  *
12  *  Copyright (c) Texas Instruments Incorporated 2010-2011
13  * 
14  *  Redistribution and use in source and binary forms, with or without 
15  *  modification, are permitted provided that the following conditions 
16  *  are met:
17  *
18  *    Redistributions of source code must retain the above copyright 
19  *    notice, this list of conditions and the following disclaimer.
20  *
21  *    Redistributions in binary form must reproduce the above copyright
22  *    notice, this list of conditions and the following disclaimer in the 
23  *    documentation and/or other materials provided with the   
24  *    distribution.
25  *
26  *    Neither the name of Texas Instruments Incorporated nor the names of
27  *    its contributors may be used to endorse or promote products derived
28  *    from this software without specific prior written permission.
29  *
30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
31  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
32  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
33  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
34  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
35  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
36  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
37  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
38  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
39  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
40  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42  ***********************************************/
44 /**  @mainpage Netapi Timer Lib 
45  *
46  *   @section intro  Introduction
47  *
48  *   The network API provides a user space interface to timers
49  *      - a function to read a hw provided 64bit time stamp, @ref netapi_getTimestamp
50  *        This returns a tick running at 1/6 cpu frequency
51  *      - functions to create or open timer groups: @ref netapi_TimerGroupCreateTimer
52  *        and @ref  netapi_TimerGroupOpenTimer.  A timer group
53  *        is a group of timers with the same characteristics:
54  *        -> local or global
55  *        -> timer resolution (msc, 10 msc, etc)
56  *        -> expect to fire or expect to cancel
57  *        -> the same call back function for fired timers
58  *      - functions to close or delete timer groups
59  *      - function to start a timer,  @ref netapi_TimerGroupStartTimer
60  *      - function to cancel a timer,  @ref netapi_TimerGroupCancelTimer
61  *      - function to poll a timer group, or all timer groups registered to a NETAPI 
62  *        instance
63  *  \par
64  *  NOTE:
65  *      (C) Copyright 2010-2011 Texas Instruments, Inc.
66  *  \par
67  */
70 #ifndef __NETAPI_TIMER__H
71 #define __NETAPI_TIMER__H
72 #include "netapi.h"
74 extern volatile unsigned long * t64_virt_addr;
75 extern unsigned int cpu_cycles_sec;
77 //return hw timer clock ticks per second
78 unsigned long t64_ticks_sec(void);
79 #define netapi_getTicksPerSec t64_ticks_sec
82 /**  @ingroup netapi_api_functions */
84 /*
85  *  @brief  API returns a 64bit h/w timestamp 
86  *
87  *  @details reads a h/w timer (TIMER64 on Appleton SOC) and returns a 64 bit time stamp    
88  *           timer runs at @ref t64_ticks_sec.  Nominally this should be 1/6 CPU clk (@ref cpu_cycles_sec)
89  *           
90  *  @param[in]  none 
91  *  @retval     unsigned long long timestamp (64 buts) 
92  *  @pre        @ref netapi_init 
93  */
94 //return 64 bit timestamp from hw timer
95 static inline unsigned long long netapi_getTimestamp(void) 
96 {
97  volatile unsigned long long t1;
98  volatile unsigned long long t2;
99  unsigned long long val;
100  t1 = t64_virt_addr[0x10/4]; //lo
101  t2 = t64_virt_addr[0x14/4]; //hi
102  val = ((unsigned long long) t2) <<32 | t1;
103  return val;
106 /******************************************************/
107 /*******************TIMER API***************************/
108 /******************************************************/
109 typedef void * NETAPI_TIMER_GROUP_HANDLE_T;     
110 typedef void * NETAPI_TIMER_T;
111 typedef void * NETAPI_TIMER_LIST_T;
113 /* timer filter values */
114 typedef int NETAPI_TIMER_FILTER_T;
115 #define NETAPI_TIMER_NA   (void*) NULL
116 #define NETAPI_TIMER_FILTER_GLOBAL 0x1
117 #define NETAPI_TIMER_FILTER_LOCAL 0x2
118 #define NETAPI_TIMER_FILTER_E2F 0x4
119 #define NETAPI_TIMER_FILTER_E2C 0x8
120 #define NETAPI_TIMER_FITLER_ALL 0xf
122 //iterator on TIMER_LIST_T
123 NETAPI_TIMER_T netapi_TimerGetFirst( NETAPI_TIMER_LIST_T list);
124 NETAPI_TIMER_T netapi_TimerGetNext( NETAPI_TIMER_LIST_T list,NETAPI_TIMER_T prev);
125 void * netapi_TimerGetCookie(NETAPI_TIMER_T timer);
126 unsigned long long netapi_TimerGetTs(NETAPI_TIMER_T timer); //debug
128 /*
129  *  @brief  API callback for timer expiration 
130  *
131  *  @details this function, provided by application,  is registered by application 
132  *  when timer group is created.  It is called by timer library when a timer or set of timers
133  *  expire. The timer list can be walled with iterators: @ref netapi_TimerGetFirst, 
134  *  @ref netapi_TimerGetNext.  The timer id or "cookie" can be accessed via @ref netapi_TimerGetCookie
135  *  NOTE: callback should check for cookie==NULL since timer could be cancelled as it is being fired
136  *  @param[in]   @ref NETAPI_TIMER_GROUP_HANDLE_T : the handle to the timer group
137  *  @param[in]   int  : the number of timers that have fired 
138  *  @param[in]   @ref NETAPI_TIMER_LIST_T : the list of timers that hace expired 
139  *  @param[in]   uint64_t : the current time
140  *  @retval     none 
141  *  @pre        @ref netapi_init , @ref netapi_TimerGroupCreate, @ref netapi_TimerGroupStartTimer
142  */
143 //timer callback
144 typedef void (*NETAPI_TIMER_CB_T) (
145         NETAPI_TIMER_GROUP_HANDLE_T th,  //timer group
146         int n_fired,     //# timers fired
147         NETAPI_TIMER_LIST_T fired_list,  //the list of fired timers. Access via iterators above
148         uint64_t currentTime);  //current timestamp
150 /*
151 *  @brief  API  for Timer Group Creation 
152  *
153  *  @details this function is used to create a timer group. A timer group is a block of timers
154  *  that share the same characteristics.
155  *  @param[in]   @ref NETAPI_T : the handle to the NETAPI Instance 
156  *  @param[in]   char * : the name of the timer
157  *  @param[in]   @ref NETAPI_TIMER_CB_T :  the callback function
158  *  @param[in]   int  : local   (=1 if this timer group is local to this netapi instance, =0 if global)
159  *  @param[in]   int  : exp2cancel. (=1 if this timer group is expected to be cancelled, =0 otherwise))
160  *  @param[in]   int  : the timer group 'tick'. This is the group timer resolution in hw timestamp units. 
161  *                Eg for 10 msc , enter @ref netapi_getTicksPerSec()/100
162  *  @param[in]   int  : timerTolerence in hw timestamp ticks.  This is FUTURE.
163  *  @param[in]   int  : maxTimers - the max number of timers that can be handled by the group.
164  *  @param[in]   int* : pointer to error return
165  *  @retval     @ref NETAPI_TIMER_GROUP_HANDLE_T : handle for this timer group 
166  *  @pre        @ref netapi_init 
167  */
168 //create a timer group
169 NETAPI_TIMER_GROUP_HANDLE_T netapi_TimerGroupCreate(
170         NETAPI_T  netHandle,  //netapi instance
171         char * name, //name of the timer block
172         NETAPI_TIMER_CB_T cb, //the callback function
173         int local,    //1 if timers local to thread
174         int exp2cancel,//1 if expect to cancel
175         int timerTicksPerGroupTick,  //resolution for this timer block, in hw timer ticks
176         int timerTolerence,          //tolerence for this timer block, in hw timer ticksi [FUTURE]
177         int maxTimers, //max # of timer objects for this group
178         int *pErr);
180 //open a [global] timer group [FUTURE]
181 NETAPI_TIMER_GROUP_HANDLE_T  netapi_TimerGroupOpen(
182         NETAPI_T netHandle,
183         char * name,
184         NETAPI_TIMER_CB_T cb,
185         int *pErr);
187 /*
188 *  @brief  API  for Start a Timer 
189  *
190  *  @details this function is used to start a timer. When it expires, the @ref NETAPI_TIMER_CB_T
191  *           will be called.
192  *  @param[in]   @ref NATAPI_TIMER_GROUP_HANDLE_T : the handle to the timer group 
193  *  @param[in]   void * :  application provided timer id or cookie. MUST NOT BE NULL!!!
194  *  @param[in]   uint64_t  : offset from current time when to fire this timer.  This offset MUST be in
195  *                           units of timer group ticks (set at create time).  Eg. For 10 msc timer group,
196  *                           offset2fire =1 =>  timer is to fire in 10 msc.
197  *  @param[in]   int* : pointer to error return
198  *  @retval     @ref NETAPI_TIMER_T : handle for this timer. Used to reference the timer for cancel
199  *  @pre        @ref netapi_init , @ref netapi_TimerGroupCreate
200  */
201 //start an individual timer
202 NETAPI_TIMER_T netapi_TimerGroupStartTimer(
203         NETAPI_TIMER_GROUP_HANDLE_T th,  //the group handle
204         void * cookie,       //user id ->  CANNONT BE NULL 
205         uint64_t offs2fire,  //offset in timerGroup ticks (eg msc)
206         int * pErr);         //error return
208 /*
209 *  @brief  API  for Cancel a Timer 
210  *
211  *  @details this function is used to cancel a timer. When it expires, the @ref NETAPI_TIMER_CB_T
212  *           will be called.
213  *  @param[in]   @ref NATAPI_TIMER_GROUP_HANDLE_T : the handle to the timer group 
214  *  @param[in]   @ref NATAPI_TIMER_T : the handle to the  individual timer to cancel
215  *  @param[in]   int* : pointer to error return
216  *  @retval    none 
217  *  @pre        @ref netapi_TimerGroupStartTimer
218  */
219 //Cancel a timer
220 void  netapi_TimerGroupCancel(
221         NETAPI_TIMER_GROUP_HANDLE_T th,
222         NETAPI_TIMER_T timerId,
223         int *pErr);
225 //close an opened timer group
226 void netapi_TimerGroupClose(
227         NETAPI_TIMER_GROUP_HANDLE_T th,
228         int *pErr);
230 //close an opened timer group
231 void netapi_TimerGroupDelete(
232         NETAPI_TIMER_GROUP_HANDLE_T th,
233         int *pErr);
235 //extract netapi handle from timer group handle
236 NETAPI_T netap_TimerGroupGetNH( NETAPI_TIMER_GROUP_HANDLE_T th);
238 //poll a specific timer group
239 int  netapi_TimerGroupPoll(NETAPI_TIMER_GROUP_HANDLE_T th, int maxTimers);
241 /*
242 *  @brief  API  for Polling all timer groups attached to an instance 
243  *
244  *  @details this function is used to poll all or a specified subset of the timer groups of an 
245  *  instance. A mask can be set to filter which categories of timer groups (local vs global etc)
246  *  to poll. The approximate max # of timers to process can also be set.
247  *  @param[in]   @ref NATAPI_T : the handle of the netapi instance. 
248  *  @param[in]   @ref NATAPI_TIMER_FILTER_T : the bit mask of timer group types to poll 
249  *  @param[in]   int : approximate max number of timers to process.  NOTE: this can be used to
250  *               coarsely control how many timers to process. In general, all timers that have been 
251  *               hashed into the same cell and have expired will be processed regardless of the
252  *               maxTmers setting.. [FUTURE]
253  *  @retval    none 
254  *  @pre        @ref netapi_init, @ref netapi_TimerGroupCreate
255  */
257 //poll all timers
258 int  netapi_TimerGroupPollAll(NETAPI_T nh, NETAPI_TIMER_FILTER_T f,  int maxTimers);
260 /*****************END API*********************************/
263 #endif