7bc17e4b02cd971ac148696132fa71ecda136f9e
[keystone-rtos/netapi.git] / ti / runtime / netapi / netcp_cfg.h
1 /***************************************************
2  * File: netcp_cfg.h 
3  * Purpose: netcp config API
4  **************************************************************
5  *@file netcp_cfg.h
6  * 
7  * @brief DESCRIPTION:  netapi NETCP configuration API header  file 
8  *          for user space transport 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 #ifndef __NETCP_CFG__H
45 #define __NETCP_CFG__H
47 #include "netapi.h"
48 #include "ti/drv/pa/pa.h"
49 #include "ti/runtime/pktlib/pktlib.h"
51 //NETCP FLOW
52 typedef struct NETCP_CFG_FLOW_Tag
53 {
54         int flowid;
55 } NETCP_CFG_FLOW_T;
56 typedef void *  NETCP_CFG_FLOW_HANDLE_T;
57 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
59 //NETCP ROUTE
60 typedef struct NETCP_CFG_ROUTE_Tag
61 {
62    NETCP_CFG_FLOW_T * p_flow;  //NULL or NETCP_DEFAULT_FLOW for default flow
63    PKTIO_HANDLE_T * p_dest_q;       //NULL for default destination queue
64 } NETCP_CFG_ROUTE_T;
65 typedef void * NETCP_CFG_ROUTE_HANDLE_T;  
66 #define NETCP_DEFAULT_ROUTE  (NETCP_CFG_ROUTE_HANDLE_T*) NULL
69 /*--------------flow management--------*/
70 NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T ,
71                                             int n, 
72                                             Pktlib_HeapHandle handles[],
73                                             int sizes[], //must be<= heap corresponding heap size-recv_offset-any desired tail room
74                                             int recv_offset,  //bytes to save in front of packet
75                                             int * err );
76 void netcp_cfgDelFlow(NETAPI_T , NETCP_CFG_FLOW_HANDLE_T , int * err);
78 /*-----------Actions----------*/
79 #define NETCP_CFG_ACTION_DISCARD 0
80 #define NETCP_CFG_ACTION_CONTINUE 1  //pass packet on to next classifier
81 #define NETCP_CFG_ACTION_TO_SW    2
83 /*------------L2----------------------*/
84 typedef void * NETCP_CFG_VLAN_T;
86 /******************************************************************/
87 /***********************APP ids for rx meta data********************/
88 /******************************************************************/
90 /* APPIDs are present in RX packet meta data and tell "how far the packet got
91    through the classification rules of NETCP 
92    APPID is 32 bits:
93       bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
94       bits 23-8  = identifier (depends on match stage)
95       bits  7-0  = logical mac interface
97    As a cheat sheet:
98 If APPID == _NETCP_MATCH_GENERIC_MAC  then
99    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.  
100    Packet did not match any other rule
102 If APPID == _NETCP_MATCH_GENERIC_IP  then
103    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
104    packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
105    is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
107 If APPID = NETCP_MATCH_CLASS
108    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
109    packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
110    the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
111    Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
112    give the ID of the classifier . Packet did not match any other rule
114 If APPID = NETCP_MATCH_CLASS_L3   (partial classifier match)
115    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
116    packet matched a general IP rule added as part of a classifier.  But it not match a
117    L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
118    not applicable
121 If APPID = NETCP_MATCH_IPSEC
122    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
123    packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
124    bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
126 ID APPID = NETCP_MATCH_IPSEC_POLICY   
127    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
128    packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
129    a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
130    bytes 3-2 of APPID.  Packet did not match any other rule 
131 */
133       
134 // NWAL "AP ids" for PA Rules that are added
135 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000  //lower byte==interface
136 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000  //lower byte==interface
137 #define NETAPI_NETCP_MATCH_CLASS        0x80000000  //FULL MATCH or' in classifier (16 bits), lower byte==interface
138 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000  //MATCHED L3 but not L4.  lower byte==interface
139 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
140 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000  //lower byte==interface, Or' in SA id (16 bits)
142 /*---------MAC APPID------------------*/
143 /* Packets just matching MAC rule are tagged with this type (MATCH_GENERIC_MAC) */
144 typedef uint32_t NETCP_CFG_MACIF_T;
146 /*---------------IP APPID-------------------*/
147 /* Packets whose final match is an IP rule are tagged with this type (MATCH_GENERIC_IP)*/ 
148 typedef uint32_t NETCP_CFG_IP_T;
150 /*--------------Tunnel APPID------------------*/
151 /* Packets whose final match a IPSEC tunnel  are tagged with this type (MATCH_IPSEC)*/ 
152 typedef uint32_t NETCP_CFG_SA_T;  
154 /*---------------IPSEc RX Policy APPID------------*/
155 /* Packets whose final match is a IPSEC RX Policy  are tagged with this type (MATCH_IPSEC_POLICY)*/ 
156 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;  
159 //use this in AddIp, AddClassifier to indicate any MAC address
160 #define NETCP_CFG_NO_INTERFACE 0xff
162 /* del mac i/f */
163 void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
165 /* del attached IP*/
166 void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
167                   nwalIpAddr_t  * ip_addr,
168                   nwalIpOpt_t * ip_qualifiers, 
169                   NETCP_CFG_IP_T, 
170                   int *err);
171  
173 /*****************************************************************
174  * Create a  MAC interface 
175  ****************************************************************/
176 /*
177 *  @brief  API Creates a MAC interface  
178  *
179  *  @details This api is used to create a MAC interface.
180  *      Once it is created, the MAC interface can be used to receive packets. The API
181  *      adds a rule to the NETCP 1st level lookup tables to route all packets with destination
182  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netcp_cfgAddIp) to
183  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
184  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
185  *  Note: The internal SOC switch must be "taught" that this mac
186  *      address is present by transmitting a packet with destination mac = this interface mac address.
187  *  @param[in]  @ref NETAPI_T: NETAPI instance 
188  *  @param[in]  char *: pointer to 6 byte MAC address for interface
189  *  @param[in]  int : interface number (0,1,..) 
190  *  @param[in]  int : switch port (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported] 
191  *  @param[in]  @ref NETCP_CFG_ROUTE_HANDLE_T : [future] handle of a created route or NULL to use internal default route 
192  *  @oaram[in]  @ref NETCP_CFG_VLAN_T : [future[ vlan configuration . Set to NULL
193  *  @param[in]  int : [future] interface state (0=down, 1= up)
194  *  @param[out] int * err:  pointer to error return
195  *  @retval     @ref NETCP_CFG_MACIF_T : returned AppID for interface (this is returned in meta data for
196  *                 received packets matching this rule an no others)
197  *  @pre       @ref netapi_init 
198  */
199 NETCP_CFG_MACIF_T  netcp_cfgCreateMacInterface(
200                   NETAPI_T  h,     //
201                   uint8_t *p_mac, //mac address associated with interface
202                   int iface_no, //0,1, ..
203                   int switch_port,//0=don't care, 1=switch port 1, 2=switch port 2 , ..
204                   NETCP_CFG_ROUTE_HANDLE_T  route, //NULL to use default
205                   NETCP_CFG_VLAN_T  vlan,  //future
206                   int state,  //0=down, 1=up  //FUTURE
207                   int * err
208                   );
210 /*****************************************************************
211  * Add IP address/qualifier to MAC interface 
212  ****************************************************************/
213 /*
214 *  @brief  API attaches an IP adderess and qualifier to a MAC interface 
215  *
216  *  @details This api is used to add an IP address to a MAC interface along
217  *           with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
218  *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
219  *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables
220  *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
221  * Note: An IP address must be attached to enable NETCP Recevie Checksum offload feature
222  *  @param[in]  @ref NETAPI_T: NETAPI instance
223  *  @param[in]  int : interface number (0,1,..)
224  *  @param[in]  @ref nwal_IpType : type of IP address (V4 for V6) 
225  *  @oaram[in]  @ref nwalIpAddr_t : ip_address
226  *  @param[in]  @ref nwalIpOpt_t : ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
227  *                  diffserv category for example
228  *  @param[in]  @ref NETCP_CFG_ROUTE_HANDLE_T : [future] handle of a created route or NULL to use internal default route 
229  *  @param[out] int * err:  pointer to error return
230  *  @retval     @ref NETCP_CFG_IP_T : returned AppID for attached rule. This is returned in RX meta data for
231  *              packets matching this rule and no other.
232  *  @pre       @ref netapi_init , @ref netcp_cfgAddMac 
233  */
234 NETCP_CFG_IP_T  netcp_cfgAddIp(
235                   NETAPI_T  h,
236                   int  iface_no,
237                   nwal_IpType ipType,
238                   nwalIpAddr_t  * ip_addr,
239                   nwalIpOpt_t * ip_qualifiers,
240                   NETCP_CFG_ROUTE_HANDLE_T  route,  //NULL for default
241                   int * err
242                   );
243 #define netcp_addIp netcp_cfgAddIp //oops
245 /*------------------classification API-------------------*/
247 //handle to installed classifier returned by API.  Pkts matching
248 //this classifier will have meta data with this tag.  Also used
249 //to delete classifier
250 typedef uint32_t NETCP_CFG_CLASS_T;  
252 //classifier L4 type  (L2,L3 implied by iface, ip)
253 typedef struct NETCP_CFG_CLASS_L4_Tag
255         //which mac interface pkt is from, 
256         int iface;
257         NETCP_CFG_IP_T  ip;
259         //L4  (port)
260         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
261         nwalAppProto_t   appProto;   //ports or equivalent
263 } NETCP_CFG_CLASS_L4_T;
265 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
266 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
268         //which mac interface pkt is from, 
269         int iface;
270         NETCP_CFG_IPSEC_POLICY_T  ip_policy;
272         //L4  (port)
273         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
274         nwalAppProto_t   appProto;   //ports or equivalent
276 } NETCP_CFG_CLASS_L4_IPSEC_T;
279 //classifier L3_L4 type (L2 implied by iface)
280 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
282         //which mac interface pkt is from, 
283         int iface;
285         //L3 -  iP address: IP type, destination addr, qualifiers
286         nwal_IpType ipType;
287         nwalIpAddr_t  * ip_addr;
288         nwalIpOpt_t * ip_qualifiers;
289         NETCP_CFG_ROUTE_HANDLE_T p_fail_route; //what to do if L3 matches but L4 fails AND L3 is a 
290                                               // new rule.(if exisitng rule, then existing fail
291                                               //route will be used.
292        
293         //L4  (port)
294         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
295         nwalAppProto_t   appProto;   //ports or equivalent
297 } NETCP_CFG_CLASS_L3_L4_T;
299 //classifier
300 typedef struct NETCP_CFG_CLASSIFIER_Tag
302         int classType;
303 #define NETCP_CFG_CLASS_TYPE_L4  0
304 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
305         union
306         {
307                 NETCP_CFG_CLASS_L3_L4_T  c_l3_l4;
308                 NETCP_CFG_CLASS_L4_T  c_l4;
309                 NETCP_CFG_CLASS_L4_IPSEC_T  c_l4_ipsec;
310         } u;
312 } NETCP_CFG_CLASSIFIER_T;
314 //Instert a classifier.
315 NETCP_CFG_CLASS_T netcp_cfgAddClass(NETAPI_T h,
316                                     NETCP_CFG_CLASSIFIER_T *p_class,
317                                     NETCP_CFG_ROUTE_HANDLE_T p_route,
318                                     int action, int * err);
319 //delete classifier
320 void netcp_cfgDelClass(NETAPI_T h,
321                          NETCP_CFG_CLASS_T classId,
322                          int *err);
326 /***************************************************************************
327 ********************************STATS**************************************
328 **************************************************************************/
330 /*
331  *  @brief  This is the callback function that is used to return statistics from NETCP 
332  *
333  *  @details The application provides a callback function that NETAPI  uses to report statistics.
334 *    The request for stats is generated from the @ref netcp_cfgReqStats API.
335  *   Note: to receive ths stats callback, the @ref netapi_netcpPoll funcition must be called
336  *  @param[in]  @ref NETAPI_T: NETAPI instance
337  *  @param[in]  @ref paSysStats_t * : the PA (NETCP packet accelerator subsystem) statistics block 
338  *  @retval     none 
339  *  @pre       @ref netapi_init , @ref netapi_cfgReqStats, @ref netapi_netcpPoll
340  */
341 //stats CB
342 typedef void (*NETCP_CFG_STATS_CB)( NETAPI_T h, paSysStats_t* pPaStats);
345 //stats request
346 /*
347  *  @brief  API request statistics from NETCP 
348  *
349  *  @details This api is used to request a statistics from NETCP.  This will generate a stats request
350  *           command to NETCP. Sometime later, the statistics result will arrive and will be passed to 
351  *           the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
352  *       Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
353  *  @param[in]  @ref NETAPI_T: NETAPI instance
354  *  @param[in]  @ref NETCP_CFG_STATS_CB : the function to call with the resulting statistics block
355  *  @param[in]  int :  clear the stats in NETCP after the report (0=no, 1=yes)                                          
356  *  @param[out] int * err:  pointer to error return
357  *  @retval     none 
358  *  @pre       @ref netapi_init 
359  */
360 void netcp_cfgReqStats(NETAPI_T  h,  //NEAPI instance
361                        NETCP_CFG_STATS_CB c, //stats report callback function
362                        int doClear,   //0: don't clear, 1 clear
363                        int *err);
365 #endif