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"
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  * @def NETCP_DEFAULT_FLOW
78  *      This defines the NETCP default FLOW to be NULL.
79  */
80 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
83 /**
84  * @ingroup nwal_api_constants
85  * @brief  Handle to the default NETCP route.
86  * @details Application to use this handle to identify default NETCP route.
87  */
88 typedef void * NETCP_CFG_ROUTE_HANDLE_T;
90 /**
91  * @def NETCP_DEFAULT_ROUTE
92  *      This defines the NETCP default ROUTE to be NULL.
93  */
94 #define NETCP_DEFAULT_ROUTE  (NETCP_CFG_ROUTE_HANDLE_T*) NULL
97 /**
98  *  @ingroup netapi_structures
99  *  @brief NETCP application defined route information.
100  *
101  */
102 typedef struct NETCP_CFG_ROUTE_Tag
104    NETCP_CFG_FLOW_T * p_flow;   /**< NULL or NETCP_DEFAULT_FLOW for default flow, @ref NETCP_CFG_FLOW_T */
105    PKTIO_HANDLE_T * p_dest_q;/**<NULL for default destination queue */
106 } NETCP_CFG_ROUTE_T;
108 /**
109  * @ingroup netapi_constants
110  * @def NETCP_CFG_ACTION_DISCARD
111  *      This defines the NETCP action to discard packet.
112  */
113 #define NETCP_CFG_ACTION_DISCARD 0
114 /**
115  * @ingroup netapi_constants
116  * @def  NETCP_CFG_ACTION_CONTINUE
117  *      This defines the NETCP action to pass packet ono the next classifier
118  */
119 #define NETCP_CFG_ACTION_CONTINUE 1
120 /**
121  * @ingroup netapi_constants
122  * @def NETCP_CFG_ACTION_TO_SW
123  *      This defines the NETCP action to pass packet to User space application
124  */
125 #define NETCP_CFG_ACTION_TO_SW    2
128 /**
129  * @ingroup nwal_api_constants
130  * @brief  Handle to the default NETCP route.
131  * @details Application to use this handle to identify default NETCP route.
132  */
133 typedef void * NETCP_CFG_VLAN_T;
135 /**
136  * @ingroup nwal_api_constants
137  * @brief  AppID for MAC interface
138  */
139 typedef uint32_t NETCP_CFG_MACIF_T;
141 /**
142  * @ingroup nwal_api_constants
143  * @brief AppID for IP interface
144  */
145 typedef uint32_t NETCP_CFG_IP_T;
149 /**
150  * @ingroup nwal_api_constants
151  * @brief This define is used to identify the application id associated with a created SA
152  */
153 typedef uint32_t NETCP_CFG_SA_T;
156 /**
157  * @ingroup nwal_api_constants
158  * @brief AppId used to identify NETCP IPSEC policy
159  */
160 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
163 /**
164  * @ingroup nwal_api_constants
165  * @def NETCP_CFG_NO_INTERFACE
166  *      This define is to be used in AddIp, AddClassifier to indicate any MAC address.
167  */
168 #define NETCP_CFG_NO_INTERFACE 0xff
172 /**
173  * @note  APPIDs are present in RX packet meta data and tell "how far the packet got
174  * through the classification rules of NETCP 
175  * APPID is 32 bits:
176  * bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
177  * bits 23-8  = identifier (depends on match stage)
178  * bits  7-0  = logical mac interface
179 */
181 /**
182  * @ingroup netapi_constants
183  * @def NETAPI_NETCP_MATCH_GENERIC_MAC
184  *      This define is used to indicate that apacket matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.  
185  *      Packet did not match any other rule
186  */
187 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000  //lower byte==interface
189 /**
190  * @ingroup netapi_constants
191  * @def NETAPI_NETCP_MATCH_GENERIC_IP
192  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
193  *      packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
194  *      is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
195  */
196 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000  //lower byte==interface
199 /**
200  * @ingroup netapi_constants
201  * @def NETAPI_NETCP_MATCH_CLASS
202  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
203  *      packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
204  *      the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
205  *      Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
206  *      give the ID of the classifier . Packet did not match any other rule
207  */
208 #define NETAPI_NETCP_MATCH_CLASS        0x80000000  //FULL MATCH or' in classifier (16 bits), lower byte==interface
210 /**
211  * @ingroup netapi_constants
212  * @def NETAPI_NETCP_MATCH_CLASS_L3
213  *      This define is used to indicate that a  packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
214  *      packet matched a general IP rule added as part of a classifier.  But it not match a
215  *      L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
216  *      not applicable
217  */
218 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000  //MATCHED L3 but not L4.  lower byte==interface
220 /**
221  * @ingroup netapi_constants
222  * @def NETAPI_NETCP_MATCH_IPSEC
223  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
224  *      packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
225  *      bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
226  */
227 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
229 /**
230  * @ingroup netapi_constants
231  * @def NETAPI_NETCP_MATCH_IPSEC_POLICY
232  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
233  *      packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
234  *      a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
235  *      bytes 3-2 of APPID.  Packet did not match any other rule 
236  */
237 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000  //lower byte==interface, Or' in SA id (16 bits)
243 /**
244  *  @ingroup netapi_cfg_functions
245  *  @brief netcp_cfgAddFlow   API to add a flow
246  * 
247  *  @details This api is used to add a flow
248  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
249  *  @param[in]  n    number of Pktlib_HeapHandle
250  *  @param[in]  handles[]   Handles to Pktlib_HeapHandle
251  *  @param[in]  sizes[]     must be <= heap corresponding heap size-recv_offset-any desired tail room
252  *  @param[in]  recv_offset   bytes to save in front of packet
253  *  @param[out] err     pointer to error return
254  *  @retval     NETCP flow handle, @ref NETCP_CFG_FLOW_HANDLE_T
255  *  @pre       @ref netapi_init
256  */
257 NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T h,
258                                             int n, 
259                                             Pktlib_HeapHandle handles[],
260                                             int sizes[],
261                                             int recv_offset,
262                                             int * err );
265 /**
266  *  @ingroup netapi_cfg_functions
267  *  @brief netcp_cfgDelFlow   API to delete a flow
268  * 
269  *  @details This api is used to delete a flow
270  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
271  *  @param[in]  p    handle to NETCP  flow
272  *  @param[out] err     pointer to error return
273  *  @retval     none
274  *  @pre       @ref netapi_init, netcp_cfgAddFlow
275  */
276 void netcp_cfgDelFlow(NETAPI_T h ,
277                                             NETCP_CFG_FLOW_HANDLE_T p ,
278                                             int * err);
280 /**
281  *  @ingroup netapi_cfg_functions
282  *  @brief netcp_cfgDelMac   API to delete MAC  interface
283  * 
284  *  @details This api is used to delete a MAC interface
285  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
286  *  @param[in]  iface_no    interface number (0,1,..)
287  *  @param[out] err     pointer to error return
288  *  @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
289  *  @pre       @ref netapi_init , @ref netcp_cfgCreateMacInterface 
290  */
291 void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
295 /**
296  *  @ingroup netapi_cfg_functions
297  *  @brief  API attaches an IP adderess and qualifier to a MAC interface
298  * 
299  *  @details This api is used to add an IP address to a MAC interface along
300  *            with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
301  *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
302  *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables
303  *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
304  *            Note: An IP address must be attached to enable NETCP receive Checksum offload feature
305  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
306  *  @param[in]  iface_no    interface number (0,1,..)
307  *  @param[in]  ipType  type of IP address (V4 for V6)
308  *  @param[in]  ip_addr      ip_address
309  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
310  *                  diffserv category for example.
311  *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
312  *  @param[out] err     pointer to error return
313  *  @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
314  *  @pre       @ref netapi_init
315  */
316 NETCP_CFG_IP_T  netcp_cfgAddIp(
317                   NETAPI_T  h,
318                   int  iface_no,
319                   nwal_IpType ipType,
320                   nwalIpAddr_t  * ip_addr,
321                   nwalIpOpt_t * ip_qualifiers,
322                   NETCP_CFG_ROUTE_HANDLE_T  route,
323                   int * err
324                   );
326 /**
327  *  @ingroup netapi_cfg_functions
328  *  @brief netcp_cfgDelIp   API to delete IP interface
329  * 
330  *  @details This api is used to delete an IP interface
331  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
332  *  @param[in]  iface_no    interface number (0,1,..)
333  *  @param[in]  ipType  type of IP address (V4 for V6)
334  *  @param[in]  ip_addr      ip_address
335  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
336  *                  diffserv category for example.
337  *  @param[in]  ip_rule_id      @ref NETCP_CFG_IP_T
338  *  @param[out] err     pointer to error return
339  *  @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
340  *  @pre       @ref netapi_init , @ref netcp_cfgAddIp
341  */
342 void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
343                   nwalIpAddr_t  * ip_addr,
344                   nwalIpOpt_t * ip_qualifiers, 
345                   NETCP_CFG_IP_T  ip_rule_id,
346                   int *err);
350 /**
351  *  @ingroup netapi_cfg_functions
352  *  @brief netcp_cfgCreateMacInterface  API to create a MAC interface
353  * 
354  *  @details This api is used to create a MAC interface.
355  *      Once it is created, the MAC interface can be used to receive packets. The API
356  *      adds a rule to the NETCP 1st level lookup tables to route all packets with destination
357  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netcp_cfgAddIp) to
358  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
359  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
360  *      Note: The internal SOC switch must be "taught" that this mac
361  *      address is present by transmitting a packet with destination mac = this interface mac address.
362  *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
363  *  @param[in]  p_mac   pointer to 6 byte MAC address for interface
364  *  @param[in]  iface_no    interface number (0,1,..) 
365  *  @param[in]  switch_port     (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported] 
366  *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
367  *  @param[in]  vlan    [future[ vlan configuration . Set to NULL, @ref NETCP_CFG_VLAN_T
368  *  @param[in]  state   [future] interface state (0=down, 1= up)
369  *  @param[out] err     pointer to error return
370  *  @retval     returns AppID for interface (this is returned in meta data for received packets matching this rule an no others, @ref NETCP_CFG_MACIF_T
371  *  @pre       @ref netapi_init 
372  */
373 NETCP_CFG_MACIF_T  netcp_cfgCreateMacInterface(
374                     NETAPI_T  h,     
375                     uint8_t *p_mac, 
376                     int iface_no,
377                     int switch_port,
378                     NETCP_CFG_ROUTE_HANDLE_T  route,
379                     NETCP_CFG_VLAN_T  vlan,
380                     int state,
381                     int * err
382 );
385 /**
386  * @brief This defines handle to installed classifier returned by API.  Pkts matching this classifier will have meta data with this tag.
387  *  Also used to delete classifier
388  */
389 typedef uint32_t NETCP_CFG_CLASS_T;  
392 /**
393  *  @ingroup netapi_structures
394  *  @brief NETAPI Class L4 Configuration
395  *
396  *  @details This structure contains Class L4 Configuration. L2,L3 implied by iface, ip
397  */
398 typedef struct NETCP_CFG_CLASS_L4_Tag
400     int             iface;      /**< Indicates which MAC interface packet is from */
401     NETCP_CFG_IP_T  ip;         /**< @ref NETCP_CFG_IP_T */
402     nwal_appProtoType_t proto;   /**< L4 proto (-1 for don't care)*/
403     nwalAppProto_t   appProto;   /**< Ports or equivalent */
405 } NETCP_CFG_CLASS_L4_T;
408 /**
409  *  @ingroup netapi_structures
410  *  @brief NETAPI Classifier L4 plus IPSEC policy configuration
411  *
412  *  @details This structure contains Class L4 plus IPSEC policy configuration. L2,L3 implied by iface, ip
413  */
414 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
415 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
417     int             iface;      /**< Indicates which MAC interface packet is from */
418     NETCP_CFG_IPSEC_POLICY_T  ip_policy; /**< IPSEC policy configuration */
419     nwal_appProtoType_t proto;   /**< L4 proto (-1 for don't care)*/
420     nwalAppProto_t   appProto;   /**< Ports or equivalent */
422 } NETCP_CFG_CLASS_L4_IPSEC_T;
427 /**
428  *  @ingroup netapi_structures
429  *  @brief NETAPI Classifier L4/L3 configuration
430  *
431  *  @details This structure contains Class L4 and Class L3 configuration. L2 implied by iface
432  */
433 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
435     int             iface;      /**< Indicates which MAC interface packet is from */
436     nwal_IpType ipType;         /**< IP address type, IPV4 or IPV6 */
437     nwalIpAddr_t  * ip_addr;    /**< IP addres */
438     nwalIpOpt_t * ip_qualifiers;/**< IP address qualifiers */
439     NETCP_CFG_ROUTE_HANDLE_T p_fail_route; /**< What to do if L3 matches but L4 fails AND L3 is a 
440                                             * new rule.(if exisitng rule, then existing fail
441                                             *route will be used. */
442     nwal_appProtoType_t proto;   /**< L4 proto (-1 for don't care)*/
443     nwalAppProto_t   appProto;   /**< Ports or equivalent */
444 } NETCP_CFG_CLASS_L3_L4_T;
446 /**
447  *  @ingroup netapi_structures
448  *  @brief NETAPI Classifier configuration
449  *
450  *  @details This structure contains the NETAPI classifer configuration
451  */
452 typedef struct NETCP_CFG_CLASSIFIER_Tag
454     int classType;              /**< Classifier type */
455 /**
456  * @def NETCP_CFG_CLASS_TYPE_L4
457  *      This defines classifier type to be Class L4
458  */
459 #define NETCP_CFG_CLASS_TYPE_L4  0
461 /**
462  * @def NETCP_CFG_CLASS_TYPE_L3_L4
463  *      This defines classifier type to be Class L4 and L3
464  */
465 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
466      union
467     {
468         NETCP_CFG_CLASS_L3_L4_T     c_l3_l4;    /**< @ref NETCP_CFG_CLASS_L3_L4_T */
469         NETCP_CFG_CLASS_L4_T        c_l4;       /**< @ref NETCP_CFG_CLASS_L4_T */
470         NETCP_CFG_CLASS_L4_IPSEC_T  c_l4_ipsec; /**< @ref NETCP_CFG_CLASS_L4_IPSEC_T */
471     } u;                                        /**< union for classifier type configuration structure */
472 } NETCP_CFG_CLASSIFIER_T;
476 /**
477  *  @ingroup netapi_cfg_functions
478  *  @brief netcp_cfgAddClass   API can be used to route a packet flow to a specific PKTIO channel
479  * 
480  *  @details This api can be used to route a packet flow to a particular PktIO channel, use a specific
481  *  pktLib heap, and/or have NetCP attach a tag (classifier id) to the incoming packet.
482  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
483  *  @param[in]  p_class
484  *  @param[in]  p_route
485  * @param[in]  action
486  *  @param[out] err     pointer to error return
487  *  @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
488  *  @pre       @ref netapi_init
489  */NETCP_CFG_CLASS_T netcp_cfgAddClass(NETAPI_T h,
490                                     NETCP_CFG_CLASSIFIER_T *p_class,
491                                     NETCP_CFG_ROUTE_HANDLE_T p_route,
492                                     int action,
493                                     int * err);
497 /**
498  *  @ingroup netapi_cfg_functions
499  *  @brief netcp_cfgDelClass   API can be used to delete a preconfigured classifier
500  * 
501  *  @details This API can be used to delete a preconfigured classifier
502  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
503  *  @param[in]  classId
504  *  @param[out] err     pointer to error return
505  *  @retval     none
506  *  @pre       @ref netapi_init, @ref netcp_cfgAddClass
507  */
508 void netcp_cfgDelClass(NETAPI_T h,
509                        NETCP_CFG_CLASS_T classId,
510                        int *err);
513 /**
514  *  @ingroup netapi_cb_functions
515  *  @brief NETCP_CFG_STATS_CB   Callback function that is used to return statistics from NETCP
516  * 
517  *  @details The application provides a callback function that NETAPI  uses to report statistics.
518  *  The request for stats is generated from the @ref netcp_cfgReqStats API.
519  *  Note: to receive ths stats callback, the @ref netapi_netcpPoll funcition must be called
520  *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
521  *  @param[out]  pPaStats    the PA (NETCP packet accelerator subsystem) statistics block 
522  *  @retval     none 
523  *  @pre       @ref netapi_init , @ref netcp_cfgReqStats, @ref netapi_netcpPoll
524  */
525 typedef void (*NETCP_CFG_STATS_CB)(NETAPI_T h, 
526                                    paSysStats_t* pPaStats);
528 /**
529  *  @ingroup netapi_cfg_functions
530  *  @brief netcp_cfgReqStats   API to request statistics from NETCP
531  * 
532  *  @details This api is used to request a statistics from NETCP.  This will generate a stats request
533  *  command to NETCP. Sometime later, the statistics result will arrive and will be passed to 
534  *  the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
535  *  Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
536  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
537  *  @param[in]  cb   the callback function to invoke with the resulting statistics block, @ref NETCP_CFG_STATS_CB
538  *  @param[in]  doClear     clear the stats in NETCP after the report (0=no, 1=yes) 
539  *  @param[out] err     pointer to error return
540  *  @retval     none 
541  *  @pre       @ref netapi_init 
542  */
543 void netcp_cfgReqStats(NETAPI_T  h,
544                        NETCP_CFG_STATS_CB cb,
545                        int doClear,
546                        int *err);
550 #endif