34fc55e9ff6b2f8916084d0e8061b14291777c53
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi_util.h
1 /******************************************************
2  *  File: netapi_util.h
3  *  Purpose:  misc utilites
4  **************************************************************
5  * FILE: netapi_util.h
6  * 
7  * DESCRIPTION:  netapi utility header file for user space transport
8  *               library
9  * 
10  * REVISION HISTORY:
11  *
12  *  Copyright (c) Texas Instruments Incorporated 2013
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  *****************************************************/
43 #ifndef __NETAPI_UTIL__H
44 #define __NETAPI_UTIL__H
46 #include <stdint.h>
47 #include "./src/netapi_loc.h"
50 //#define NETAPI_DEBUG
51 #ifdef NETAPI_DEBUG
52 #define netapi_Log printf
53 #else
54 #define netapi_Log
55 #endif
57 extern NETAPI_SHM_T* pnetapiShm;
59 /* Wrapper functions around HPLIB APIs for QMSS , *utility to convert virt2phy, phy2virt */
60 #define _Osal_qmssVirtToPhy hplib_mVMVirtToPhy
62 #define _Osal_qmssPhyToVirt hplib_mVMPhyToVirt
64 //static hplib_spinLock_T netapi_util_lock = hplib_spinLock_UNLOCKED_INITIALIZER;
66 /**
67  *  @ingroup netapi_gen_functions
68  *  @brief netapi_registerHeap  API is used to register a heap that is created by application so that
69  *                              it's garbage queue can be polled automatically by @ref netapi_pollHeapGarbage.
70  *
71  *  @details This API registers an application-created heap with the netapi instance
72  *           so that it can add that heap's garbage queue to the garbage poll function. 
73  *           NOTE: netapi internal heap is automatically registered
74  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
75  *  @param[in]  h   Handle of pklib heap to register
76  *  @retval     1 if OK, <0 on error
77  *  @pre        @ref netapi_init
78  */
79 static inline int netapi_registerHeap(NETAPI_T p,
80                                       Pktlib_HeapHandle h)
81 {
82     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
83     int i;
84     pp->spinLock.lock(&pnetapiShm->netapi_util_lock);
85     for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
86     {
87         if (!pp->createdHeaps[i])
88         {
89             pp->createdHeaps[i]=h;
90             pp->spinLock.unlock(&pnetapiShm->netapi_util_lock);
91             return 1;
92         }
93     }
94     pp->spinLock.unlock(&pnetapiShm->netapi_util_lock);
95     return -1;
96 }
98 /**
99  *  @ingroup netapi_gen_functions
100  *  @brief netapi_unregisterHeap  API is used to un-register a heap that was created by application 
101  *                                and previously registered so that it's garbage queue could  be polled 
102  *                                automatically by @ref netapi_pollHeapGarbage. 
103  *
104  *  @details This API un-registers an application-created heap with the netapi instance. 
105  *           NOTE: netapi internal heap is automatically registered
106  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
107  *  @param[in]  h   The pklib handle to heap 
108  *  @retval     <0 if err, 1 if OK
109  *  @pre        @ref netapi_init
110  */
111 static inline int netapi_unregisterHeap(NETAPI_T p,
112                                         Pktlib_HeapHandle h)
114     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
115     int i;
116     pp->spinLock.lock(&pnetapiShm->netapi_util_lock);
117     for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
118     {
119             if (pp->createdHeaps[i] == h)
120             {
121                 pp->createdHeaps[i]=NULL;
122                 pp->spinLock.unlock(&pnetapiShm->netapi_util_lock);
123                 return 1;
124             }
125     }
126     pp->spinLock.unlock(&pnetapiShm->netapi_util_lock);
127     return -1;
130 /**
131  *  @ingroup netapi_gen_functions
132  *  @brief netapi_closeHeap  API is used to remove a created pktlib heap
133  *
134  *  @details This API removes an application-created heap with the netapi instance
135  *           NOTE: descriptors are zapped and cannot be reused]
136  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
137  *  @param[in]  h :  handle to pklib heap 
138  *  @retval     <0 if err, 1 if OK
139  *  @pre        @ref netapi_init  @ref netapi_registerHeap
140  */
141 static inline int netapi_closeHeap(NETAPI_T p,
142                                    Pktlib_HeapHandle h)
144     Qmss_QueueHnd q;
145     Pktlib_garbageCollection(h);
146     q = Pktlib_getZeroHeapQueue(h);
147     netapip_zapQ(q);
148     q= Pktlib_getInternalHeapQueue(h);
149     netapip_zapQ(q);
151 /**
152  *  @ingroup netapi_gen_functions
153  *  @brief netapi_getCookie  API is used to return a piece of application-provided opaque data that has been
154  *                           stored in the netapi instance.
155  *
156  *  @details The application can save a pointer to opaque data in the @ref NETAPI_T instance.
157  *           This APi lets this data be returned to the application.
158  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
159  *  @retval     Data provided in @ref netapi_setCookie
160  *  @pre        @ref netapi_init, @ref netapi_setCookie
161  */
163 static inline void * netapi_getCookie(NETAPI_T p)
165     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
166     return pp->cookie;
169 /**
170  *  @ingroup netapi_gen_functions
171  *  @brief netapi_setCookie  API is used to set a piece of application-provided opaque data t in the netapi instance.
172  *
173  *  @details The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
174  *           Pointer to a opaque data can be returned later to the application via @ref netapi_getCookie
175  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
176  *  @param[in]  cookie Opaque data to be saved
177  *  @retval     none
178  *  @pre        @ref netapi_init
179  */
180 static inline void netapi_setCookie(NETAPI_T p,
181                                     void * cookie)
183     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
184     pp->cookie= cookie;
187 /**
188  *  @ingroup netapi_gen_functions
189  *  @brief netapi_getBufMemRemainder  API is used to return the amount of free memory available for
190  *         allocating buffers for additonal Pktlib heaps
191  *
192  *  @details The application can use this API to determine how much free memory is
193  *           available for heap buffers if it decides to create its own.
194  *  @retval     Amount of memory available for heap buffer storage (in bytes)
195  *  @pre        @ref netapi_init 
196  */
197 static inline int  netapi_getBufMemRemainder(void)
199      return hplib_vmGetMemPoolRemainder(0);
202 /**
203  *  @ingroup netapi_gen_functions
204  *  @brief netapi_getDefaultFlow:  API is used to return the default NETCP flow that is to
205  *                                 be used for incoming packets.
206  *
207  *  @details   The application can use this API to return the default NETCP flow that is used
208  *             for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
209  *             used to supply free packets to the receive DMA function.
210  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
211  *  @retval     NETCP_CFG_FLOW_HANDLE_T     The handle to default flow
212  *  @pre        @ref netapi_init 
213  */
214 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p)
216     return NETCP_DEFAULT_FLOW;
219 /**
220  *  @ingroup netapi_gen_functions
221  *  @brief netapi_getDefaultRoute:  API is used to return the default NETCP route handle.
222  *
223  *  @details This API returns the default NETCP route created by @ref netapi_init.
224  *           A netcp route consists of a NETCP flow plus a destination pktio channel 
225  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
226  *  @retval     The handle of the default route, NETCP_CFG_ROUTE_HANDLE_T
227  *  @pre        @ref netapi_init  
228  */
229 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p)
231     return NETCP_DEFAULT_ROUTE;
234 /**
235  *  @ingroup cfg_functions
236  *  @brief netapi_netcpCfgGetPolicyUserData    API to retrieve user mode data associated with 
237  *                                             Policy APPID.
238  *
239  *  @details This api is used to retrieve user mode data associated with an Policy APPID
240  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
241  *  @param[in]  app_id  application id whose user mode data is to be retrieved
242  *  @retval void*   pointer to user mode data.
243  *  @pre       @ref netapi_init 
244  */
245 static inline void*  netapi_netcpCfgGetPolicyUserData(NETAPI_T h,
246                                                       NETCP_CFG_SA_T app_id)
248     NETAPI_NWAL_GLOBAL_CONTEXT_T *p = &netapi_get_global()->nwal_context;
249     int slot = netapi_cfgGetMatchId(app_id);
250     if ((slot <0 ) || (slot >= TUNE_NETAPI_MAX_POLICY))
251     {
252         return NULL;
253     }
254     return (p->policy[slot].user_data);
257 /**
258  *  @ingroup cfg_functions
259  *  @brief netapi_netcpCfgGetIpSecUserData    API to retrieve user mode data associated with IPSEC APPID.
260  *
261  *  @details This api is used to retrieve user mode data associated with an IPSEC APPID
262  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
263  *  @param[in]  app_id  application id whose user mode data is to be retrieved
264  *  @retval void*   pointer to user mode data.
265  *  @pre       @ref netapi_init 
266  */
267 static inline void*  netapi_netcpCfgGetIpSecUserData(NETAPI_T h,
268                                                      NETCP_CFG_SA_T app_id)
270     NETAPI_NWAL_GLOBAL_CONTEXT_T *p = &netapi_get_global()->nwal_context;
271     int slot = netapi_cfgGetMatchId(app_id);
272     netapi_Log("netapi_netcpCfgGetIpSecUserData: slot found %d\n", slot);
273     if ((slot <0 ) || (slot >= TUNE_NETAPI_MAX_SA))
274     {
275         return NULL;
276     }
277     netapi_Log("netapi_netcpCfgGetIpSecUserData: user data being returned %d\n",
278         (uint32_t)(p->tunnel[slot].user_data));
279     return (p->tunnel[slot].user_data);
283 /**
284  *  @ingroup cfg_functions
285  *  @brief netapi_netcpCfgGetIpUserData    API to retrieve user mode data associated with Generic IP APPID.
286  *
287  *  @details This api is used to retrieve user mode data associated with a Generic IP APPID
288  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
289  *  @param[in]  app_id  application id whose user mode data is to be retrieved
290  *  @retval void*   pointer to user mode data.
291  *  @pre       @ref netapi_init 
292  */
293 static inline void*  netapi_netcpCfgGetIpUserData(NETAPI_T h,
294                                                   NETCP_CFG_SA_T app_id)
296     NETAPI_NWAL_GLOBAL_CONTEXT_T *p = &netapi_get_global()->nwal_context;
297     int slot = netapi_cfgGetMatchId(app_id);
298     if ((slot <0 ) || (slot >= TUNE_NETAPI_MAX_NUM_IP))
299     {
300         return NULL;
301     }
302     return (p->ips[slot].user_data);
305 /**
306  *  @ingroup cfg_functions
307  *  @brief netapi_netcpCfgGetClassiferUserData  API to retrieve user mode data associated with Classifer APPID.
308  *
309  *  @details This api is used to retrieve user mode data associated with a flassifier APPID
310  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
311  *  @param[in]  app_id  application id whose user mode data is to be retrieved
312  *  @retval void*   pointer to user mode data.
313  *  @pre       @ref netapi_init 
314  */
315 static inline void*  netapi_netcpCfgGetClassiferUserData(NETAPI_T h,
316                                                          NETCP_CFG_SA_T app_id)
318     NETAPI_NWAL_GLOBAL_CONTEXT_T *p = &netapi_get_global()->nwal_context;
319     int slot = netapi_cfgGetMatchId(app_id);
320     if ((slot <0 ) || (slot >= TUNE_NETAPI_MAX_CLASSIFIERS))
321     {
322         return NULL;
323     }
324     return (p->classi[slot].user_data);
328 /**
329  *  @ingroup cfg_functions
330  *  @brief netapi_netcpCfgGetUserData    API to retrieve user mode data associated with APPID.
331  *
332  *  @details This api is used to retrieve user mode data associated with an APPID
333  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
334  *  @param[in]  app_id  application id whose user mode data is to be retrieved
335  *  @retval void*   pointer to user mode data.
336  *  @pre       @ref netapi_init 
337  */
338 static inline void*  netapi_netcpCfgGetUserData(NETAPI_T h,
339                                                 NETCP_CFG_SA_T app_id)
341     NETCP_CFG_SA_T appIdType;
342     NETAPI_NWAL_GLOBAL_CONTEXT_T *p = &netapi_get_global()->nwal_context;
344     appIdType = app_id & 0xff000000;
345     switch(appIdType)
346     {
347         case(NETAPI_NETCP_MATCH_IPSEC):
348             netapi_Log("netapi_netcpCfgGetUserData: ipsec appID found\n");
349             return (netapi_netcpCfgGetIpSecUserData(h, app_id));
350             break;
351         case(NETAPI_NETCP_MATCH_IPSEC_POLICY):
352             netapi_Log("netapi_netcpCfgGetUserData: policy appID found\n");
353             return (netapi_netcpCfgGetPolicyUserData(h, app_id));
354             break;
355         case(NETAPI_NETCP_MATCH_GENERIC_IP):
356             netapi_Log("netapi_netcpCfgGetUserData: IP appID found\n");
357             return (netapi_netcpCfgGetIpUserData(h, app_id));
358             break;
359         case(NETAPI_NETCP_MATCH_CLASS):
360             netapi_Log("netapi_netcpCfgGetUserData: classifier appID found\n");
361             return (netapi_netcpCfgGetClassiferUserData(h, app_id));
362             break;
363         default:
364             return NULL;
365             break;
366     }
369 /**
370  *  @ingroup cfg_functions
371  *  @brief netapi_netcpCfgUpdateUserData    API to update user mode data associated with APPID.
372  *
373  *  @details This api is used to update user mode data associated with an APPID
374  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
375  *  @param[in]  app_id  application id whose user mode data is to updated
376  *  @retval void*   pointer to user mode data.
377  *  @pre       @ref netapi_init 
378  */
379 static inline netapi_RetValue netapi_netcpCfgUpdateUserData(NETAPI_T h,
380                                                             NETCP_CFG_SA_T app_id,
381                                                             void * user_data)
383     NETCP_CFG_SA_T appIdType;
384     NETAPI_NWAL_GLOBAL_CONTEXT_T *p = &netapi_get_global()->nwal_context;
386     int slot = netapi_cfgGetMatchId(app_id);
387     if ((slot <0 ) || (slot >= TUNE_NETAPI_MAX_CLASSIFIERS))
388     {
389         return NETAPI_ERR_BAD_INPUT;
390     }
391     appIdType = app_id & 0xff000000;
392     switch(appIdType)
393     {
394         case(NETAPI_NETCP_MATCH_IPSEC):
395             netapi_Log("netapi_netcpCfgUpdateUserData: ipsec appID found\n");
396             p->tunnel[slot].user_data = user_data;
397             return NETAPI_ERR_OK;
398             break;
399         case(NETAPI_NETCP_MATCH_IPSEC_POLICY):
400             netapi_Log("netapi_netcpCfgUpdateUserData: policy appID found\n");
401             p->policy[slot].user_data = user_data;
402             return NETAPI_ERR_OK;
403             break;
404         case(NETAPI_NETCP_MATCH_GENERIC_IP):
405             netapi_Log("netapi_netcpCfgUpdateUserData: IP appID found\n");
406             p->ips[slot].user_data = user_data;
407             return NETAPI_ERR_OK;
408             break;
409         case(NETAPI_NETCP_MATCH_CLASS):
410             netapi_Log("netapi_netcpCfgUpdateUserData: classifier appID found\n");
411             p->classi[slot].user_data = user_data;
412             return NETAPI_ERR_OK;
413             break;
414         default:
415             return NETAPI_ERR_BAD_INPUT;
416             break;
417     }
420 #endif