SDOCM00113322: kernel RX UDP/TCP checksum offload to NETCP breaks user space tranport...
[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 2013
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 #ifdef __cplusplus
54 extern "C" {
55 #endif
57 //#include "netapi.h"
59 /**
60  *  @ingroup cfg_structures
61  *  @brief NETCP Flow ID configuaration informaation
62  *  @details A flow defines a set of free queues (pktlib heap) for hardware to use to get
63  *          free packet descriptor(s) and buffer(s) to use when receiving a packet. CPPI flow ID for
64  *          default case, use NETCP_DEFAULT_FLOW
65  */
66 typedef struct NETCP_CFG_FLOW_Tag
67 {
68     int flowid;         /**< flow id*/
69     int dma_engine;     /**< dma engine (QMSS, NETCP)*/
70 } NETCP_CFG_FLOW_T;
73 /**
74  *  @ingroup cfg_structures
75  *  @brief NETAPI configuration information
76  *
77  *  @details The parameters in this structure are used to configure NETAPI.
78  */
79 typedef struct NETAPI_CFG_Tag
80 {
81  int def_mem_size;                  /**<  Bytes of CMA memory we have allocated */
82  int def_flow_pkt_rx_offset;        /**<  Offset in pkt buffer for hw to start RX */
83  int def_max_descriptors;           /**<  Number of descriptors in system  (must be power of 2), 2^14 max */
84  int def_tot_descriptors_for_us;    /**<  Number of descriptors to create in our region (must be power of 2)*/
85  int def_heap_n_descriptors;        /**<  Number of descriptor plus buffers in default heap*/
86  int def_heap_n_zdescriptors;       /**<  Number of zero len descriptors in defaut heap*/
87  int def_heap_buf_size;             /**<  Size of buffers in default heap, max amount of area for packet data */
88  int def_heap_tailroom_size;        /**<  Size of tailroom in reserve */
89  int def_heap_extra_size;           /**<  Size of extra space at end of buffer */ 
90  int def_multi_process;             /**<  Flag to indicate if NETAPI init is for multi-process environment */
91  void *rmHandle;                    /**<  Optional: Resource Manager (RM) server handle to use RM for re                                                    souce allocations*/
92  int memoryRegion;                  /**<  Optional: Specify the descriptor memory region to be used,
93                                           must be a valid memory  region index
94                                           (0 to Maximum number of memory regions supported
95                                           Not used when using Resouce Manager(RM)as QMSS via RM will
96                                           return available Memory Region Id.
97                                           */
98  int start_index;                   /**<  Optional: Used to leave holes by configuring dummy regions which
99                                           can be later configured with actual values. May either be
100                                           specified by the user (for example, to select "internal" or
101                                           "external" linking RAM, or set to QMSS_START_INDEX_NOT_SPECIFIED,
102                                           QMSS_PARAM_NOT_SPECIFIED to have LLD/RM select a compatible startIndex
103                                           from anywhere with free indicies, or QMSS_START_INDEX_INTERNAL.
104                                           for internal linking RAM, QMSS_START_INDEX_EXTERNAL for external linking RAM. 
105                                           Not used when using Resouce Manager(RM)as QMSS via RM will
106                                           return available Memory Region Id and determine avialable start index.
107                                           */
108 }  NETAPI_CFG_T;
110 /* @note:
111    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
112    each descriptor attached to these buffers will have rigBufferLen of:
113       def_heap_buf_size.
114    for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.
115    for detault RX flow,  threshold (ie max # of bytes in buffer) will be:
116        def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
119  RX Packet from NetCP
121 Headroom [Application]     Packet [HW]                Tailroom [Application]    Extra Space [Application]
122 <-----------------------><--------------------------><------------------------><----------------------->
124 Cppi_HostDesc->origBufferLen
125 <----------------------------------------------------------------------------->
126 Cppi_HostDesc->origBuffPtr
128 \/
129 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
130 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size  |   Extra Size          |
131                         ^
132                         |
133                      Cppi_HostDesc->buffPtr
134 */
137 /**
138  * @ingroup cfg_constants
139  * @brief  This defines the handle to a NETCP configured Flow. A Flow is a set of pktlib heaps that h/w can use to obtain free packets.
140  */
141 typedef NETCP_CFG_FLOW_T* NETCP_CFG_FLOW_HANDLE_T;
143 /**
144  * @ingroup cfg_constants
145  * @def NETCP_DEFAULT_FLOW
146  * @brief This defines the default FLOW for NETCP to use.
147  * The default flow uses the default pktlib heap created by netapi_init; i.e.
148  * NETCP will allocate descriptors and buffers for received packets from this heap.
149  */
150 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T) NULL
154 /**
155  * @ingroup cfg_constants
156  * @def NETCP_DEFAULT_ROUTE
157  * @brief This defines the NETCP default route.  This route has NETCP send received packets to the default NETCP 
158  * pktio channel using descriptors and buffers from the default flow. The default route is created by netapi_init
159  */
160 #define NETCP_DEFAULT_ROUTE (NETCP_CFG_ROUTE_HANDLE_T) NULL
163 /**
164  *  @ingroup cfg_constants
165  *  @{
166  *
167  *  @name   Valid Parameter configuration for NETCP_CFG_ROUTE_T
168  *  @brief  Valid Parameter configuration
169  *
170  *  @details Valid Parameter to configure optional parameters.
171  */
172 /* @{ */
173 /**
174  *  @def  NETCP_CFG_VALID_PARAM_ROUTE_TYPE
175  *        Valid Route Type configuration
176  *
177  */
179 #define NETCP_CFG_VALID_PARAM_ROUTE_TYPE        0x01
180 /*  @}  */
181 /* @{ */
182 /**
183  *  @def  NETCP_CFG_VALID_PARAM_MATCH_ACTION_DEST
184  *        Valid Match Destination configuration present,
185  *        When set, NetCP to terminate packet at configured destination
186  *        if classification matches as specified by match_destination of
187  *        @NETCP_CFG_ROUTE_T
188  *
189  */
190 #define NETCP_CFG_VALID_PARAM_MATCH_ACTION_DEST        0x02
191 /*  @}  */
192 /* @{ */
193 /**
194  *  @def  NETCP_CFG_VALID_PARAM_FAIL_ACTION_DEST
195  *        Valid Fail Destination configuration present,
196  *        When set, NetCP to terminate packet at configured destination
197  *        if next route classification fails as specified by fail_destination of
198  *        @NETCP_CFG_ROUTE_T
199  *
200  */
201 #define NETCP_CFG_VALID_PARAM_FAIL_ACTION_DEST          0x04
202 /*  @}  */
203 /** @} */
207 /**
208  *  @ingroup cfg_structures
209  *  @brief NETCP application defined route information.
210  *  @details This structure is used to define a packet receive route.  A route consists of a 
211  *           flow where to get free descriptors and buffers to hold the packet, and a destination 
212  *           queue where to place the packet. Priority routing based on VLAN priority bits,
213  *           DSCP/TOS, and received input port is supported. In the case
214  *           of priority based routing, the PASS will forward the matchd packeed to the desired
215  *           queue which is equal to the base queue plus an offset. This offset is sepcififed
216  *           by the VLAN prioirty or DSCP/TOS value, or received input port.
217  *
218  */
219 typedef struct NETCP_CFG_ROUTE_Tag
221     uint32_t            valid_params;       /**< Specifies which route config params
222                                                  are valid */
223     NETCP_CFG_FLOW_T    *p_flow;            /**< NULL or NETCP_DEFAULT_FLOW for default
224                                               *flow,@ref NETCP_CFG_FLOW_T
225                                               */
226     PKTIO_HANDLE_T      *p_dest_q;          /**< NULL for default destination queue */
228     nwalRouteType_t     routeType;          /**< Optional: Routing priority,
229                                               *  @see nwal.h for nwalRouteType_t
230                                               */
231    uint16_t             egress_swith_port;  /* learned swithc port #, from ale_table */
232     uint16_t            match_destination;  /**< Optional: NetCP to terminate packet at specified destination 
233                                                   if classification matches
234                                                   @see nwal.h for nwal_matchAction_t*/
235     uint16_t            fail_destination;   /**< Optional: NetCP to terminate packet at specified destination 
236                                                   if next route classification match fails 
237                                                   @see nwal.h for nwal_failAction_t*/
239 } NETCP_CFG_ROUTE_T;
242 /**
243  * @ingroup cfg_constants
244  * @brief  Handle to a NETCP route.
245  * @details Application to use this handle to identify a NETCP route. A NETCP route defines the
246  *          pktio channel for packets received by NETCP
247  *    and the flow to use.
248  */
249 typedef NETCP_CFG_ROUTE_T* NETCP_CFG_ROUTE_HANDLE_T;
254 /**
255  * @ingroup cfg_constants
256  * @def NETCP_CFG_ACTION_DISCARD
257  *      This defines the NETCP action to discard packet.
258  */
259 #define NETCP_CFG_ACTION_DISCARD NWAL_MATCH_ACTION_DISCARD
260 /**
261  * @ingroup cfg_constants
262  * @def  NETCP_CFG_ACTION_CONTINUE
263  *      This defines the NETCP action to pass packet ono the next classifier
264  */
265 #define NETCP_CFG_ACTION_CONTINUE NWAL_MATCH_ACTION_CONTINUE_NEXT_ROUTE
266 /**
267  * @ingroup cfg_constants
268  * @def NETCP_CFG_ACTION_TO_SW
269  *      This defines the NETCP action to pass packet to User space application
270  */
271 #define NETCP_CFG_ACTION_TO_SW    NWAL_MATCH_ACTION_HOST
273 /**
274  * @ingroup cfg_constants
275  * @def NETCP_CFG_ALL_EXCEPTIONS
276  *      This defines NETCP configuration for all Exepction Packets.
277  */
278 #define NETCP_CFG_ALL_EXCEPTIONS 0xff
280 /**
281  * @ingroup cfg_constants
282  * @brief General APP_ID Type definition.
283  */
284 typedef uint32_t NETCP_CFG_APP_ID_T;
287 /**
288  * @ingroup cfg_constants
289  * @brief  Handle to NETCP VLAN configuration (FUTURE).
290  * @details Application to use this handle to identify a VLAN configuration.
291  */
292 typedef void * NETCP_CFG_VLAN_T;
294 /**
295  * @ingroup cfg_constants
296  * @brief  NETCP PA LLD handle associated with an SA
297  * @details Application to use this handle to identify a PA PLLD handle associated with an SA.
298  */
299 typedef void * NETCP_CFG_PA_HANDLE_T;
301 /**
302  * @ingroup cfg_constants
303  * @brief  NETCP SA LLD handle associated with an SA
304  * @details Application to use this handle to identify a SA LLD handle associated with an SA.
305  */
306 typedef void * NETCP_CFG_SA_HANDLE_T;
308 /**
309  * @ingroup cfg_constants
310  * @brief  AppID for packets matching a  MAC interface rule
311  */
312 typedef uint32_t NETCP_CFG_MACIF_T;
314 /**
315  * @ingroup cfg_constants
316  * @brief AppID for packets matching an IP interface rule
317  */
318 typedef uint32_t NETCP_CFG_IP_T;
320 /**
321  * @ingroup cfg_constants
322  * @brief This define is used to identify the application id associated with a created SA (IPSEC security association) rule
323  */
324 typedef uint32_t NETCP_CFG_SA_T;
327 /**
328  * @ingroup cfg_constants
329  * @brief AppId for packets matching an NETCP IPSEC policy rule
330  */
331 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
335 /**
336  * @ingroup cfg_constants
337  * @brief  AppID for packets being classified as  type exception.
338  */
339 typedef uint32_t NETCP_CFG_EXCEPTION_PKT_T;
341 /**
342  * @ingroup cfg_constants
343  *@brief This define is to be used in AddIp, AddClassifier, addSA, etc. to indicate that the rule can be bound to any MAC address.
344  */
345 #define NETCP_CFG_NO_INTERFACE 0xff
349 /**
350  * @note  APPIDs are present in RX packet meta data and tell "how far" the packet got
351  * through the classification rules of NETCP. 
352  * APPID is 32 bits:
353  * bits 31-24 = NETAPI_NETCP_MATCH_STAGE
354  * bits 23-8  = NETAPI_NETCP_MATCH_ID identifier 
355  * bits  7-0  = NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE logical mac interface
356 */
358 #define NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT 0 
359 #define NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK 0xFF
361 #define NETAPI_NETCP_MATCH_ID_SHIFT 8 
362 #define NETAPI_NETCP_MATCH_ID_MASK 0xFFFF
364 #define NETAPI_NETCP_MATCH_STAGE_SHIFT 24
365 #define NETAPI_NETCP_MATCH_STAGE_MASK 0xFF
368 /**
369  * @brief Helper function to get match stage associated with application ID.
370  */
371 #define netapi_cfgGetMatchStage(appid)  (((appid) >> NETAPI_NETCP_MATCH_STAGE_SHIFT) & NETAPI_NETCP_MATCH_STAGE_MASK)
373 /**
374  * @brief Helper function to get match id associated with application ID.
375  */
376 #define netapi_cfgGetMatchId(appid) (((appid) >> NETAPI_NETCP_MATCH_ID_SHIFT) & NETAPI_NETCP_MATCH_ID_MASK)
378 /**
379  * @brief Helper function to get logical match interface associated with application ID.
380  */
381 #define netapi_cfgGetMatchLogicalMacIface(appid) (((appid) >> NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT) & \
382                                                     NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK)
385 /**
386  * @ingroup cfg_constants
387  * @def NETAPI_NETCP_MATCH_GENERIC_MAC
388  *      This define is used for an APPID that indicates that a packet matched a MAC entry.
389  *      Logical MAC interface location:
390  *          Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and 
391  *          NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
392  *      Packet did not match any other rule.
393  */
394 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000
396 /**
397  * @ingroup cfg_constants
398  * @def NETAPI_NETCP_MATCH_GENERIC_IP
399  *      This define is used for an APPID that indicates that a packet matched a MAC entry.
400  *      Logical MAC interface location:
401  *          Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and 
402  *          NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
403  *       IP rule number for this interface location:
404  *          Refer to NETAPI_NETCP_MATCH_ID_SHIFT and 
405  *          NETAPI_NETCP_MATCH_ID_MASK.
406  *      Packet also matched a generic IP rule attached to that interface.
407  *      Packet did not match any other rule.
408  */
409 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000
411 /**
412  * @ingroup cfg_constants
413  * @def NETAPI_NETCP_MATCH_CLASS
414  *      This define is used for an APPID that indicates that a packet matched a MAC entry.
415  *      Logical MAC interface location:
416  *          Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and 
417  *          NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
418  *      Classifer ID location:
419  *          Refer to NETAPI_NETCP_MATCH_ID_SHIFT and 
420  *          NETAPI_NETCP_MATCH_ID_MASK.
421  *      Packet also matched a generic IP rule attached to 
422  *      that interface OR a general IP rule added as part of the classifier or it matched a combination
423  *      of ISPEC SA rule and a policy check.  In addition, packet matched a L4 port rule that was added 
424  *      as part of a classifer. Packet did not match any other rule.
425  */
426 #define NETAPI_NETCP_MATCH_CLASS        0x80000000
428 /**
429  * @ingroup cfg_constants
430  * @def NETAPI_NETCP_MATCH_CLASS_L3
431  *      This define is used for an APPID that indicates that a  packet matched a MAC entry.
432  *      Logical MAC interface location:
433  *          Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and 
434  *          NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
435  *      Packet also  matched a general IP rule added as part 
436  *      of a classifier.  But it not match a L4 port or any other rule. 
437  *      We cannot determine what classifer partially matched so Bytes 3-2 are not applicable
438  */
439 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000
441 /**
442  * @ingroup cfg_constants
443  * @def NETAPI_NETCP_MATCH_IPSEC
444  *      This define is used for an APPID that indicates that a packet matched a MAC entry.
445  *      Logical MAC interface location:
446  *          Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and 
447  *          NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
448  *      SA ID location:
449  *          Refer to NETAPI_NETCP_MATCH_ID_SHIFT and 
450  *          NETAPI_NETCP_MATCH_ID_MASK.
451  *      Packet also matched an IPSEC SA  rule (matched proto, destination ip and SPI).  
452  *      Packet did not match any other rule (so may have failed a policy check)
453  */
454 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  
457 /**
458  * @ingroup cfg_constants
459  * @def NETAPI_NETCP_MATCH_IPSEC_POLICY
460  *      This define is used for an APPID that indicates that a packet matched a MAC entry
461  *      Logical MAC interface location:
462  *          Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and 
463  *          NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
464  *      Packet also matched an IPSEC SA rule (matched proto, 
465  *      dest ip and SPI).  Packet also matched a POLICY RULE (this is a check of the inner IP).
466  *      IPSEC RX Policy ID location:
467  *          Refer to NETAPI_NETCP_MATCH_ID_SHIFT and 
468  *          NETAPI_NETCP_MATCH_ID_MASK.
469  *      Packet did not match any other rule 
470  */
471 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000  //lower byte==interface, Or' in SA id (16 bits)
473 /**
474  * @ingroup cfg_constants
475  * @def NETAPI_NETCP_CFG_MATCH_EXCEPTION
476  *      This define is used for an APPID that indicates that a packet is of type exception. 
477  *      Actual exception id is in byte 0 of APPID.
478  */
479 #define NETAPI_NETCP_CFG_MATCH_EXCEPTION     0x08000000
483 /**
484  *  @ingroup cfg_structures
485  *  @brief NETCP flow configuration information.
486  *  @details This structure is used to define key parameters for the receive flow to be created.
487  *           These include the flow index to use (or can be left un-specified), the dma_index
488  *           (specifying out of which CPPI DMA engine the flow should be allocated),
489  *           the receive offset (the byte offset into each buffer where received data should be placed),
490  *           and the drop policy for the DMA channel to use if there is no free buffer available (drop or block)
491  *
492  */
493 typedef struct NETCP_CFG_FLOW_CONFIG_Tag
495    int              flow_index;     /**< flow index to use or NETAPI_NETCP_FLOW_INDEX_ANY */
496 /**
497  * @def NETAPI_NETCP_FLOW_INDEX_ANY
498  * @ingroup cfg_constants
499  *      This define is used to let NETAPI pick the flow index to use(for flow_index field)
500  */
501 #define NETAPI_NETCP_FLOW_INDEX_ANY  CPPI_PARAM_NOT_SPECIFIED
503    int              dma_index;      /**< allocate flow out of which DMA */
504 /**
505  * @def NETAPI_DMA_INFRASTRUCTURE
506  * @ingroup cfg_constants
507  *      This define is used specify a flow in the QMSS CPPI DMA (for dma_index field)
508  */
509 #define NETAPI_DMA_INFRASTRUCTURE 0
510 /**
511  * @def NETAPI_DMA_NETCP
512  * @ingroup cfg_constants
513  *      This define us usee specify a flow in the NETCP CPPI DMA (for dma_index field)
514  */
515 #define NETAPI_DMA_NETCP 1
517    int              recv_offset;    /**< start of packet offset */
519    int              block;          /**< TRUE => DMA will wait for free descriptor if heap(s) are empty.
520                                          FALSE => DMA will discard */
521 /**
522  * @def NETAPI_FLOW_DROP
523  * @ingroup cfg_constants
524  *      This define is used to indicate that the flow should institute a Block policy.
525  *      This means that the DMA should wait for a free descriptor/buffer to come available if
526  *      the free poll is empty (for the block field)
527  */
528 #define NETAPI_FLOW_BLOCK 1
529 /**
530  * @def NETAPI_FLOW_DROP
531  * @ingroup cfg_constants
532  *      This define us used to indicate that the flow should institute a Drop policy.
533  *      This means that the DMA should NOT wait for a free descriptor/buffer to come available
534  *      if the free poll is empty. The transfer will be aborted and the data will dropped (for block field)
535  */
536 #define NETAPI_FLOW_DROP 0
538    PKTIO_HANDLE_T * p_dest_q;       /**<destination queue for this flow (may be overwrritten by source DMA) */
539 } NETCP_CFG_FLOW_CONFIG_T;
541  /**
542  *  @ingroup cfg_structures
543  * @brief
544  *  The structure contains the NETAPI Physical Memory Address Device configuration for
545  *  QMSS and PASS Perihperals.
546  *
547  * @details
548  *  The structure contains the NETAPI Physical Memory Address Device configuration for
549  *  QMSS and PASS Perihperals.
550  */
551 typedef struct NETCP_CFG_GLOB_DEVICE_PARAMS_Tag
553     int         fNssGen2;           /**< 1: NSS Gen2 device */
554     uint32_t    cslNetCpCfgRegs;    /**< Base address of NETCP configuration Registers */
555     uint32_t    cslQmssCfgBase;     /**< Base address of QMSS configuration Registers */
556     uint32_t    cslQmssDataBase;    /**< Base address of QMSS Data Registers */
557     uint32_t    cslNetCpCfgSaCfgRegs;/**< Base address of SA configuration Registers */
559 } NETCP_CFG_GLOB_DEVICE_PARAMS_T;
564 /**
565  *  @ingroup cfg_functions
566  *  @brief netapi_netcpCfgAddFlow   API to add a flow
567  * 
568  *  @details This api is used to add a flow
569  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
570  *  @param[in]  n    number of Pktlib_HeapHandle
571  *  @param[in]  handles[]   Handles to Pktlib_HeapHandle
572  *  @param[in]  sizes[]     must be <= heap corresponding heap size-recv_offset-any desired tail room
573  *  @param[in]  p_cfg   @ref NETCP_CFG_FLOW_CONFIG_T
574  *  @param[out] err     pointer to error return
575  *  @retval     NETCP flow handle, @ref NETCP_CFG_FLOW_HANDLE_T
576  *  @pre       @ref netapi_init
577  */
578 NETCP_CFG_FLOW_HANDLE_T netapi_netcpCfgAddFlow(NETAPI_T h,
579                                             int n, 
580                                             Pktlib_HeapHandle handles[],
581                                             int sizes[],
582                                             NETCP_CFG_FLOW_CONFIG_T * p_cfg,
583                                             int * err );
585 /**
586  *  @ingroup cfg_functions
587  *  @brief netapi_netcpCfgDelFlow   API to delete a flow
588  * 
589  *  @details This api is used to delete a flow.
590  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
591  *  @param[in]  p    handle to NETCP  flow
592  *  @param[out] err     pointer to error return
593  *  @retval     none
594  *  @pre       @ref netapi_init, netapi_netcpCfgAddFlow
595  */
596 void netapi_netcpCfgDelFlow(NETAPI_T h ,
597                                             NETCP_CFG_FLOW_HANDLE_T p ,
598                                             int * err);
600 /**
601  *  @ingroup cfg_functions
602  *  @brief  API attaches an IP address and qualifier to a MAC interface
603  * 
604  *  @details This api is used to add an IP address to a MAC interface along
605  *            with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
606  *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
607  *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables.
608  *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
609  *            Note: An IP address must be attached to enable NETCP receive Checksum offload feature
610  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
611  *  @param[in]  iface_no    interface number (0,1,..)
612  *  @param[in]  ipType  type of IP address (V4 for V6)
613  *  @param[in]  ip_addr destination or local
614  *  @param[in]  ip_rem_addr source or remote
615  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
616  *                              diffserv category for example.
617  *  @param[in]  route       handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
618  *  @param[in]  user_data     Optional: pointer to user provided data associated with IP
619  *  @param[in]  ip_addr remote
620  *  @param[out] err     pointer to error return
621  
622  *  @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
623  *  @pre       @ref netapi_init
624  */
625 NETCP_CFG_IP_T  netapi_netcpCfgAddIp(NETAPI_T                   h,
626                                      int                        iface_no,
627                                      nwal_IpType                ipType,
628                                      nwalIpAddr_t*              ip_addr,
629                                      nwalIpAddr_t*              ip_rem_addr,
630                                      nwalIpOpt_t*               ip_qualifiers,
631                                      NETCP_CFG_ROUTE_HANDLE_T   route,
632                                      void*                      user_data,
633                                      int*                       err);
635 /**
636  *  @ingroup cfg_functions
637  *  @brief netapi_netcpCfgDelIp   API to delete IP interface
638  * 
639  *  @details This api is used to delete an IP interface
640  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
641  *  @param[in]  iface_no    interface number (0,1,..)
642  *  @param[in]  ipType  type of IP address (V4 for V6)
643  *  @param[in]  ip_addr      ip_address
644  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
645  *                  diffserv category for example.
646  *  @param[in]  ip_rule_id      @ref NETCP_CFG_IP_T
647  *  @param[out] err     pointer to error return
648  *  @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
649  *  @pre       @ref netapi_init , @ref netapi_netcpCfgAddIp
650  */
651 void netapi_netcpCfgDelIp(NETAPI_T          h, 
652                           int               iface_no,
653                           nwal_IpType       ipType,
654                           nwalIpAddr_t*     ip_addr,
655                           nwalIpOpt_t*      ip_qualifiers, 
656                           NETCP_CFG_IP_T    ip_rule_id,
657                           int*              err);
659 /**
660  *  @ingroup cfg_functions
661  *  @brief netapi_netcpCfgCreateMacInterface  API to insert a MAC interface rule in the NETCP hardware
662  *  lookup engines.
663  * 
664  *  @details This api is used to insert a MAC interface in the NETCP hardware lookup engines.
665  *      Once it is created, the MAC interface can be used to receive packets. The API
666  *      adds a rule to the NETCP 1st level lookup tables to route all packets with destination
667  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netapi_netcpCfgAddIp) to
668  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
669  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
670  *      Note: The internal SOC switch (if operating in full swithc mode) may need to  be "taught" that this mac
671  *      address is present by transmitting a packet with destination mac = this interface mac address.
672  *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
673  *  @param[in]  p_mac   pointer to 6 byte MAC address for local interface
674  *  @param[in]  p_mac_remote   pointer to 6 byte MAC address for remote interface
675  *  @param[in]  iface_no    interface number (0,1,..) 
676  *  @param[in]  switch_port     (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported currenly] 
677  *  @param[in]  route   handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
678  *  @param[in]  vlan    [future[ vlan configuration . Set to NULL, @ref NETCP_CFG_VLAN_T
679  *  @param[in]  etherType  Ethertype field.
681  *  @param[in]  state   [future] interface state (0=down, 1= up)
682  *  @param[out] err     pointer to error return
683  *  @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
684  *  @pre       @ref netapi_init 
685  */
686 NETCP_CFG_MACIF_T  netapi_netcpCfgCreateMacInterface(NETAPI_T                   h,
687                                                      uint8_t*                   p_mac,
688                                                      uint8_t*                   p_mac_remote,
689                                                      int                        iface_no,
690                                                      int                        switch_port,
691                                                      NETCP_CFG_ROUTE_HANDLE_T   route,
692                                                      NETCP_CFG_VLAN_T           vlan,
693                                                      uint16_t                   etherType,
694                                                      int                        state,
695                                                      int *                      err);
697 /**
698  *  @ingroup cfg_functions
699  *  @brief netapi_netcpCfgDelMac   API to delete MAC  interface
700  * 
701  *  @details This api is used to delete a MAC interface
702  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
703  *  @param[in]  iface_no    interface number (0,1,..)
704  *  @param[out] err     pointer to error return
705  *  @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
706  *  @pre       @ref netapi_init , @ref netapi_netcpCfgCreateMacInterface 
707  */
708 void netapi_netcpCfgDelMac(NETAPI_T     h,
709                            int          iface_no,
710                            int*         err);
713 /**
714  * @brief This defines handle to installed classifier returned by API.  Pkts matching this classifier will have meta data with this tag.
715  *  Also used to delete classifier
716  */
717 typedef uint32_t NETCP_CFG_CLASS_T;
720 /**
721  *  @ingroup cfg_structures
722  *  @brief NETAPI Class L4 Configuration
723  *
724  *  @details This structure contains Classifier L4 Configuration. In this type of classifier, the  L2 and L3 header match criteria are implied by the iface and ip entries.  L4 packet match criteria are defined by the proto and appProto fields ( L4 protocol id and ports)
725  */
726 typedef struct NETCP_CFG_CLASS_L4_Tag
728     int                 iface;      /**< Indicates which MAC interface packet should be received on*/
729     NETCP_CFG_IP_T      ip;         /**< IP rule to match: see @ref NETCP_CFG_IP_T */
730     nwal_appProtoType_t proto;      /**< L4 proto (-1 for don't care)*/
731     nwalAppProto_t      appProto;   /**< L4 Ports or equivalent */
733 } NETCP_CFG_CLASS_L4_T;
736 /**
737  *  @ingroup cfg_structures
738  *  @brief NETAPI Classifier L4 plus IPSEC policy configuration
739  *
740  *  @details This structure contains Classifier L4 plus IPSEC policy configuration. In this type of classifier, the  L2,L3 header match criteria are implied by the iface and ip_policy fields. The L4 match criteria are implied by the proto and appProto fields. 
741  */
742 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
743 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
745     int                       iface;      /**< Indicates which MAC interface packet should be received from */
746     NETCP_CFG_IPSEC_POLICY_T  ip_policy;  /**< IPSEC policy configuration. see @ref NETCP_CFG_IPSEC_POLICY_T */
747     nwal_appProtoType_t       proto;      /**< L4 proto (-1 for don't care)*/
748     nwalAppProto_t            appProto;   /**< L4 Ports or equivalent */
750 } NETCP_CFG_CLASS_L4_IPSEC_T;
754 /**
755  *  @ingroup cfg_structures
756  *  @brief NETAPI Classifier L4/L3 configuration
757  *
758  *  @details This structure contains Class L4 + L3 Classifier configuration. In this type of classifier the L2 header match criteria is implied by the iface field.  The L3 header match criteria is implied by the ipType, ip_addr and ip_qulaifier fields.  L4 match criteris is implied by the proto and appProto fields.  A failed route can be optionally included to tell NETCP what to do if the L3 portion of the classifier matches but not the L4 portion.
759  */
760 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
762     int                         iface;          /**< Indicates which MAC interface packet is from */
763     nwal_IpType                 ipType;         /**< IP address type, IPV4 or IPV6 */
764     nwalIpAddr_t*               ip_addr;        /**< IP address to match */
765     nwalIpOpt_t*                ip_qualifiers;  /**< IP address qualifiers */
766     NETCP_CFG_ROUTE_HANDLE_T    p_fail_route;   /**< What to do if L3 matches but L4 fails AND L3 is a 
767                                                      new rule.(if exisitng rule, then existing fail
768                                                      route will be used). */
769     nwal_appProtoType_t         proto;          /**< L4 proto (-1 for don't care)*/
770     nwalAppProto_t              appProto;       /**< Ports or equivalent */
771 } NETCP_CFG_CLASS_L3_L4_T;
773 /**
774  *  @ingroup cfg_structures
775  *  @brief NETAPI Classifier configuration
776  *
777  *  @details This structure contains the NETAPI classifer configuration.  This is a union of the different classifier types above
778  */
779 typedef struct NETCP_CFG_CLASSIFIER_Tag
782 /**
783  * Classifer type which can be set to one of the following defines:
784  * <br>
785  *      @ref NETCP_CFG_CLASS_TYPE_L4 , @ref NETCP_CFG_CLASS_TYPE_L3_L4, _
786  */
787     int classType;
789 /**
790  * @def NETCP_CFG_CLASS_TYPE_L4
791  * @ingroup cfg_constants
792  *      This defines classifier type to be Class L4. Class L4 classifiers specifiy the L4 protocol information of the packets to matched;  the L2,L3 portions of the classifier are implied by supplied handles from the mac interface create and IP Add APIs
793  */
794 #define NETCP_CFG_CLASS_TYPE_L4  0
796 /**
797  * @def NETCP_CFG_CLASS_TYPE_L3_L4
798  * @ingroup cfg_constants
799  *      This defines classifier type to be Class L4/L3 .  Class L3_L4 classifiers specify both the IP address (L3) and the L4 protocol information of the packets to be matched.
800  */
801 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
803      union
804     {
805         NETCP_CFG_CLASS_L3_L4_T     c_l3_l4;    /**< @ref NETCP_CFG_CLASS_L3_L4_T */
806         NETCP_CFG_CLASS_L4_T        c_l4;       /**< @ref NETCP_CFG_CLASS_L4_T */
807         NETCP_CFG_CLASS_L4_IPSEC_T  c_l4_ipsec; /**< @ref NETCP_CFG_CLASS_L4_IPSEC_T */
808     } u;                                        /**< union for classifier type configuration structure */
809 } NETCP_CFG_CLASSIFIER_T;
813 /**
814  *  @ingroup cfg_functions
815  *  @brief netapi_netcpCfgAddClass   API to attach a classifier rule to NETCP.
816  *      This can be used to route a particular packet flow to a specific PKTIO channel
817  * 
818  *  @details This api can be used to route a particular packet flow to a particular PktIO channel, using a specific 
819  *  pktLib heap, and/or have NetCP attach a tag (classifier id) to the incoming packet.
820  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
821  *  @param[in]  p_class definition of the classifier
822  *  @param[in]  p_route handle to NETCP route.
823  *  @param[in]  action       what to do with packet: one of NETCP_CFG_ACTION_TO_SW, DISCARD or CONTINUE
824  *  @param[in]  user_data     Optional: pointer to user provided data associated with SA
825  *  @param[out] err     pointer to error return
826  *  @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
827  *  @pre       @ref netapi_init
828  */NETCP_CFG_CLASS_T netapi_netcpCfgAddClass(NETAPI_T                   h,
829                                              NETCP_CFG_CLASSIFIER_T*    p_class,
830                                              NETCP_CFG_ROUTE_HANDLE_T   p_route,
831                                              int                        action,
832                                              void*                      user_data,
833                                              int*                       err);
837 /**
838  *  @ingroup cfg_functions
839  *  @brief netapi_netcpCfgDelClass   API to delete a preconfigured classifier
840  * 
841  *  @details This API can be used to delete a preconfigured classifier
842  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
843  *  @param[in]  classId
844  *  @param[out] err     pointer to error return
845  *  @retval     none
846  *  @pre       @ref netapi_init, @ref netapi_netcpCfgAddClass
847  */
848 void netapi_netcpCfgDelClass(NETAPI_T           h,
849                              NETCP_CFG_CLASS_T  classId,
850                              int*               err);
853 /**
854  *  @ingroup netapi_cb_functions
855  *  @brief NETCP_CFG_STATS_CB   Callback function that is used to return statistics from NETCP
856  * 
857  *  @details The application provides a callback function that NETAPI  uses to report statistics.
858  *  The request for stats is generated from the @ref netapi_netcpCfgReqStats API.
859  *  Note: to receive this stats callback, the @ref netapi_netcpPoll function must be called
860  *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
861  *  @param[out]  pPaStats    the PA (NETCP packet accelerator subsystem) statistics block 
862  *  @retval     none 
863  *  @pre       @ref netapi_init , @ref netapi_netcpCfgReqStats, @ref netapi_netcpPoll
864  */
865 typedef void (*NETCP_CFG_STATS_CB)(NETAPI_T      h,
866                                    paSysStats_t* pPaStats);
868 /**
869  *  @ingroup cfg_functions
870  *  @brief netapi_netcpCfgReqStats   API to request statistics from NETCP
871  * 
872  *  @details This api is used to request a statistics from NETCP.  This will generate a stats request
873  *  command to NETCP. Sometime later, the statistics result will arrive and will be passed to 
874  *  the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
875  *  Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
876  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
877  *  @param[in]  cb   the callback function to invoke with the resulting statistics block, @ref NETCP_CFG_STATS_CB
878  *  @param[in]  doClear     clear the stats in NETCP after the report (0=no, 1=yes) 
879  *  @param[out] err     pointer to error return
880  *  @retval     none 
881  *  @pre       @ref netapi_init 
882  */
883 void netapi_netcpCfgReqStats(NETAPI_T               h,
884                              NETCP_CFG_STATS_CB     cb,
885                              int                    doClear,
886                              int*                   err);
889 /**
890  *  @ingroup cfg_functions
891  *  @brief netapi_netcpCfgExceptions    API to configure NETCP with global rules for exception packet handling
892  *
893  *  @details This api is used to configure NETCP with global rules of how to handle exception packets specified by exception_id.
894  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
895  *  @param[in]  exception_id id of the exception packet, refer to pa.h,.pa_EROUTE_XXX for list of exception packet id's
896  *  @param[in]  p_route handle to NETCP route.
897  *  @param[in]  action, action for NETCP to take upon classifying packet as type exception, refer to nwal. nwal_matchAction_t
898  *  @retval returns app_id, @ref NETCP_CFG_EXCEPTION_PKT_T
899  *  @pre       @ref netapi_init 
900  */
901 NETCP_CFG_EXCEPTION_PKT_T netapi_netcpCfgExceptions(NETAPI_T                    h,
902                                                     int                         exception_id ,
903                                                     nwal_matchAction_t          action,
904                                                     NETCP_CFG_ROUTE_HANDLE_T    p_route);
907 #ifdef __cplusplus
909 #endif
910 #endif