Doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / netcp_cfg.h
1 /******************************************************************************
2  * FILE PURPOSE:  netapi NETCP configuration API header file
3  ******************************************************************************
4  * FILE NAME:   netcp_cfg.h
5  *
6  * DESCRIPTION:netapi NETCP configuration API header  file  for user space transport library
7  *
8  * REVISION HISTORY:
9  *
10  *  Copyright (c) Texas Instruments Incorporated 2010-2011
11  *
12  *  Redistribution and use in source and binary forms, with or without
13  *  modification, are permitted provided that the following conditions
14  *  are met:
15  *
16  *    Redistributions of source code must retain the above copyright
17  *    notice, this list of conditions and the following disclaimer.
18  *
19  *    Redistributions in binary form must reproduce the above copyright
20  *    notice, this list of conditions and the following disclaimer in the
21  *    documentation and/or other materials provided with the
22  *    distribution.
23  *
24  *    Neither the name of Texas Instruments Incorporated nor the names of
25  *    its contributors may be used to endorse or promote products derived
26  *    from this software without specific prior written permission.
27  *
28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39  *
40  */
41 /* ============================================================= */
43 /**
44  *   @file netcp_cfg.h
45  *   @brief Netapi NETCP configuration API header  file for user space transport library
46  */
50 #ifndef __NETCP_CFG__H
51 #define __NETCP_CFG__H
53 #include "netapi.h"
54 #include "ti/drv/pa/pa.h"
55 #include "ti/runtime/pktlib/pktlib.h"
57 //NETCP FLOW
58 /**
59  *  @ingroup netapi_structures
60  *  @brief CPPI flow ID for default case, use NETCP_DEFAULT_FLOW
61  */
62 typedef struct NETCP_CFG_FLOW_Tag
63 {
64     int flowid;         /**< flow id*/
65 } NETCP_CFG_FLOW_T;
69 /**
70  * @ingroup netapi_constants
71  * @brief  This defines the handle to NETCP configuration flow.
72  */
73 typedef void *  NETCP_CFG_FLOW_HANDLE_T;
75 /**
76  * @ingroup netapi_constants
77  * @brief  This defines the NETCP default FLOW to be NULL.
78  */
79 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
82 /**
83  * @ingroup nwal_api_constants
84  * @brief  Handle to the default NETCP route.
85  * @details Application to use this handle to identify default NETCP route.
86  */
87 typedef void * NETCP_CFG_ROUTE_HANDLE_T;
89 /**
90  * @brief This defines the NETCP default ROUTE to be NULL.
91  */
92 #define NETCP_DEFAULT_ROUTE  (NETCP_CFG_ROUTE_HANDLE_T*) NULL
95 /**
96  *  @ingroup netapi_structures
97  *  @brief NETCP application defined route information.
98  *
99  */
100 typedef struct NETCP_CFG_ROUTE_Tag
102    NETCP_CFG_FLOW_T * p_flow;   /**< NULL or NETCP_DEFAULT_FLOW for default flow, @ref NETCP_CFG_FLOW_T */
103    PKTIO_HANDLE_T * p_dest_q;/**<NULL for default destination queue */
104 } NETCP_CFG_ROUTE_T;
106 /**
107  * @ingroup netapi_constants
108  * @brief This defines the NETCP action to discard packet.
109  */
110 #define NETCP_CFG_ACTION_DISCARD 0
111 /**
112  * @ingroup netapi_constants
113  * @brief This defines the NETCP action to pass packet ono the next classifier
114  */
115 #define NETCP_CFG_ACTION_CONTINUE 1
116 /**
117  * @ingroup netapi_constants
118  * @brief This defines the NETCP action to pass packet to User space application
119  */
120 #define NETCP_CFG_ACTION_TO_SW    2
123 /**
124  * @ingroup nwal_api_constants
125  * @brief  Handle to the default NETCP route.
126  * @details Application to use this handle to identify default NETCP route.
127  */
128 typedef void * NETCP_CFG_VLAN_T;
130 /**
131  * @ingroup nwal_api_constants
132  * @brief  AppID for MAC interface
133  */
134 typedef uint32_t NETCP_CFG_MACIF_T;
136 /**
137  * @ingroup nwal_api_constants
138  * @brief AppID for IP interface
139  */
140 typedef uint32_t NETCP_CFG_IP_T;
144 /**
145  * @ingroup nwal_api_constants
146  * @brief This define is used to identify the application id associated with a created SA
147  */
148 typedef uint32_t NETCP_CFG_SA_T;
151 /**
152  * @ingroup nwal_api_constants
153  * @brief AppId used to identify NETCP IPSEC policy
154  */
155 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
158 /**
159  * @ingroup nwal_api_constants
160  * @brief This define is to be used in AddIp, AddClassifier to indicate any MAC address.
161  */
162 #define NETCP_CFG_NO_INTERFACE 0xff
166 /**
167  * @note  APPIDs are present in RX packet meta data and tell "how far the packet got
168  * through the classification rules of NETCP 
169  * APPID is 32 bits:
170  * bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
171  * bits 23-8  = identifier (depends on match stage)
172  * bits  7-0  = logical mac interface
173 */
175 /**
176  * @ingroup netapi_constants
177  * @brief This define is used to indicate that apacket matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.  
178  * Packet did not match any other rule
179  */
180 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000  //lower byte==interface
182 /**
183  * @ingroup netapi_constants
184  * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
185  * packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
186  * is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
187  */
188 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000  //lower byte==interface
191 /**
192  * @ingroup netapi_constants
193  * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
194  * packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
195  * the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
196  * Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
197  * give the ID of the classifier . Packet did not match any other rule
198  */
199 #define NETAPI_NETCP_MATCH_CLASS        0x80000000  //FULL MATCH or' in classifier (16 bits), lower byte==interface
201 /**
202  * @ingroup netapi_constants
203  * @brief This define is used to indicate that a  packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
204  * packet matched a general IP rule added as part of a classifier.  But it not match a
205  * L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
206  * not applicable
207  */
208 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000  //MATCHED L3 but not L4.  lower byte==interface
210 /**
211  * @ingroup netapi_constants
212  * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
213  * packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
214  * bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
215  */
216 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
218 /**
219  * @ingroup netapi_constants
220  * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
221  * packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
222  * a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
223  * bytes 3-2 of APPID.  Packet did not match any other rule 
224  */
225 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000  //lower byte==interface, Or' in SA id (16 bits)
231 /**
232  *  @ingroup netapi_cfg_functions
233  *  @brief netcp_cfgAddFlow   API to add a flow
234  * 
235  *  @details This api is used to add a flow
236  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
237  *  @param[in]  n    number of Pktlib_HeapHandle
238  *  @param[in]  handles[]   handles to Pktlib_HeapHandle
239  *  @param[in]  sizes[]     must be<= heap corresponding heap size-recv_offset-any desired tail room
240  *  @param[in]  recv_offset   bytes to save in front of packet
241  *  @param[out] err     pointer to error return
242  *  @retval     NETCP flow handle, @ref NETCP_CFG_FLOW_HANDLE_T
243  *  @pre       @ref netapi_init
244  */
245 NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T h,
246                                             int n, 
247                                             Pktlib_HeapHandle handles[],
248                                             int sizes[],
249                                             int recv_offset,
250                                             int * err );
253 /**
254  *  @ingroup netapi_cfg_functions
255  *  @brief netcp_cfgDelFlow   API to delete a flow
256  * 
257  *  @details This api is used to delete a flow
258  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
259  *  @param[in]  p    handle to NETCP  flow
260  *  @param[out] err     pointer to error return
261  *  @retval     none
262  *  @pre       @ref netapi_init, netcp_cfgAddFlow
263  */
264 void netcp_cfgDelFlow(NETAPI_T h ,
265                                             NETCP_CFG_FLOW_HANDLE_T p ,
266                                             int * err);
268 /**
269  *  @ingroup netapi_cfg_functions
270  *  @brief netcp_cfgDelMac   API to delete MAC  interface
271  * 
272  *  @details This api is used to delete a MAC interface
273  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
274  *  @param[in]  iface_no    interface number (0,1,..)
275  *  @param[out] err     pointer to error return
276  *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
277  *  @pre       @ref netapi_init , @ref netcp_cfgAddMac 
278  */
279 void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
283 /**
284  *  @ingroup netapi_cfg_functions
285  *  @brief  API attaches an IP adderess and qualifier to a MAC interface
286  * 
287  *  @details This api is used to add an IP address to a MAC interface along
288  *            with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
289  *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
290  *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables
291  *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
292  *            Note: An IP address must be attached to enable NETCP receive Checksum offload feature
293  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
294  *  @param[in]  iface_no    interface number (0,1,..)
295  *  @param[in]  ipType  type of IP address (V4 for V6), @ref nwal_IpType
296  *  @param[in]  ip_addr      ip_address, @ref nwalIpAddr_t
297  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
298  *                  diffserv category for example. @ref nwalIpOpt_t
299  *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
300  *  @param[out] err     pointer to error return
301  *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
302  *  @pre       @ref netapi_init , @ref netcp_cfgAddMac 
303  */
304 NETCP_CFG_IP_T  netcp_cfgAddIp(
305                   NETAPI_T  h,
306                   int  iface_no,
307                   nwal_IpType ipType,
308                   nwalIpAddr_t  * ip_addr,
309                   nwalIpOpt_t * ip_qualifiers,
310                   NETCP_CFG_ROUTE_HANDLE_T  route,
311                   int * err
312                   );
314 #define netcp_addIp netcp_cfgAddIp //oops
316 /**
317  *  @ingroup netapi_cfg_functions
318  *  @brief netcp_cfgDelIp   API to delete IP interface
319  * 
320  *  @details This api is used to delete an IP interface
321  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
322  *  @param[in]  iface_no    interface number (0,1,..)
323  *  @param[in]  ipType  type of IP address (V4 for V6), @ref nwal_IpType
324  *  @param[in]  ip_addr      ip_address, @ref nwalIpAddr_t
325  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
326  *                  diffserv category for example. @ref nwalIpOpt_t
327  *  @param[in]  ip_rule_id      @ref NETCP_CFG_IP_T
328  *  @param[out] err     pointer to error return
329  *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
330  *  @pre       @ref netapi_init , @ref netcp_cfgAddIp
331  */
332 void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
333                   nwalIpAddr_t  * ip_addr,
334                   nwalIpOpt_t * ip_qualifiers, 
335                   NETCP_CFG_IP_T  ip_rule_id,
336                   int *err);
340 /**
341  *  @ingroup netapi_cfg_functions
342  *  @brief netcp_cfgCreateMacInterface  API to create a MAC interface
343  * 
344  *  @details This api is used to create a MAC interface.
345  *      Once it is created, the MAC interface can be used to receive packets. The API
346  *      adds a rule to the NETCP 1st level lookup tables to route all packets with destination
347  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netcp_cfgAddIp) to
348  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
349  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
350  *      Note: The internal SOC switch must be "taught" that this mac
351  *      address is present by transmitting a packet with destination mac = this interface mac address.
352  *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
353  *  @param[in]  p_mac   pointer to 6 byte MAC address for interface
354  *  @param[in]  iface_no    interface number (0,1,..) 
355  *  @param[in]  switch_port     (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported] 
356  *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
357  *  @param[in]  vlan    [future[ vlan configuration . Set to NULL, @ref NETCP_CFG_VLAN_T
358  *  @param[in]  state   [future] interface state (0=down, 1= up)
359  *  @param[out] err     pointer to error return
360  *  @retval     returns AppID for interface (this is returned in meta data for received packets matching this rule an no others) @ref @ref NETCP_CFG_MACIF_T
361  *  @pre       @ref netapi_init 
362  */
363 NETCP_CFG_MACIF_T  netcp_cfgCreateMacInterface(
364                   NETAPI_T  h,     
365                   uint8_t *p_mac, 
366                   int iface_no,
367                   int switch_port,
368                   NETCP_CFG_ROUTE_HANDLE_T  route,
369                   NETCP_CFG_VLAN_T  vlan,
370                   int state,
371                   int * err
372                   );
375 /**
376  * @brief This defines handle to installed classifier returned by API.  Pkts matching this classifier will have meta data with this tag.
377  *  Also used to delete classifier
378  */
379 typedef uint32_t NETCP_CFG_CLASS_T;  
383 //classifier L4 type  (L2,L3 implied by iface, ip)
384 typedef struct NETCP_CFG_CLASS_L4_Tag
386         //which mac interface pkt is from, 
387         int iface;
388         NETCP_CFG_IP_T  ip;
390         //L4  (port)
391         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
392         nwalAppProto_t   appProto;   //ports or equivalent
394 } NETCP_CFG_CLASS_L4_T;
396 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
397 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
399         //which mac interface pkt is from, 
400         int iface;
401         NETCP_CFG_IPSEC_POLICY_T  ip_policy;
403         //L4  (port)
404         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
405         nwalAppProto_t   appProto;   //ports or equivalent
407 } NETCP_CFG_CLASS_L4_IPSEC_T;
410 //classifier L3_L4 type (L2 implied by iface)
411 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
413         //which mac interface pkt is from, 
414         int iface;
416         //L3 -  iP address: IP type, destination addr, qualifiers
417         nwal_IpType ipType;
418         nwalIpAddr_t  * ip_addr;
419         nwalIpOpt_t * ip_qualifiers;
420         NETCP_CFG_ROUTE_HANDLE_T p_fail_route; //what to do if L3 matches but L4 fails AND L3 is a 
421                                               // new rule.(if exisitng rule, then existing fail
422                                               //route will be used.
423        
424         //L4  (port)
425         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
426         nwalAppProto_t   appProto;   //ports or equivalent
428 } NETCP_CFG_CLASS_L3_L4_T;
430 //classifier
431 typedef struct NETCP_CFG_CLASSIFIER_Tag
433         int classType;
434 #define NETCP_CFG_CLASS_TYPE_L4  0
435 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
436         union
437         {
438                 NETCP_CFG_CLASS_L3_L4_T  c_l3_l4;
439                 NETCP_CFG_CLASS_L4_T  c_l4;
440                 NETCP_CFG_CLASS_L4_IPSEC_T  c_l4_ipsec;
441         } u;
443 } NETCP_CFG_CLASSIFIER_T;
447 /**
448  *  @ingroup netapi_cfg_functions
449  *  @brief netcp_cfgAddClass   API can be used to route a packet flow to a specific PKTIO channel
450  * 
451  *  @details This api can be used to route a packet flow to a particular PktIO channel, use a specific
452  *  pktLib heap, and/or have NetCP attach a tag (classifier id) to the incoming packet.
453  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
454  *  @param[in]  p_class
455   *  @param[in]  p_route
456  *  @param[out] err     pointer to error return
457  *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
458  *  @pre       @ref netapi_init
459  */NETCP_CFG_CLASS_T netcp_cfgAddClass(NETAPI_T h,
460                                     NETCP_CFG_CLASSIFIER_T *p_class,
461                                     NETCP_CFG_ROUTE_HANDLE_T p_route,
462                                     int action, int * err);
466 /**
467  *  @ingroup netapi_cfg_functions
468  *  @brief netcp_cfgDelClass   API can be used to delete a preconfigured classifier
469  * 
470  *  @details This API can be used to delete a preconfigured classifier
471  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
472  *  @param[in]  classId
473  *  @param[out] err     pointer to error return
474  *  @retval     none
475  *  @pre       @ref netapi_init, @ref netcp_cfgAddClass
476  */
477 void netcp_cfgDelClass(NETAPI_T h,
478                          NETCP_CFG_CLASS_T classId,
479                          int *err);
483 /**
484  *  @ingroup netapi_cb_functions
485  *  @brief NETCP_CFG_STATS_CB   Callback function that is used to return statistics from NETCP
486  * 
487  *  @details The application provides a callback function that NETAPI  uses to report statistics.
488  *  The request for stats is generated from the @ref netcp_cfgReqStats API.
489  *  Note: to receive ths stats callback, the @ref netapi_netcpPoll funcition must be called
490  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
491  *  @param[out]  pPaStats    the PA (NETCP packet accelerator subsystem) statistics block 
492  *  @retval     none 
493  *  @pre       @ref netapi_init , @ref netapi_cfgReqStats, @ref netapi_netcpPoll
494  */
495 typedef void (*NETCP_CFG_STATS_CB)( NETAPI_T h, paSysStats_t* pPaStats);
500 /**
501  *  @ingroup netapi_cfg_functions
502  *  @brief netcp_cfgReqStats   API to request statistics from NETCP
503  * 
504 *  @details This api is used to request a statistics from NETCP.  This will generate a stats request
505  *  command to NETCP. Sometime later, the statistics result will arrive and will be passed to 
506  *  the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
507  *  Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
508  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
509  *  @param[in]  c   the callback function to invoke with the resulting statistics block, @ref NETCP_CFG_STATS_CB
510  *  @param[in]  doClear     clear the stats in NETCP after the report (0=no, 1=yes) 
511  *  @param[out] int * err:  pointer to error return
512  *  @retval     none 
513  *  @pre       @ref netapi_init 
514  */
515 void netcp_cfgReqStats(NETAPI_T  h,  //NEAPI instance
516                        NETCP_CFG_STATS_CB c, //stats report callback function
517                        int doClear,   //0: don't clear, 1 clear
518                        int *err);
520 #endif